Metadata-Version: 2.1
Name: mecsimcalc
Version: 0.0.5
Summary: Useful functions for MecSimCalc.com
Author: MecSimCalc
Author-email: <info@mecsimcalc.com>
Keywords: python,MecSimCalc,Calculator,Simple
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Description-Content-Type: text/markdown
Provides-Extra: dev
License-File: LICENSE


# Mecsimcalc 0.0.5 documentation

This library is designed to provide a set of functions for handling and converting various types of data, such as base64 encoded data, Pandas DataFrames, and Pillow images.

- [GitHub Repository](https://github.com/MecSimCalc/MecSimCalc-utils)
- [PyPi Page](https://pypi.org/project/mecsimcalc/)

## General

<div style="display: flex; justify-content: space-between; align-items: center;">
  <h3 style="margin: 5px; padding: 0;">decode_file_data</h3>
  <a href="https://github.com/MecSimCalc/MecSimCalc-utils/blob/main/mecsimcalc/input_utils.py#LL8C1-L30C1" style="font-size: larger; margin-bottom: 2em; margin: 5px; padding: 0;"><strong>[Source]</strong></a>
</div>

```python
def decode_file_data(encoded_data, metadata = False)
```

#### Description:

Converts a base64 encoded file into a file object and metadata

#### Arguments:

| Argument           | Type                | Description                                                     |
| ------------------ | ------------------- | --------------------------------------------------------------- |
| **`encoded_data`** | **str**             | Base64 encoded file data                                        |
| **`metadata`**     | **bool** (optional) | If True, function returns file and metadata (Defaults to False) |

#### Returns:

| Return Type             | Description                   | Condition         |
| ----------------------- | ----------------------------- | ----------------- |
| **`io.BytesIO`**        | The decoded file data         | metadata is False |
| **`(io.BytesIO, str)`** | The decoded file and metadata | metadata is True  |

#### Example:

```python
>>> inputFile = inputs['file']
>>> file, metadata = decode_file_data(inputFile, metadata = True)
>>> print(metadata)
data:image/jpeg;base64,
>>> type(file)
<class '_io.BytesIO'>
```

<div style="display: flex; justify-content: space-between; align-items: center;">
  <h3 style="margin: 5px; padding: 0;">download_text</h3>
  <a href="https://github.com/MecSimCalc/MecSimCalc-utils/blob/main/mecsimcalc/output_utils.py#LL182C1-L214C1" style="font-size: larger; margin-bottom: 2em; margin: 5px; padding: 0;"><strong>[Source]</strong></a>
</div>

```python
def download_text(
    text: str,
    filename: str = "myfile",
    extension: str = ".txt",
    download_text: str = "Download File",
) -> str:
```

#### Description:

Generates a downloadable text file containing the given text

#### Arguments:

| Argument            | Type               | Description                                                                   |
| ------------------- | ------------------ | ----------------------------------------------------------------------------- |
| **`text`**          | **str**            | The text to be downloaded                                                     |
| **`filename`**      | **str** (optional) | The name of the file to be downloaded (Defaults to "myfile")                  |
| **`extension`**     | **str** (optional) | The file extension of the file to be downloaded (Defaults to ".txt")          |
| **`download_text`** | **str** (optional) | The text to be displayed on the download button (Defaults to "Download File") |

#### Returns:

| Return Type | Description                           |
| ----------- | ------------------------------------- |
| **`str`**   | The HTML code for the download button |

#### Example:

#### Python

```python
>>> downloadLink = download_text("Hello World!")
>>> return {"downloadLink": downloadLink}
```

#### Jinja2

```python
# outputs.downloadLink is the html download link generated by the function
{{ outputs.downloadLink }}
```

## Tables/DataFrames

<div style="display: flex; justify-content: space-between; align-items: center;">
  <h3 style="margin: 5px; padding: 0;">file_to_dataframe</h3>
  <a href="https://github.com/MecSimCalc/MecSimCalc-utils/blob/main/mecsimcalc/input_utils.py#LL32C1-L52C14" style="font-size: larger; margin-bottom: 2em; margin: 5px; padding: 0;"><strong>[Source]</strong></a>
</div>

```python
def file_to_dataframe(file_data):
```

#### Description:

Converts a file object into a pandas DataFrame

#### Arguments:

| Argument        | Type           | Description                                          |
| --------------- | -------------- | ---------------------------------------------------- |
| **`file_data`** | **io.BytesIO** | Decoded file data (e.g. from **`decode_file_data`**) |

#### Raises:

| Exception                   | Description                                                                                                 |
| --------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **`pd.errors.ParserError`** | If the file data cannot be converted to a DataFrame (i.e. file is not an Excel or CSV file or is corrupted) |

#### Returns:

| Return Type        | Description                      |
| ------------------ | -------------------------------- |
| **`pd.DataFrame`** | DataFrame created from file data |

#### Example:

```python
>>> inputFile = inputs['file']
>>> file = decode_file_data(inputFile)
>>> df = file_to_dataframe(file)
>>> print(df)
   A  B  C
0  a  b  c
1  d  e  f
```

<div style="display: flex; justify-content: space-between; align-items: center;">
  <h3 style="margin: 5px; padding: 0;">input_to_dataframe</h3>
  <a href="https://github.com/MecSimCalc/MecSimCalc-utils/blob/main/mecsimcalc/input_utils.py#LL55C1-L67C39" style="font-size: larger; margin-bottom: 2em; margin: 5px; padding: 0;"><strong>[Source]</strong></a>
</div>

```python
def input_to_dataframe(file):
```

#### Description:

Converts a base64 encoded file data into a pandas DataFrame

#### Arguments:

| Argument   | Type    | Description              |
| ---------- | ------- | ------------------------ |
| **`file`** | **str** | Base64 encoded file data |

#### Returns:

| Return Type        | Description                      |
| ------------------ | -------------------------------- |
| **`pd.DataFrame`** | DataFrame created from file data |

#### Example:

```python
>>> inputFile = inputs['file']
>>> df = input_to_dataframe(inputFile)
>>> print(df)
   A  B  C
0  a  b  c
1  d  e  f
```

<div style="display: flex; justify-content: space-between; align-items: center;">
  <h3 style="margin: 5px; padding: 0;">print_dataframe</h3>
  <a href="https://github.com/MecSimCalc/MecSimCalc-utils/blob/main/mecsimcalc/output_utils.py#LL10C1-L67C39" style="font-size: larger; margin-bottom: 2em; margin: 5px; padding: 0;"><strong>[Source]</strong></a>
</div>

```python
def print_dataframe(
    df,
    download = False,
    DownloadText = "Download Table",
    DownloadFileName = "mytable",
    FileType = "csv",
):
```

#### Description:

Creates an HTML table and a download link for a given DataFrame

#### Arguments:

| Argument               | Type                | Description                                                             |
| ---------------------- | ------------------- | ----------------------------------------------------------------------- |
| **`df`**               | **pd.DataFrame**    | DataFrame to be converted                                               |
| **`download`**         | **bool** (optional) | If True, function returns a download link (Defaults to False)           |
| **`DownloadText`**     | **str** (optional)  | Text to be displayed as the download link (Defaults to "Download File") |
| **`DownloadFileName`** | **str** (optional)  | Name of file when downloaded (Defaults to "myfile")                     |
| **`FileType`**         | **str** (optional)  | File type of download (Defaults to "csv")                               |

#### Returns:

| Return Type           | Description                 | Condition         |
| --------------------- | --------------------------- | ----------------- |
| **`str`**             | HTML table                  | download is False |
| **`Tuple[str, str]`** | (HTML table, download link) | download is True  |

#### Example:

#### Python Code:

```python
>>> inputFile = inputs['file']
>>> df = input_to_dataframe(inputFile)
>>> table, download = print_dataframe(df, download = True, DownloadFileName = "FunkyTable", DownloadText = "Download My Funky Table HERE!", FileType = "xlsx")
>>> return {
        "table":table,
        "download":download,
    }
```

#### Output using Jinja2 Template:

```python
# outputs.table is the HTML table
Displaying Table
{{ outputs.table }}

# outputs.download is the download link
Downloading Table
{{ outputs.download }}
```

<div style="display: flex; justify-content: space-between; align-items: center;">
  <h3 style="margin: 5px; padding: 0;">table_to_dataframe</h3>
  <a href="https://github.com/MecSimCalc/MecSimCalc-utils/blob/main/mecsimcalc/input_utils.py#LL89C1-L105C35 style="font-size: larger; margin-bottom: 2em; margin: 5px; padding: 0;"><strong>[Source]</strong></a>
</div>

```python
def table_to_dataframe(columns: List[List[str]], column_headers: List[str]) -> pd.DataFrame:
```

#### Description:

Creates a DataFrame from given columns and headers

#### Arguments:

| Argument             | Type                | Description                                                                        |
| -------------------- | ------------------- | ---------------------------------------------------------------------------------- |
| **`columns`**        | **List[List[str]]** | List of columns to be converted into a DataFrame. Each column is a list of strings |
| **`column_headers`** | **List[str]**       | List of column headers                                                             |

#### Returns:

| Return Type        | Description                                |
| ------------------ | ------------------------------------------ |
| **`pd.DataFrame`** | DataFrame created from columns and headers |

#### Example:

```python
>>> columns = [["a", "b", "c"], ["d", "e", "f"]]
>>> column_headers = ["A", "B", "C"]
>>> df = table_to_dataframe(columns, column_headers)
>>> print(df)
   A  B  C
0  a  b  c
1  d  e  f

```

<div style="display: flex; justify-content: space-between; align-items: center;">
  <h3 style="margin: 5px; padding: 0;">print_table</h3>
  <a href="https://github.com/MecSimCalc/MecSimCalc-utils/blob/main/mecsimcalc/output_utils.py#LL216C1-L240C114" style="font-size: larger; margin-bottom: 2em; margin: 5px; padding: 0;"><strong>[Source]</strong></a>
</div>

```python
print_table(rows: List[List[str]], column_headers: List[str]):
```

#### Description:

Creates an HTML table from given rows and column headers

#### Arguments:

| Argument             | Type                | Description                                                                 |
| -------------------- | ------------------- | --------------------------------------------------------------------------- |
| **`rows`**           | **List[List[str]]** | List of rows to be converted into a table. Each column is a list of strings |
| **`column_headers`** | **List[str]**       | List of column headers                                                      |

#### Returns:

| Return Type | Description                              |
| ----------- | ---------------------------------------- |
| **`str`**   | HTML table created from rows and headers |

#### Example:

#### Python Code:

```python
>>> rows = [["a", "b", "c"], ["d", "e", "f"]]
>>> column_headers = ["A", "B", "C"]
>>> table = print_table(rows, column_headers)
>>> return {
        "table":table,
    }
```

#### Output using Jinja2 Template:

```python
# outputs.table is the HTML table
Displaying Table
{{ outputs.table }}
```

## Images

<div style="display: flex; justify-content: space-between; align-items: center;">
  <h3 style="margin: 5px; padding: 0;">input_to_PIL</h3>
  <a href="https://github.com/MecSimCalc/MecSimCalc-utils/blob/main/mecsimcalc/input_utils.py#LL70C1-L87C1" style="font-size: larger; margin-bottom: 2em; margin: 5px; padding: 0;"><strong>[Source]</strong></a>
</div>

```python
def input_to_PIL(file):
```

#### Description:

Converts a base64 encoded file data into a pillow image

#### Arguments:

| Argument   | Type    | Description              |
| ---------- | ------- | ------------------------ |
| **`file`** | **str** | Base64 encoded file data |

#### Returns:

| Return Type                       | Description              |
| --------------------------------- | ------------------------ |
| **`Tuple[PIL.Image.Image, str]`** | (pillow image, metadata) |

#### Example:

```python
>>> inputFile = inputs['file']
>>> img, metadata = input_to_PIL(inputFile)
>>> print(metadata)
data:image/jpeg;base64,
>>> type(file)
<class 'PIL.JpegImagePlugin.JpegImageFile'>
```

<div style="display: flex; justify-content: space-between; align-items: center;">
  <h3 style="margin: 5px; padding: 0;">print_img</h3>
  <a href="https://github.com/MecSimCalc/MecSimCalc-utils/blob/main/mecsimcalc/output_utils.py#LL70C1-L129C1 style="font-size: larger; margin-bottom: 2em; margin: 5px; padding: 0;"><strong>[Source]</strong></a>
</div>

```python
def print_img(
    img,
    metadata,
    WIDTH = 200,
    HEIGHT = 200,
    OriginalSize = False,
    download = False,
    DownloadText = "Download Image",
    ImageName= "myimg",
):
```

#### Description:

Converts a pillow image into an HTML image and a download link

#### Arguments:

| Argument           | Type                | Description                                                                        |
| ------------------ | ------------------- | ---------------------------------------------------------------------------------- |
| **`img`**          | **PIL.Image.Image** | Pillow image                                                                       |
| **`metadata`**     | **str**             | Image metadata                                                                     |
| **`WIDTH`**        | **int** (optional)  | Output width of the image in pixels (Defaults to 200)                              |
| **`HEIGHT`**       | **int** (optional)  | Output height of the image in pixels (Defaults to 200)                             |
| **`OriginalSize`** | **bool** (optional) | If True, the HTML image will be displayed in its original size (Defaults to False) |
| **`download`**     | **bool** (optional) | If True, function returns a download link (Defaults to False)                      |
| **`DownloadText`** | **str** (optional)  | The text to be displayed on the download link (Defaults to "Download Image")       |
| **`ImageName`**    | **str** (optional)  | The name of the image file when downloaded (Defaults to "myimg")                   |

#### Returns:

| Return Type           | Description                 | Condition         |
| --------------------- | --------------------------- | ----------------- |
| **`str`**             | HTML image                  | download is False |
| **`Tuple[str, str]`** | (HTML image, download link) | download is True  |

#### Example:

#### Python Code:

```python
>>> inputFile = inputs['file']
>>> img, metadata = input_to_PIL(inputFile)
>>> image, download = print_img(img, metadata, OriginalSize = True, download = True, DownloadText = "Download Image Here", ImageName = "myimage")
>>> return {
        "image":image,
        "download":download,
    }
```

#### Output using Jinja2 Template:

```python
# outputs.image is the HTML image
Displaying Image
{{ outputs.image }}

# outputs.download is the download link
Downloading Image
{{ outputs.download }}
```

<div style="display: flex; justify-content: space-between; align-items: center;">
  <h3 style="margin: 5px; padding: 0;">print_plt</h3>
  <a href="https://github.com/MecSimCalc/MecSimCalc-utils/blob/main/mecsimcalc/output_utils.py#LL131C1-L180C1" style="font-size: larger; margin-bottom: 2em; margin: 5px; padding: 0;"><strong>[Source]</strong></a>
</div>

```python
def print_plt(
    plt:,
    width = 500,
    dpi= 100,
    download= False,
    DownloadText = "Download Plot",
    DownloadFileName = "myplot",
)
```

#### Description:

Converts a matplotlib.pyplot or matplotlib.figure into an HTML image tag and optionally provides a download link for the image

#### Arguments:

| Argument               | Type                | Description                                                                 |
| ---------------------- | ------------------- | --------------------------------------------------------------------------- |
| **`plt`**              | **plt or figure**   | Matplotlib figure                                                           |
| **`width`**            | **int** (optional)  | Output width of the image in pixels (Defaults to 500)                       |
| **`dpi`**              | **int** (optional)  | Output dpi of the image in pixels (Defaults to 100)                         |
| **`download`**         | **bool** (optional) | If True, function returns a download link (Defaults to False)               |
| **`DownloadText`**     | **str** (optional)  | The text to be displayed on the download link (Defaults to "Download Plot") |
| **`DownloadFileName`** | **str** (optional)  | The name of the image file when downloaded (Defaults to "myplot")           |

#### Returns:

| Return Type           | Description                 | Condition         |
| --------------------- | --------------------------- | ----------------- |
| **`str`**             | HTML image                  | download is False |
| **`Tuple[str, str]`** | (HTML image, download link) | download is True  |

#### Example:

#### Python Code:

```python
>>> import matplotlib.pyplot as plt
>>> import numpy as np
>>> x = np.linspace(0, 2 * np.pi, 400)
>>> y = np.sin(x)
>>> fig, ax = plt.subplots()
>>> ax.plot(x, y)
>>> ax.set_title('A single plot')
>>> image, download = print_plt(fig, width = 500, dpi = 100, download = True, DownloadText = "Download Sin Function Plot", DownloadFileName = "sin(x)")
>>> return {
        "image":image,
        "download":download,
    }
```

#### Output using Jinja2 Template:

```python
# outputs.image is the HTML image
Displaying Image
{{ outputs.image }}

# outputs.download is the download link
Downloading Image
{{ outputs.download }}
```
