j8yte-toolbox 1.0.0.dev0__tar.gz

j8yte_toolbox-1.0.0.dev0/.gitlab-ci.yml

@@ -0,0 +1,83 @@
+include: 
+  - project: 'lab-semifer/templates/gitlab-ci'
+    file: '.python-vault.yml'
+
+stages:
+  - linting
+  - testing
+  - build
+  - deploy
+
+variables:
+  UV_LINK_MODE: "copy"
+  GIT_DEPTH: "0"
+
+ruff:
+  stage: linting
+  script:
+    - uv run --group dev ruff check .
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+      when: always
+    - if: $CI_COMMIT_BRANCH != "main"
+
+pytest:
+  stage: testing
+  script:
+    - uv run --group dev pytest --cov=src --cov-report=term-missing --cov-report=html:htmlcov
+  coverage: '/TOTAL.*\s+(\d+)\%/'
+  artifacts:
+    paths:
+      - htmlcov/
+    expire_in: 1 week
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+      when: always
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: always
+
+build-package:
+  stage: build
+  script:
+    - uv build
+  artifacts:
+    paths:
+      - dist/
+    expire_in: 1 week
+  rules:
+    - if: '$CI_COMMIT_TAG'
+
+pages:
+  stage: deploy
+  image: alpine:latest
+  script:
+    - mkdir -p public
+    - cp -r htmlcov/* public/
+  artifacts:
+    paths:
+      - public/
+    expire_in: 30 days
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+      when: always
+
+pypi-publish:
+  stage: deploy
+  needs:
+    - job: vault
+    - job: build-package
+  script:
+    - |
+      VAULT_CLIENT_TOKEN=$(uv run python -c "
+      import urllib.request, json
+      req = urllib.request.Request('${VAULT_SERVER_URL}/v1/auth/jwt/login', data=json.dumps({'jwt': '${VAULT_ID_TOKEN}', 'role': '${VAULT_AUTH_ROLE}'}).encode())
+      print(json.loads(urllib.request.urlopen(req).read())['auth']['client_token'])
+      ")
+      export UV_PUBLISH_TOKEN=$(uv run python -c "
+      import urllib.request, json
+      req = urllib.request.Request('${VAULT_SERVER_URL}/v1/kv/data/pypi', headers={'X-Vault-Token': '${VAULT_CLIENT_TOKEN}'})
+      print(json.loads(urllib.request.urlopen(req).read())['data']['data']['token'])
+      ")
+    - uv publish
+  rules:
+    - if: '$CI_COMMIT_TAG'

j8yte_toolbox-1.0.0.dev0/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2026 j8yte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

j8yte_toolbox-1.0.0.dev0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: j8yte-toolbox
+Version: 1.0.0-dev
+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.

j8yte_toolbox-1.0.0.dev0/README.md

@@ -0,0 +1,123 @@
+# 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.

j8yte_toolbox-1.0.0.dev0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+fallback-version = "1.0.0-dev"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/j8yte_toolbox"]
+
+[project]
+name = "j8yte-toolbox"
+dynamic = ["version"]
+description = "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."
+readme = "README.md"
+requires-python = ">=3.13"
+authors = [
+    { name = "j8yte", email = "j8ytes@gmail.com" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Utilities",
+    "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = [
+    "mailgun~=1.10",
+    "requests~=2.34",
+    "tzdata~=2026.6",
+    "xlsxwriter~=3.3",
+    "pandas~=3.1",
+    "openpyxl~=3.1",
+    "hvac~=2.4",
+    "xhtml2pdf~=0.2"
+]
+
+[project.urls]
+Homepage = "https://github.com/j8yte/j8yte-toolbox"
+Bug-Tracker = "https://github.com/j8yte/j8yte-toolbox/issues"
+
+[dependency-groups]
+# Dépendances de développement
+dev = [
+    "pytest~=9.2",
+    "pytest-cov~=7.1",
+    "ruff~=0.17",
+]
+
+[tool.ruff]
+target-version = "py313"
+line-length = 88
+exclude = ["tests"]
+
+[tool.ruff.lint]
+# E/W (Pycodestyle), F (Pyflakes), I (Isort), UP (Pyupgrade), B (Bugbear)
+select = ["E", "W", "F", "I", "UP", "B"]
+ignore = []
+
+[tool.ruff.lint.isort]
+known-first-party = ["j8yte_toolbox"]

j8yte_toolbox-1.0.0.dev0/src/j8yte_toolbox/__init__.py

@@ -0,0 +1,14 @@
+from .core import Api, Base, Excel, Html, Jsm, Mail, Mailgun, Pdf, Slack, Vault
+
+__all__ = [
+    "Api",
+    "Base",
+    "Excel",
+    "Html",
+    "Jsm",
+    "Mail",
+    "Mailgun",
+    "Pdf",
+    "Slack",
+    "Vault"
+]