About The Project
Overview
This package was created by factoring out many reusable code artifacts from my various projects over a number of years. Since this work was not a part of a group effort, the test coverage is predictably abysmal :raised_eyebrow: and Python documentation notably absent :expressionless:. For each of my projects, which derive from a common Docker application found here, this package provides some specific and relatively powerful features to enable rapid offshoots for new ideas.
The package is organized under src/tailucas_pylib/ with the following key modules:
-
Core Modules:
__init__.py: Application bootstrap with logging, locale, configuration (viaapp.conf), and device name setup. Logs to syslog (UDP) or stdout/stderr. Optionally changes working directory toWORK_DIR.creds.py: 1Password credential management supporting both 1Password Connect Server and 1Password Service Account modes. Fetches secrets from environment variables or container secrets (/run/secrets).flags.py: Feature flag checking backed by a 1Password credential item.
-
Application Framework:
app.py: Thread base class with ZMQ relay (ZmqRelay) and worker (ZmqWorker) patterns for inter-thread communication via ZeroMQ.threads.py: Thread nanny with shutdown tracking, graceful termination, Cronitor monitoring integration, and lingering socket cleanup.handler.py: Context manager (exception_handler) that handles ZMQ connectivity,ContextTerminated,ResourceWarning, and general exceptions with optional Sentry reporting and graceful shutdown.process.py: Signal handler (SignalHandler) with subprocess execution (exec_cmd) helpers.
-
Communication:
-
Utilities:
data.py: Builds MessagePack payloads with timestamp and optional data for IPC.datetime.py: Timezone-aware timestamp creation, ISO formatting, and Unix timestamp conversion.device.py: Pydantic data model (Device) for device state with optional fields.bluetooth.py: Bluetooth adaptor detection and device ping viahcitool/l2ping.
-
AWS Integration (
aws/):__init__.py: Manages cached Boto3 sessions with STS role assumption, credential retrieval from 1Password.metrics.py: Posts CloudWatch count metrics with dimensions.
-
Command-line Tools (
tools/):config_interpol.py: Interpolates a config file with environment variables or an overlay config, outputting the resolved values.cred_tool.py: Fetches and displays a 1Password credential read from stdin.yaml_interpol.py: Processes YAML templates, substituting values from configuration sections.aws_configure.py: Generates AWS CLI configuration files from 1Password-stored credentials.
Built With
Technologies that help make this package useful:
Also:
Core Technologies:
- Python 3.11+ - Primary runtime
- 1Password Connect/Service Account - Credential management
- ZeroMQ - Inter-process communication
- RabbitMQ - Message queuing
- MessagePack - Binary serialization
- Pydantic - Data validation and modeling
- Sentry - Error tracking and monitoring
AWS Integration:
- Boto3 - AWS SDK
- CloudWatch - Metrics and monitoring
- Simple Workflow Service - Workflow orchestration (deprecated)
Development Tools:
- uv - Dependency management
- Cronitor - Cron job monitoring
Getting Started
Here is some detail about the intended use of this package.
Prerequisites
A Python project or runtime environment. Since this project is already initialized with [uv][vu-url] dependency management, I recommend that you continue to use it. Beyond the Python dependencies defined in the configuration, the package init carries hardcoded dependencies on Sentry and 1Password in order to function. Unless you want these and are effectively extending my base project, you're likely better off forking this package and cutting out what you do not need.
Installation
This package is published to the Python Package index from time to time.
Usage
I have various projects that use this tool chain. For example, my Base Project which can be run stand-alone but also serves as my Docker base image from which other projects are derived.
Testing
Tests use pytest with coverage. Some tests exercise live services (1Password Connect Server or Service Account, AWS session setup) and expect the OP_CONNECT_HOST, OP_CONNECT_TOKEN, OP_VAULT and OP_SERVICE_ACCOUNT_TOKEN environment variables. For deterministic results regardless of the ambient environment, the suite pins TZ=UTC and APP_NAME=test itself (see conftest.py).
Quick run (all extras)
uv sync --all-extras
uv run pytest
Extras matrix
Optional dependencies are organized as extras (aws, creds, dto, monitoring, mq). Using a Hatch matrix, the full test suite also runs against every combination of these extras: 32 environments, each installing the package with only that combination's dependencies.
# list the 32 test environments
uv run hatch env show
# run the whole matrix (stops at the first failing environment)
uv run hatch run test:run
# run a single combination
uv run hatch run test.aws-no-creds-dto-no-monitoring-mq:run
# remove all cached test environments
uv run hatch env prune
Tests that require an unavailable optional dependency skip themselves via pytest.importorskip, so every combination runs as much of the suite as its installed extras allow. Per-environment coverage data is written to .coverage.<env-name>.
Note that a full matrix run executes the live 1Password tests many times over, and the 1Password service-account API rate limit is shared across them. An occasional RateLimitExceeded failure during a full run is transient; re-run the affected environment to confirm.
License
Distributed under the MIT License. See LICENSE for more information.
Acknowledgments
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file tailucas_pylib-0.7.7.tar.gz.
File metadata
- Download URL: tailucas_pylib-0.7.7.tar.gz
- Upload date:
- Size: 21.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
229afec99014a5c48165aeeeabd3c25a5b9e9d48d3bfb04db968397fe5e9016e
|
|
| MD5 |
f68a02cbd87484e11f87efe95fc4cb36
|
|
| BLAKE2b-256 |
d58c12a14b378327aec3dec19799ea94ada57915bd29910a49c15d010db2dce3
|
File details
Details for the file tailucas_pylib-0.7.7-py3-none-any.whl.
File metadata
- Download URL: tailucas_pylib-0.7.7-py3-none-any.whl
- Upload date:
- Size: 27.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5a279c7fe19e7d7122d18f25eb879bd3eab49ee56d0e1ad997a7e1537c0008e5
|
|
| MD5 |
3c8683dd2e3232035a8ec4b752375fcd
|
|
| BLAKE2b-256 |
06e085196f5ca348b80870e93048a2f848ea717f1e6861c5b9cb1edd6ca8a9d3
|
