Metadata-Version: 2.4
Name: rtecommon
Version: 3.1.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.
- 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.
- 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.
- `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.
- `legacy/`: Archived material excluded from normal test runs.

______________________________________________________________________

### Tooling Scripts

- `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. 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.

`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`.

______________________________________________________________________

## 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. 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"

