Commons¶
commons is a library of common functionality that is used across a broad range of apps and other libraries.
It bundles small, well-tested helpers (string, dict, date & time operators, …) with larger building blocks for
settings, database access, file storage, user management, background jobs, events with a transactional outbox and live streams.
Installation¶
The library is installed directly from GitHub and requires Python 3.14 or newer. Pin it to a release tag
(e.g. v1.0.0) or follow a major version with its branch (e.g. versions/1, always the latest 1.x release).
All releases are listed in the changelog.
# exact release
poetry add "git+https://github.com/cokeSchlumpf/lib--python-commons.git#v1.0.0"
# latest 1.x release (update with `poetry update commons`)
poetry add "git+https://github.com/cokeSchlumpf/lib--python-commons.git#versions/1"
# including the Azure storage backend
poetry add "git+https://github.com/cokeSchlumpf/lib--python-commons.git#v1.0.0[azure]"
# exact release
pip install "commons @ git+https://github.com/cokeSchlumpf/lib--python-commons.git@v1.0.0"
# latest 1.x release
pip install "commons @ git+https://github.com/cokeSchlumpf/lib--python-commons.git@versions/1"
# including the Azure storage backend
pip install "commons[azure] @ git+https://github.com/cokeSchlumpf/lib--python-commons.git@v1.0.0"
What's inside¶
| Module | Description |
|---|---|
commons.collection_operators, commons.datetime_operators, commons.dict_operators, commons.string_operators, commons.url_operators, commons.path_operators |
General-purpose helper functions. |
commons.excel_operators |
Writing pandas data frames to formatted Excel workbooks. |
commons.datastructures.tree |
A generic tree structure with rendering helpers. |
commons.settings |
Reading layered app settings from TOML files and APP__ environment variables. |
commons.database, commons.database_operators |
SQLModel/SQLAlchemy building blocks: column types, table mixins, unit of work. |
commons.storage, commons.storage_operators |
A file storage abstraction with local, SQL and Azure Blob Storage backends. |
commons.users |
User identities and role-based access control. |
jobs |
Running and tracking background jobs. |
Contributing¶
Checks and formatting are run with Poe the Poet: