Metadata-Version: 2.4
Name: rtecommon
Version: 3.3.0
Summary: Common tools/utilities/configurations used in the RealTime Events echo system.
License: Proprietary
License-File: LICENSE.txt
Author: Hendrik du Toit
Author-email: hendrik@brightedge.co.za
Maintainer: Hendrik du Toit
Maintainer-email: hendrikdt@citiqprepaid.co.za
Requires-Python: >=3.10,<3.15
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Office/Business
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: beetools (>=5.5.1,<6.0.0)
Requires-Dist: colorlog (>=6.10.1,<7.0.0)
Requires-Dist: pydantic (>=2.12.5,<3.0.0)
Requires-Dist: pydantic-settings (>=2.13.1,<3.0.0)
Requires-Dist: sqlalchemy (>=2.0.49,<3.0.0)
Project-URL: Homepage, https://github.com/RealTimeEvents/rtecommon
Project-URL: Repository, https://github.com/RealTimeEvents/rtecommon.git
Project-URL: changelog, https://github.com/RealTimeEvents/rtecommon/releases
Project-URL: issues, https://github.com/RealTimeEvents/rtecommon/issues
Description-Content-Type: text/markdown

# RealTimeEvents Common

| **Category** | **Status' and Links**                                                                                      |
| ------------ | ---------------------------------------------------------------------------------------------------------- |
| General      | [![][general_maintenance_y_img]][general_maintenance_y_lnk] [![][general_semver_pic]][general_semver_link] |
| CD/CI        | [![][cicd_codestyle_img]][cicd_codestyle_lnk]                                                              |

Shared tools, logging helpers, database bootstrap utilities, and reusable test infrastructure for the RealTime Events
ecosystem.

______________________________________________________________________

## Short Description

`rtecommon` centralises reusable project infrastructure so RealTime Events services can share configuration,
environment handling, logging behaviour, database bootstrap helpers, and test infrastructure from one maintained
package.

______________________________________________________________________

## Module Overview

### Key Features

- Shared configuration helpers for environment-driven application settings.
- Environment-backed settings models exposed from `rtecommon.configs.settings` for repo and runtime metadata.
- Shared database bootstrap helpers in `rtecommon.dbdef` for installer-role setup, database creation, session access,
  and table initialization.
- Shared session-factory configuration, context-managed session access, and runtime reset helpers in
  `rtecommon.dbdef` for consuming services and isolated test runs.
- Runtime resets preserve configurable SQLAlchemy session factories by clearing their bind instead of replacing the
  configured factory object.
- Shared testing settings exports in `rtecommon.testing` expose `DevAutoSettings` and `dev_auto_settings` for
  environment-driven development database overrides.
- Common logging utilities with `setup_logging`, named logger access, masked environment setting logging, and shared
  logging settings.
- Reusable pytest fixture factories and Docker/PostgreSQL helpers in `rtecommon.testing` for service-level integration
  and unit-test setup.
- Optional setup and teardown callbacks for shared database-session fixtures so consuming repos can attach their own
  session lifecycle behavior without copying the base fixture implementation.
- Packaging and developer tooling aligned for Python `3.10` through `3.14`.
- Repository bootstrap scripts for local Python, React, GitHub access, and private package access setup.
- Centralised test coverage for common helpers under `tests/unit/`.

### Project Structure

- `src/rtecommon/`: Core shared Python modules.
- `src/rtecommon/configs/settings.py`: Shared environment-backed settings models loaded from the repo `.env` file.
- `src/rtecommon/dbdef.py`: Shared PostgreSQL bootstrap, runtime configuration, and SQLAlchemy session helpers.
- `src/rtecommon/logging/`: Shared logging configuration, formatters, and helper functions.
- `src/rtecommon/testing/`: Shared pytest fixture factories and Docker/PostgreSQL test utilities.
- `src/rtecommon/testing/settings.py`: Shared development test-database settings model and ready-to-use settings
  instance for consuming repos.
- `tests/unit/`: Unit tests for reusable modules.
- `tasks/`: Working task notes and repository lessons for Codex-assisted changes.
- Root setup scripts: `InstallDevEnv.ps1`, `InstallPy.ps1`, `InstallReact.ps1`, `install_react.sh`,
  `SetupDotEnv.ps1`, `SetupGitHubAccess.ps1`, and `SetupPrivateRepoAccess.ps1`.
- `ReleaseNotes.md`: Published branch-to-release change summaries.
- `.github/workflows/py-temp-publish-pvt-build_release_notify_after_merge-def.yaml`: Reusable release-after-merge
  automation for private Python package publishing and notification.
- `legacy/`: Archived material excluded from normal test runs.

______________________________________________________________________

### Tooling Scripts

- `Install.ps1`: Refreshes local formatting/linting tools, installs pre-commit hooks, and installs the repo in editable
  mode when `pyproject.toml` is present.
- `InstallDevEnv.ps1`: Validates the supported Python range and prepares the local development toolchain.
- `InstallPy.ps1`: Installs or updates the local Python runtime on Windows when required for the repo.
- `InstallReact.ps1` and `install_react.sh`: Bootstrap the React toolchain on Windows or shell-based environments.
- `SetupDotEnv.ps1`: Regenerates the repository `.env` file from the maintained template.
- `SetupGitHubAccess.ps1` and `SetupPrivateRepoAccess.ps1`: Configure repository and package access for local work.

