rtecommon 3.2.1

Common tools/utilities/configurations used in the RealTime Events echo system.

RealTimeEvents Common

Category	Status' and Links
General
CD/CI

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.
• 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.
• 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.
2. Optionally run Install.ps1 on Windows to refresh local developer tooling, install hooks, and install the package in editable mode.
3. Create the repo .env via SetupDotEnv.ps1.
4. Set or verify PROJECT_NAME, PROJECT_DIR, and VENV_ENVIRONMENT in the generated .env before running code that imports rtecommon.configs.settings.
5. 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().
6. Optionally run InstallDevEnv.ps1 to validate the interpreter version and prepare the local toolchain.
7. Use InstallPy.ps1, InstallReact.ps1, or install_react.sh when the local environment still needs language or frontend tooling support.
8. Import rtecommon from a consuming service and configure logging with setup_logging.
9. Run the active test suite with poetry run pytest.

---

Usage

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.

---

Release Notes Workflow

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

---