Small 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.
This package exposes functionality under the reputils module. The main user‑facing component at present is reputils providing:
EmailAddressdataclass for parsing/formatting email addressesSMTPServerInfoconfiguration for SMTP host/port/TLS/etc.MRSendmailto compose and send text/HTML emails with optional attachments and headers
There 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.
- Language: Python (requires Python >= 3.12; CI uses Python 3.14)
- Packaging/build: Hatchling (
pyproject.toml) - Testing: pytest
- Lint/format: black, isort, mypy
- CI: GitHub Actions (tests/mypy workflow badge shown above) and a scheduled workflow to update a clones badge
Runtime dependencies (see pyproject.toml / requirements.txt):
loguru>=0.7.3pytz>=2025.2(packaged aspytz==2025.2inrequirements.txt)python-dateutil==2.9.*
Development dependencies (see requirements-dev.txt):
pytest,mypy,black,isort,pre-commit, and typing stubs for dateutil and pytz
Python version: >=3.12. The repo’s Makefile and CI use Python 3.14 locally/in CI.
Install from PyPI:
pip install reputils
From source (recommended for development):
git clone https://github.com/vroomfondel/reputils
cd reputils
make install
The make install target creates/uses a local .venv and installs dev requirements.
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.
from email import message_from_string
from reputils import EmailAddress, SMTPServerInfo, MRSendmail
server = SMTPServerInfo(
smtp_server="smtp.example.com",
smtp_port=587,
smtp_user="user@example.com",
smtp_pass="app-password",
use_start_tls=True,
)
mailer = MRSendmail(
serverinfo=server,
returnpath=EmailAddress(email="bounce@example.com", name="Mailer"),
senderfrom=EmailAddress(email="noreply@example.com", name="No Reply"),
subject="Hello from reputils",
)
mailer.add_to(EmailAddress.from_str("Alice <alice@example.com>"))
raw, res = mailer.send(
txt="Plain text body",
html="<p>HTML body</p>",
)
print("All recipients succeeded:", res.all_succeeded())
# Extract the Message-ID from the rendered message if you need it:
msg = message_from_string(raw)
print("Message-ID:", msg["Message-ID"]) # e.g. <20250101...@example.com>from pathlib import Path
from reputils import EmailAddress, SMTPServerInfo, MRSendmail
# Create or reuse a mailer instance (example shown inline for completeness)
server = SMTPServerInfo(smtp_server="smtp.example.com", smtp_port=587, use_start_tls=True)
mailer = MRSendmail(
serverinfo=server,
returnpath=EmailAddress(email="bounce@example.com", name="Mailer"),
senderfrom=EmailAddress(email="noreply@example.com", name="No Reply"),
subject="Monthly report",
)
mailer.add_to(EmailAddress.from_str("Alice <alice@example.com>"))
mailer.add_cc(EmailAddress.from_str("Bob <bob@example.com>"))
mailer.add_bcc(EmailAddress.from_str("carol@example.com"))
raw, res = mailer.send(
txt="Report attached.",
files=[Path("/tmp/report.txt"), Path("/tmp/plot.png")],
additional_headers={
"X-Trace-ID": "12345",
"List-Id": "example.list.example.com",
},
)
if not res.all_succeeded():
# Inspect per‑recipient SMTP errors (email, code, message)
for email, code, message in res.get_all_errors():
print(f"Failed: {email} -> {code} {message}")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 é, ñ, ą, …).
Example:
from reputils import EmailAddress, SMTPServerInfo, MRSendmail
server = SMTPServerInfo(smtp_server="smtp.example.com", smtp_port=587, use_start_tls=True)
mailer = MRSendmail(
serverinfo=server,
returnpath=EmailAddress(email="bounce@example.com", name="Mailer"),
senderfrom=EmailAddress(email="noreply@example.com", name="München Prüfstelle"),
subject="Status für Prüfstände – Größe ist größer",
)
mailer.add_to(EmailAddress(email="alice@example.com", name="Jörg Hübner"))
txt_body = "Hallo Jörg, die Größe ist größer als erwartet. Grüße aus München!"
html_body = "<p>Hallo Jörg, die Größe ist <b>größer</b> als erwartet. Grüße aus München!</p>"
raw, res = mailer.send(txt=txt_body, html=html_body)
assert res.all_succeeded()No additional configuration is required; Python’s email package handles RFC 2047/2045 encoding under the hood, and reputils sets sane UTF‑8 defaults.
from reputils import SMTPServerInfo, MRSendmail, EmailAddress
server = SMTPServerInfo(smtp_server="smtp.example.com", smtp_port=587)
mailer = MRSendmail(serverinfo=server, returnpath=EmailAddress(email="bounce@example.com"))
# Low‑level smtplib debugging for this call
raw, res = mailer.send(txt="Hello", wants_smtp_level_debug=True)
# More verbose application‑level logging from MRSendmail for this call
raw, res = mailer.send(txt="Hello", wantsdebuglogging=True)MailReport uses loguru for logging. To enable a reasonable default console configuration with a built‑in “skiplog” filter, call:
from reputils import configure_loguru_default_with_skiplog_filter
configure_loguru_default_with_skiplog_filter()See also scripts/loguru_skiplog_config_example.py for a minimal example.
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.ymlon a schedule or manual dispatch.
Environment variables required by the script/CI workflow:
GIST_TOKEN: GitHub token with permission to update the target GistGIST_ID: ID of the Gist storing history and badge JSONREPO_TOKEN: GitHub token to read repository traffic statsGITHUB_REPOSITORY: full repo slug, e.g.owner/repository
Local ad‑hoc run:
GIST_TOKEN=... GIST_ID=... REPO_TOKEN=... GITHUB_REPOSITORY=vroomfondel/reputils \
python scripts/update_badge.py
Convenience tasks are provided via Makefile:
make install– create.venvand install dev requirementsmake tests– run pytestmake tcheck– run mypy type checksmake lint– run blackmake isort– fix import ordermake prepare– run tests and pre‑commit checksmake pypibuild– build distribution withhatchling/buildmake pypipush– upload to PyPI viahatch
Note: The Makefile activates .venv automatically for these targets when not running in GitHub Actions.
make tests
Pytest is configured via pytest.ini. Current tests are minimal (see tests/test_base.py).
reputils/
├─ reputils/
│ ├─ __init__.py
│ └─ MailReport.py # Email utilities
├─ scripts/
│ └─ update_badge.py # CI helper for clone badge
├─ tests/
│ ├─ __init__.py
│ ├─ conftest.py
│ └─ test_base.py
├─ pyproject.toml # Hatchling project config
├─ requirements.txt # Runtime deps
├─ requirements-dev.txt # Dev/test tools
├─ requirements-build.txt # Build/upload tools
├─ Makefile # Dev tasks and packaging
├─ pytest.ini
├─ LICENSE
└─ README.md
- For CI badge update:
GIST_TOKEN,GIST_ID,REPO_TOKEN,GITHUB_REPOSITORY(see Scripts section). - TODO: Document any runtime configuration for
reputilsif/when added. At present, logging for thereputilslogger is disabled by default in code.
Build wheels/sdist:
make pypibuild
Upload to PyPI (requires credentials configured for hatch resp. ${HOME}/.pypirc properly filled):
make pypipush
Artifacts are produced in the dist/ directory. The version is managed in pyproject.toml.
No console scripts/entry points are currently defined in pyproject.toml.
MIT License. See the LICENSE file.
- TODO: Add a CHANGELOG or release notes.
- TODO: Document additional modules if added in the future.
This 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.