Metadata-Version: 2.4
Name: rtecommon
Version: 3.0.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)
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, and configuration utilities for the RealTime Events ecosystem.

______________________________________________________________________

## Short Description

`rtecommon` centralises reusable project infrastructure so RealTime Events services can share configuration,
environment handling, and logging behaviour 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.
- Common logging utilities with `setup_logging`, named logger access, and masked environment setting logging.
- 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/logging/`: Shared logging configuration, formatters, and helper functions.
- `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. 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.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=7,
    log_dir="logs",
    log_level_console="INFO",
    log_level_file="DEBUG",
    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,
    }
)
```

______________________________________________________________________

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

