hermers

Open-source Python client for Hermers with REST and native gRPC in one package.

The Hermers server is private / proprietary. This repository is the public SDK only and does not include or publish server source.

Client	Import	Default endpoint
Hermes	hermers	https://hermers.aduki.pro/v1
HermesGrpc	hermers	grpc.aduki.pro:443

Requirements

• Python 3.11+

Install

pip install hermers

Quickstart (REST)

from hermers import Hermes

hermes = Hermes("hm_live_xxxxxxxxxxxxxxxxxxxxxxxx")
me = hermes.ready()
print(me.tenant, me.user)

contacts = hermes.contacts.list({"limit": 50})
print(contacts["total"])

Quickstart (gRPC)

from hermers import HermesGrpc

client = HermesGrpc("hm_live_xxxxxxxxxxxxxxxxxxxxxxxx")
client.ready()
print(client.me.tenant, client.me.user)

mailboxes = client.mail.list_mailboxes()
print(len(mailboxes.items))
client.close()

For resource-by-resource examples, see docs/rest/README.md and docs/grpc/README.md.

Authentication

API key only:

• REST: Authorization: Key <key>
• gRPC metadata: authorization: Key <key>

The SDK does not expose login, password, or JWT refresh helpers. Prefer ready() before the first resource call. Callers never pass tenant/user hex for scoped resource methods because both clients cache whoami.

Resources

REST properties:

• contacts
• mail
• keys
• user
• tenant
• calendar
• events
• feeds
• scheduling

gRPC properties:

• contacts
• mail
• feeds
• storage
• sync
• security
• spam
• tier
• usage
• session

The clean top-level API stays available via hermers.Hermes / hermers.HermesGrpc, while the implementation is organized under hermers.rest.* and hermers.grpc.*.

Testing

PYTHONPATH=src python3 -m unittest discover -s tests -v
# for live tests, set the API-key environment variable expected by the test suite
PYTHONPATH=src python3 -m unittest discover -s tests -v

Without a live API key configured, the unit suites still run and the live REST/gRPC tests no-op. Never commit secrets or local environment files.

Docs

Developer docs live under docs/ and publish with mdBook.

The book source is assembled from docs/ plus this repository README.md into book/, then built into site/ for GitHub Pages.

Requires mdbook on PATH.

make docs-prepare
make docs-build
make docs-check
make docs-serve
make docs

License

MIT