Metadata-Version: 2.5
Name: j8yte-toolbox
Version: 1.0.1
Summary: A Python module that provides static methods designed to simplify the export of Excel files, communication on Slack, sending emails, executing HTTP requests, creating HTML documents, and more.
Project-URL: Homepage, https://github.com/j8yte/j8yte-toolbox
Project-URL: Bug-Tracker, https://github.com/j8yte/j8yte-toolbox/issues
Author-email: j8yte <j8ytes@gmail.com>
License-File: LICENSE.txt
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.13
Requires-Dist: hvac~=2.4
Requires-Dist: mailgun~=1.10
Requires-Dist: openpyxl~=3.1
Requires-Dist: pandas~=3.1
Requires-Dist: requests~=2.34
Requires-Dist: tzdata~=2026.6
Requires-Dist: xhtml2pdf~=0.2
Requires-Dist: xlsxwriter~=3.3
Description-Content-Type: text/markdown

# j8yte-toolbox

A general-purpose and modern Python toolkit designed to simplify common API interactions, file manipulation (Excel, PDF, Base64), notification delivery (Slack, Mail, Mailgun), and secure infrastructure secret management via HashiCorp Vault.

---

## 🚀 Installation & Integration

Add the module to your project managed with **uv**:

```bash
uv add j8yte-toolbox
```

---

## 🛠️ Classes & Features Reference

### 1. `Api` (HTTP Requests)
Provides a robust wrapper over `requests` featuring a native automatic retry strategy in case of infrastructure issues (HTTP codes 429, 500, 502, 503, 504).

*   **`basic_auth_header(user, password)`**: Generates a Basic HTTP authentication token encoded in Base64.
*   **`request(method, host, entry_point, ...)`**: Executes a secure HTTP request using reusable custom sessions.

```python
from j8yte_toolbox import Api

# Example of a secure GET request
response = Api.request(
    method="GET",
    host="example.com",
    entry_point="/api/something",
    headers={"Accept": "application/json"}
)
```

### 2. `Base` (Low-Level Utilities)
Utility functions for type conversion, timezones, and physical files.

*   **`str2bool(value)`**: Converts a string value (`"true"`, `"yes"`, `"1"`) into a native boolean.
*   **`get_iso_8601(date, timezone)`**: Computes the dynamic daylight saving offset (summer/winter) for a given UTC date.
*   **`bin_to_base64(src, dest)`** / **`base64_to_bin(text, dest)`**: Bidirectional conversion of binary files.

### 3. `Excel` (XLSX Manipulation)
Facilitates stylized exportation and reading of spreadsheets using `xlsxwriter` and `pandas`.

*   **`export(file, data)`**: Exports a list of dictionaries into a pre-formatted Excel spreadsheet (blue headers, automatic filters, and auto-adjusted columns).
*   **`read(file, sheet, no_headers)`**: Reads an Excel file and returns its content as a clean Python `list[dict]`.

```python
from j8yte_toolbox import Excel

data = [{"Key1": "abc", "Key2": "123"}, {"Key1": "def", "Key2": "456"}]
Excel.export("report.xlsx", data)
```

### 4. `Html` (Document & Chart Generation)
Allows the dynamic generation of lightweight HTML documents for emails or document conversion. Features a semantic CSS mapping system that automatically applies visual classes (`ok`, `warn`, `crit`, `ongoing`) based on text status keywords or numeric thresholds.

*   **`create_doc(body, layout, font_size)`**: Generates a complete HTML5 document integrating a stylesheet compatible with demanding email clients.
*   **`create_table(data, empty_blank)`**: Automatically converts dictionaries into dynamically colored HTML tables.
*   **`create_separator()`**: Creates an HTML separator compatible with legacy Outlook desktop clients.
*   **`create_pie_chart(...)`** / **`create_bar_chart(...)`**: Generates chart image tags pointing to the remote QuickChart API.
*   **`color_class(value, invert, empty_blank)`**: Evaluates string or numeric values to return the appropriate CSS class.
*   **`create_label(title, value)`**: Generates a formatted HTML stat box with a title and a value.

### 5. `Jsm` (Atlassian Jira Service Management Integration)
Utilities dedicated to manipulating complex structures for Jira forms and injecting formatted comments using the Atlassian Document Format (ADF) schema.

*   **`form_select(field, data, return_unknown_if_empty)`**: Parses and cleans choice-based text answers from Jira forms.
*   **`create_table(headers, data, text, colwidth)`**: Generates the structural JSON dictionary representing a data table, ready to be sent via the JSM Comment API.

### 6. `Mail` & `Mailgun` (Email Services)
Two messaging alternatives tailored to your infrastructure delivery requirements.

*   **`Mail.send(...)`**: Dispatches HTML emails via a standard SMTP server relay (supports TLS encryption and authentication). Supports file attachments.
*   **`Mailgun.send(...)`**: Dispatches transactional messages via the high-availability Mailgun REST API, supporting dynamic lists of file attachments.

### 7. `Pdf` (Document Export)
Provides straightforward exporting tools to save HTML content directly into portable documents.

*   **`export(file, html_doc)`**: Converted raw HTML structures into a physical formatted PDF binary file using `xhtml2pdf`.

### 8. `Slack` (Communications & Block Kit)
Complete management of interactions with the Slack collaboration platform.

*   **`send(host, token, channel, blocks, text)`**: Sends a simple text message or a complex layout interface using Slack Block Kit structures.
*   **`delete(host, token, channel, timestamp)`**: Deletes a specific message in a Slack channel using its unique timestamp identifier.
*   **`send_attachment(host, token, channel, filepath, blocks)`**: Handles Slack's 3-step file upload workflow to securely upload local attachments directly into a channel.
*   **`delete_attachment(host, token, file_id)`**: Programmatically removes an uploaded attachment from Slack using its file identifier.
*   **`create_table(data)`**: Translates a 2-column Python dataset into structural Slack Markdown table blocks.
*   **`create_list(data, simple)`**: Transforms data into a structural Slack list layout (either bulleted rich text blocks or simple markdown rows).

### 9. `Vault` (Secure Secrets Management)
Seamlessly interfaces with **HashiCorp Vault** within automated tasks, eliminating hardcoded passwords and tokens from your repository.

*   **`get(reqs, url, role, token, mount_point)`**: Authenticates the client and batch-extracts secrets from the Vault KV v2 secret engine.

```python
from j8yte_toolbox import Vault

# Automatic secret retrieval
my_requests = [{"path": "my-project/tokens", "key": "slack_api_token"}]
retrieved_secrets = Vault.get(my_requests)
```

---

## 🔒 Pipeline Environment Variables

To operate seamlessly within your CI/CD automated jobs (specifically GitLab CI), the `Vault` class listens to the following standardized environment variables:

| Variable Name | Description | Example |
| :--- | :--- | :--- |
| `VAULT_SERVER_URL` | The network URL of your secure HashiCorp Vault instance. | `https://company.com` |
| `VAULT_AUTH_ROLE` | The authentication role name configured in Vault for GitLab CI. | `gitlab-ci-read-role` |
| `VAULT_ID_TOKEN` | The temporary OIDC JWT token automatically supplied by the GitLab Runner. | *(Generated by GitLab)* |

---

## 📝 License

This project is licensed under the **MIT** License. See the `LICENSE` file for more details.
