utils

Reusable Python utilities for application configuration and logging.

The package currently provides:

• a Pydantic-based settings base class with environment-variable support
• configurable application logging via uvicorn's DefaultFormatter
• console logging and optional daily rotating file logs
• configurable log retention and log file naming

The project requires Python 3.14 or newer.

Publish package

Prerequisites

• Python 3.14 or newer
• uv
• a Gitea repository with Package Registry support enabled
• a Gitea Personal Access Token with permission to write packages

The examples below use:

Gitea host: https://gitea.schneiderserver.site
Owner:     mathias
Package:   utils

Create a token in Gitea under User settings → Applications → Access Tokens. Keep it private and do not commit it to the repository.

Publish

Run the tests and build the source distribution and wheel:

uv sync
uv run pytest
rm -rf dist
uv build

The build artifacts will be written to dist/:

dist/utils-<version>.tar.gz
dist/utils-<version>-py3-none-any.whl

Configure the Gitea PyPI registry in ~/.pypirc:

[distutils]
index-servers =
    gitea

[gitea]
repository = https://gitea.schneiderserver.site/api/packages/mathias/pypi
username = mathias
password = YOUR_PRIVATE_GITEA_TOKEN

Upload the package:

python -m twine upload --repository gitea dist/*

Gitea does not allow the same package version to be uploaded twice. To publish an update, increment version in pyproject.toml, rebuild, and upload again:

version = "0.1.1"

It is useful to create a matching Git tag for each published version:

git tag v0.1.0
git push origin v0.1.0

Consume package in other projects

Public package

If the package is publicly readable, install it with:

pip install \
  --index-url https://gitea.schneiderserver.site/api/packages/mathias/pypi/simple \
  utils

The equivalent uv command is:

uv pip install \
  --index-url https://gitea.schneiderserver.site/api/packages/mathias/pypi/simple \
  utils

Private package

For a private package, use a token with package-read permission. Avoid putting the token directly into commands where possible because it can end up in shell history or process listings.

pip install \
  --index-url https://<username>:<read-token>@gitea.schneiderserver.site/api/packages/mathias/pypi/simple \
  utils

For CI, provide the token through a secret rather than committing it to a configuration file.

Add as a project dependency with uv add

Yes. uv add adds the package to the consuming project's [project].dependencies in pyproject.toml and updates uv.lock:

uv add --index gitea=https://gitea.schneiderserver.site/api/packages/mathias/pypi/simple utils

For a public package, this may be enough for the initial add. To keep the package source explicit and avoid accidentally resolving utils from another index, configure the index and source in the consuming project's pyproject.toml:

[project]
dependencies = [
    "utils>=0.1.0",
]

[tool.uv.sources]
utils = { index = "gitea" }

[[tool.uv.index]]
name = "gitea"
url = "https://gitea.schneiderserver.site/api/packages/mathias/pypi/simple"
explicit = true

For a private package, keep the URL free of credentials and provide them at install or lock time through environment variables. For the index name gitea, uv expects:

export UV_INDEX_GITEA_USERNAME=mathias
export UV_INDEX_GITEA_PASSWORD=YOUR_PRIVATE_GITEA_TOKEN
uv lock
uv sync

The token is not written to pyproject.toml or uv.lock. In CI, set these variables from protected secrets. The utils entry in pyproject.toml can then be installed in any checkout with:

uv sync

Usage

Logging configuration

LoggingSettings configures the root logger when instantiated. By default it writes to the console and to logs/monitoring_backend.log, rotating the file at midnight and retaining 30 rotated files.

from utils.logging_config import LoggingSettings

settings = LoggingSettings(
    LOG_LEVEL="INFO",
    LOG_TO_FILE=True,
    LOG_FILE_PATH="logs/application.log",
    LOG_BACKUP_COUNT=14,
)

The settings can also be overridden with environment variables:

export LOG_LEVEL=DEBUG
export LOG_TO_FILE=true
export LOG_FILE_PATH=logs/application.log
export LOG_BACKUP_COUNT=14

Invalid log levels fall back to INFO. LOG_BACKUP_COUNT must be zero or greater.

Base settings

BaseSettingsConfig is a small base class for Pydantic settings models. Extra environment variables are ignored and environment variable names are matched case-sensitively:

from utils.settings import BaseSettingsConfig


class ApplicationSettings(BaseSettingsConfig):
    APP_NAME: str = "example"

Development

Install the locked development environment and run the test suite with:

uv sync
uv run pytest

Build the package without publishing it:

uv build