wr-common-lib 0.1.4

Shared enums and optional PostgreSQL helpers for email workflows

wr-common-lib

Shared enums and optional PostgreSQL helpers for the email table.

PyPI	wr-common-lib
import	wr_common_lib

Requires Python 3.12+.

Install

pip install wr-common-lib
pip install "wr-common-lib[db]"   # adds async-db-tools

Package layout

src/wr_common_lib/
├── __init__.py          # __version__
└── email/
    ├── __init__.py      # public exports
    ├── constants.py     # MailFlow, MailStatus
    └── db_oper.py       # EmailDbOper ([db] extra)

Enums

MailFlow and MailStatus are StrEnum values aligned with PostgreSQL mail_flow / mail_status.

from wr_common_lib.email import MailFlow, MailStatus

MailFlow.OUTBOUND
MailStatus.PENDING.value
MailStatus.SENT.is_terminal

Status flows

Outbound:  PENDING → SENT | FAILED；webhook → DELIVERED | BOUNCED
Inbound:   RECEIVED → PARSED | PARSE_FAILED

EmailDbOper

Requires the [db] extra and a async-db-tools PostgresPool.

EmailDbOper is lazy-imported: from wr_common_lib.email import MailStatus does not require async-db-tools.

from wr_common_lib.email import EmailDbOper, MailFlow, MailStatus, get_email_content_hash

db_oper = EmailDbOper(pool)

task = {
    "imo": 1234567,
    "voyage_id": "...",
    "mail_from": "[e-mail]",
    "to": "[e-mail]",
    "cc": "",
    "subject": "...",
    "content": "...",
    "attachments": [],
    "content_hash": get_email_content_hash(...),  # optional
}

email_id = await db_oper.insert_email(task, MailFlow.INBOUND, MailStatus.RECEIVED)
await db_oper.update_status(email_id, MailStatus.SENT)
await db_oper.update_parsed_data(email_id, {"key": "value"})

Inbound and outbound use the same fields (to, cc, subject, content, attachments). DB columns remain mail_to / mail_cc.

Dependencies

install	brings in
wr-common-lib	—
wr-common-lib[db]	async-db-tools

Your application still owns the database URL and pool lifecycle.

Development

pip install -e ".[db]"

uv version 0.1.2          # bump before release
export UV_PUBLISH_TOKEN=pypi-...
uv build && uv publish

PyPI does not allow re-uploading the same version; always bump the version for a new release.

License

MIT — see LICENSE.