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:

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.

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].

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.

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.