______________________________________________________________________

## Getting Started

1. Run `poetry install`.
1. Optionally run `Install.ps1` on Windows to refresh local developer tooling, install hooks, and install the package
   in editable mode.
1. Create the repo `.env` via `SetupDotEnv.ps1`.
1. Set or verify `PROJECT_NAME`, `PROJECT_DIR`, and `VENV_ENVIRONMENT` in the generated `.env` before running code that
   imports `rtecommon.configs.settings`.
1. If a consuming service uses the shared database helpers, configure `rtecommon.dbdef` with its base metadata,
   environment settings, logger, and table package before calling `initialize_database()` or `get_db()`.
1. Optionally run `InstallDevEnv.ps1` to validate the interpreter version and prepare the local toolchain.
1. Use `InstallPy.ps1`, `InstallReact.ps1`, or `install_react.sh` when the local environment still needs language or
   frontend tooling support.
1. Import `rtecommon` from a consuming service and configure logging with `setup_logging`.
1. Run the active test suite with `poetry run pytest`.

______________________________________________________________________

## Usage

```python
from rtecommon.configs.settings import env_settings
from rtecommon.configs.settings import logging_settings
from rtecommon.logging import get_named_loggers
from rtecommon.logging import log_environment_settings
from rtecommon.logging import setup_logging

log_path = setup_logging(
    log_backup_count=logging_settings.LOG_BACKUP_COUNT,
    log_dir=logging_settings.LOG_DIR,
    log_level_console=logging_settings.LOG_LEVEL_CONSOLE,
    log_level_file=logging_settings.LOG_LEVEL_FILE,
    log_when=logging_settings.LOG_WHEN,
    service_name="rtecommon",
)

log_all, log_console, log_file = get_named_loggers()
log_environment_settings(
    {
        "PROJECT_NAME": env_settings.PROJECT_NAME,
        "SERVICE_NAME": "rtecommon",
        "VENV_ENVIRONMENT": env_settings.VENV_ENVIRONMENT,
    }
)
```

The stable shared logging API is:

- `rtecommon.logging.setup_logging`
- `rtecommon.logging.get_named_loggers`
- `rtecommon.logging.log_environment_settings`

`setup_logging(...)` defaults log rotation to `midnight`. Consumers can override that explicitly through
`log_when` or through `rtecommon.configs.settings.LoggingSettings`.

______________________________________________________________________

## Database and Testing Helpers

`rtecommon.dbdef` is the shared database bootstrap layer for consuming services. Configure it once with
`configure_runtime(...)`, then use `initialize_database()`, `get_db()`, or `transaction()` from the shared module
instead of duplicating service-local PostgreSQL bootstrap code.

`configure_session_factory(...)` lets a consumer bind its own shared session factory, `get_db_session()` exposes the
dependency-style session provider as a context manager, and `reset_engine_and_session_factory()` resets the shared
engine/session globals for isolated test runs or runtime reconfiguration.

When `env_settings.VENV_ENVIRONMENT == "prod"`, `initialize_database()` still performs the model import and database
permission/bootstrap checks, but it skips automatic table creation.

`rtecommon.testing` provides the reusable pieces for database-backed tests. `rtecommon.testing.postgres` contains the
Docker/PostgreSQL lifecycle helpers, and `rtecommon.testing.fixtures` exposes fixture factories that let a consuming
repo keep only the thin adapter code in its own `tests/conftest.py`.

`make_db_session_fixture(...)` also accepts optional `session_setup_getter` and `session_teardown_getter` callbacks for
repo-specific setup or cleanup around the shared SQLAlchemy session lifecycle.

`rtecommon.testing.DevAutoSettings` and `rtecommon.testing.dev_auto_settings` expose environment-backed overrides for
Docker-backed development MySQL host and port settings so consuming repos can share one testing configuration surface.

______________________________________________________________________

## Release Notes Workflow

1. Commit the intended branch changes.
1. Compare the current branch against `master`.
1. Prepend a new section to `ReleaseNotes.md` without changing older entries.
1. Keep `pyproject.toml` versioning aligned with the release entry so the merge-triggered workflow can publish the
   matching release tag.
1. Group the changes under clear headings and end the new entry with the divider line.
1. Publish the release branch and PR through the normal repository workflow.

______________________________________________________________________

[cicd_codestyle_img]: https://img.shields.io/badge/code%20style-black-000000.svg "Black"
[cicd_codestyle_lnk]: https://github.com/psf/black "Black"
[general_maintenance_y_img]: https://img.shields.io/badge/Maintenance%20Intended-%E2%9C%94-green.svg?style=flat-square "Maintenance - intended"
[general_maintenance_y_lnk]: http://unmaintained.tech/ "Maintenance - intended"
[general_semver_link]: https://semver.org/ "Semantic Versioning - 2.0.0"
[general_semver_pic]: https://img.shields.io/badge/Semantic%20Versioning-2.0.0-brightgreen.svg?style=flat-square "Semantic Versioning - 2.0.0"

