{"id":37085514,"url":"https://github.com/vroomfondel/reputils","last_synced_at":"2026-01-14T10:31:07.507Z","repository":{"id":286082887,"uuid":"570085091","full_name":"vroomfondel/reputils","owner":"vroomfondel","description":"Python utilities library for email composition \u0026 sending (SMTP, MIME, attachments) with sane defaults","archived":false,"fork":false,"pushed_at":"2025-12-14T16:07:07.000Z","size":5198,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-15T01:22:32.913Z","etag":null,"topics":["automation","ci-tools","email","email-automation","hatchling","helper-library","mime","mypy","pypi-package","pytest","python","python-library","python3","smtp","smtp-client","utilities"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/reputils/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vroomfondel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-11-24T09:57:19.000Z","updated_at":"2025-12-14T16:07:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"37f3eb93-1e99-4256-bd4a-2e45889fa218","html_url":"https://github.com/vroomfondel/reputils","commit_stats":null,"previous_names":["vroomfondel/reputils"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vroomfondel/reputils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vroomfondel%2Freputils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vroomfondel%2Freputils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vroomfondel%2Freputils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vroomfondel%2Freputils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vroomfondel","download_url":"https://codeload.github.com/vroomfondel/reputils/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vroomfondel%2Freputils/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28417395,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T10:25:19.714Z","status":"ssl_error","status_checked_at":"2026-01-14T10:22:49.371Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","ci-tools","email","email-automation","hatchling","helper-library","mime","mypy","pypi-package","pytest","python","python-library","python3","smtp","smtp-client","utilities"],"created_at":"2026-01-14T10:31:06.764Z","updated_at":"2026-01-14T10:31:07.492Z","avatar_url":"https://github.com/vroomfondel.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![mypy and pytests](https://github.com/vroomfondel/reputils/actions/workflows/mypynpytests.yml/badge.svg)\n![Cumulative Clones](https://img.shields.io/endpoint?logo=github\u0026url=https://gist.githubusercontent.com/vroomfondel/98e7e1bf08bf1bdefdcc68e96985710d/raw/reputils_clone_count.json)\n[![PyPI Downloads](https://static.pepy.tech/personalized-badge/reputils?period=total\u0026units=INTERNATIONAL_SYSTEM\u0026left_color=BLACK\u0026right_color=GREEN\u0026left_text=PyPi+Downloads)](https://pepy.tech/projects/reputils)\n\n[![https://github.com/vroomfondel/reputils/raw/main/Gemini_Generated_Image_reputils_695z2w695z2w695z_250x250.png](https://github.com/vroomfondel/reputils/raw/main/Gemini_Generated_Image_reputils_695z2w695z2w695z_250x250.png)](https://github.com/vroomfondel/reputils)\n\n# reputils\n\nSmall Python utilities packaged as a library. Currently includes helpers for assembling and sending emails (headers, MIME parts, attachments) with sane defaults, plus a small script used in CI to update a GitHub clones badge via a Gist.\n\n- Source: https://github.com/vroomfondel/reputils\n- PyPI: https://pypi.org/project/reputils/\n\n## Overview\n\nThis package exposes functionality under the `reputils` module. The main user‑facing component at present is `reputils` providing:\n\n- `EmailAddress` dataclass for parsing/formatting email addresses\n- `SMTPServerInfo` configuration for SMTP host/port/TLS/etc.\n- `MRSendmail` to compose and send text/HTML emails with optional attachments and headers\n\nThere is also a maintenance script `scripts/update_badge.py` that is run in GitHub Actions to update a Shields.io JSON endpoint with cumulative repository clone statistics.\n\n## Stack\n\n- Language: Python (requires Python \u003e= 3.12; CI uses Python 3.14)\n- Packaging/build: Hatchling (`pyproject.toml`)\n- Testing: pytest\n- Lint/format: black, isort, mypy\n- CI: GitHub Actions (tests/mypy workflow badge shown above) and a scheduled workflow to update a clones badge\n\n## Requirements\n\nRuntime dependencies (see `pyproject.toml` / `requirements.txt`):\n\n- `loguru\u003e=0.7.3`\n- `pytz\u003e=2025.2` (packaged as `pytz==2025.2` in `requirements.txt`)\n- `python-dateutil==2.9.*`\n\nDevelopment dependencies (see `requirements-dev.txt`):\n\n- `pytest`, `mypy`, `black`, `isort`, `pre-commit`, and typing stubs for dateutil and pytz\n\nPython version: `\u003e=3.12`. The repo’s Makefile and CI use Python 3.14 locally/in CI.\n\n## Installation\n\nInstall from PyPI:\n\n```\npip install reputils\n```\n\nFrom source (recommended for development):\n\n```\ngit clone https://github.com/vroomfondel/reputils\ncd reputils\nmake install\n```\n\nThe `make install` target creates/uses a local `.venv` and installs dev requirements.\n\n## Usage\n\n### Basic send (text and/or HTML)\n\n`MRSendmail.send()` now returns a tuple `(raw_message: str, result: SendResult)`. The raw string contains the fully rendered RFC 5322 message (including the generated `Message-ID` header). Use the `SendResult` helper to check whether delivery succeeded for all recipients or to inspect per‑recipient failures.\n\n```python\nfrom email import message_from_string\nfrom reputils import EmailAddress, SMTPServerInfo, MRSendmail\n\nserver = SMTPServerInfo(\n    smtp_server=\"smtp.example.com\",\n    smtp_port=587,\n    smtp_user=\"user@example.com\",\n    smtp_pass=\"app-password\",\n    use_start_tls=True,\n)\n\nmailer = MRSendmail(\n    serverinfo=server,\n    returnpath=EmailAddress(email=\"bounce@example.com\", name=\"Mailer\"),\n    senderfrom=EmailAddress(email=\"noreply@example.com\", name=\"No Reply\"),\n    subject=\"Hello from reputils\",\n)\n\nmailer.add_to(EmailAddress.from_str(\"Alice \u003calice@example.com\u003e\"))\n\nraw, res = mailer.send(\n    txt=\"Plain text body\",\n    html=\"\u003cp\u003eHTML body\u003c/p\u003e\",\n)\n\nprint(\"All recipients succeeded:\", res.all_succeeded())\n# Extract the Message-ID from the rendered message if you need it:\nmsg = message_from_string(raw)\nprint(\"Message-ID:\", msg[\"Message-ID\"])  # e.g. \u003c20250101...@example.com\u003e\n```\n\n### Cc/Bcc, attachments, and additional headers\n\n```python\nfrom pathlib import Path\nfrom reputils import EmailAddress, SMTPServerInfo, MRSendmail\n\n# Create or reuse a mailer instance (example shown inline for completeness)\nserver = SMTPServerInfo(smtp_server=\"smtp.example.com\", smtp_port=587, use_start_tls=True)\nmailer = MRSendmail(\n    serverinfo=server,\n    returnpath=EmailAddress(email=\"bounce@example.com\", name=\"Mailer\"),\n    senderfrom=EmailAddress(email=\"noreply@example.com\", name=\"No Reply\"),\n    subject=\"Monthly report\",\n)\n\nmailer.add_to(EmailAddress.from_str(\"Alice \u003calice@example.com\u003e\"))\nmailer.add_cc(EmailAddress.from_str(\"Bob \u003cbob@example.com\u003e\"))\nmailer.add_bcc(EmailAddress.from_str(\"carol@example.com\"))\n\nraw, res = mailer.send(\n    txt=\"Report attached.\",\n    files=[Path(\"/tmp/report.txt\"), Path(\"/tmp/plot.png\")],\n    additional_headers={\n        \"X-Trace-ID\": \"12345\",\n        \"List-Id\": \"example.list.example.com\",\n    },\n)\n\nif not res.all_succeeded():\n    # Inspect per‑recipient SMTP errors (email, code, message)\n    for email, code, message in res.get_all_errors():\n        print(f\"Failed: {email} -\u003e {code} {message}\")\n```\n\n### Unicode (Umlauts/Accents) work out of the box\n\n`MailReport` composes messages using UTF‑8 and quoted‑printable encodings for both headers and bodies. That means subjects, display names, and message content with Umlauts and other non‑ASCII characters are sent correctly (e.g. Ä Ö Ü ä ö ü ß, accents like é, ñ, ą, …).\n\nExample:\n\n```python\nfrom reputils import EmailAddress, SMTPServerInfo, MRSendmail\n\nserver = SMTPServerInfo(smtp_server=\"smtp.example.com\", smtp_port=587, use_start_tls=True)\nmailer = MRSendmail(\n    serverinfo=server,\n    returnpath=EmailAddress(email=\"bounce@example.com\", name=\"Mailer\"),\n    senderfrom=EmailAddress(email=\"noreply@example.com\", name=\"München Prüfstelle\"),\n    subject=\"Status für Prüfstände – Größe ist größer\",\n)\n\nmailer.add_to(EmailAddress(email=\"alice@example.com\", name=\"Jörg Hübner\"))\n\ntxt_body = \"Hallo Jörg, die Größe ist größer als erwartet. Grüße aus München!\"\nhtml_body = \"\u003cp\u003eHallo Jörg, die Größe ist \u003cb\u003egrößer\u003c/b\u003e als erwartet. Grüße aus München!\u003c/p\u003e\"\n\nraw, res = mailer.send(txt=txt_body, html=html_body)\nassert res.all_succeeded()\n```\n\nNo additional configuration is required; Python’s `email` package handles RFC 2047/2045 encoding under the hood, and `reputils` sets sane UTF‑8 defaults.\n\n### SMTP and application‑level debug logging per send\n\n```python\nfrom reputils import SMTPServerInfo, MRSendmail, EmailAddress\n\nserver = SMTPServerInfo(smtp_server=\"smtp.example.com\", smtp_port=587)\nmailer = MRSendmail(serverinfo=server, returnpath=EmailAddress(email=\"bounce@example.com\"))\n\n# Low‑level smtplib debugging for this call\nraw, res = mailer.send(txt=\"Hello\", wants_smtp_level_debug=True)\n\n# More verbose application‑level logging from MRSendmail for this call\nraw, res = mailer.send(txt=\"Hello\", wantsdebuglogging=True)\n```\n\n### Logging configuration with Loguru (optional)\n\n`MailReport` uses `loguru` for logging. To enable a reasonable default console configuration with a built‑in “skiplog” filter, call:\n\n```python\n\nfrom reputils import configure_loguru_default_with_skiplog_filter\n\nconfigure_loguru_default_with_skiplog_filter()\n```\n\nSee also `scripts/loguru_skiplog_config_example.py` for a minimal example.\n\n## Scripts and Automation\n\n- `scripts/update_badge.py`: Updates a Gist with clone history and a Shields.io JSON for a “Cumulative Clones” badge. This is executed by `.github/workflows/update-clone-badge.yml` on a schedule or manual dispatch.\n\nEnvironment variables required by the script/CI workflow:\n\n- `GIST_TOKEN`: GitHub token with permission to update the target Gist\n- `GIST_ID`: ID of the Gist storing history and badge JSON\n- `REPO_TOKEN`: GitHub token to read repository traffic stats\n- `GITHUB_REPOSITORY`: full repo slug, e.g. `owner/repository`\n\nLocal ad‑hoc run:\n\n```\nGIST_TOKEN=... GIST_ID=... REPO_TOKEN=... GITHUB_REPOSITORY=vroomfondel/reputils \\\npython scripts/update_badge.py\n```\n\n## Makefile Targets\n\nConvenience tasks are provided via `Makefile`:\n\n- `make install` – create `.venv` and install dev requirements\n- `make tests` – run pytest\n- `make tcheck` – run mypy type checks\n- `make lint` – run black\n- `make isort` – fix import order\n- `make prepare` – run tests and pre‑commit checks\n- `make pypibuild` – build distribution with `hatchling`/`build`\n- `make pypipush` – upload to PyPI via `hatch`\n\nNote: The Makefile activates `.venv` automatically for these targets when not running in GitHub Actions.\n\n## Running Tests\n\n```\nmake tests\n```\n\nPytest is configured via `pytest.ini`. Current tests are minimal (see `tests/test_base.py`).\n\n## Project Structure\n\n```\nreputils/\n├─ reputils/\n│  ├─ __init__.py\n│  └─ MailReport.py              # Email utilities\n├─ scripts/\n│  └─ update_badge.py            # CI helper for clone badge\n├─ tests/\n│  ├─ __init__.py\n│  ├─ conftest.py\n│  └─ test_base.py\n├─ pyproject.toml                 # Hatchling project config\n├─ requirements.txt               # Runtime deps\n├─ requirements-dev.txt           # Dev/test tools\n├─ requirements-build.txt         # Build/upload tools\n├─ Makefile                       # Dev tasks and packaging\n├─ pytest.ini\n├─ LICENSE\n└─ README.md\n```\n\n## Environment Variables\n\n- For CI badge update: `GIST_TOKEN`, `GIST_ID`, `REPO_TOKEN`, `GITHUB_REPOSITORY` (see Scripts section).\n- TODO: Document any runtime configuration for `reputils` if/when added. At present, logging for the `reputils` logger is disabled by default in code.\n\n## Build and Publish\n\nBuild wheels/sdist:\n\n```\nmake pypibuild\n```\n\nUpload to PyPI (requires credentials configured for `hatch` resp. `${HOME}/.pypirc` properly filled):\n\n```\nmake pypipush\n```\n\nArtifacts are produced in the `dist/` directory. The version is managed in `pyproject.toml`.\n\n## Entry Points / CLI\n\nNo console scripts/entry points are currently defined in `pyproject.toml`.\n\n## License\n\nMIT License. See the `LICENSE` file.\n\n## Changelog / Roadmap\n\n- TODO: Add a CHANGELOG or release notes.\n- TODO: Document additional modules if added in the future.\n\n## ⚠️ Disclaimer\n\nThis is a development/experimental project. For production use, review security settings, customize configurations, and test thoroughly in your environment. 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. Use at your own risk.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvroomfondel%2Freputils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvroomfondel%2Freputils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvroomfondel%2Freputils/lists"}