pycraftcore

pycraftcore is a reusable technical infrastructure library for Python applications: configuration, resilient HTTP clients, a pooled async SQLite repository, a sandboxed Python code runner, safe SQL validation, serialization, and a handful of other adapters — small, swappable building blocks rather than a framework.

Design principles: Modularity · Reusability · Maintainability

Table of Contents

• Functionality
• Installation
• Configuration
• Development

Functionality

Installation

Stable release (recommended for production):

pip install pycraftcore

Development build (latest features, may be unstable):

pip install -i https://test.pypi.org/simple/ pycraftcore

Configuration

Services are configured using YAML files combined with environment variables.

Directory layout — a root.yml plus per-kind subdirectories, one file per item:

Environment variables referenced from YAML via ${oc.env:NAME}:

This list isn't exhaustive — any config value can be templated the same way; check the YAML under config/<env>/ for what a given deployment actually reads.

Connector example (connector/<tag>.yml):

connector:
  <connector_tag>:
    name: <connector name>
    type: api
    base_url: <base url>
    timeout: 5
    retry: 3
    auth:
      type: token
      key_name: apikey
      key_value: ${oc.env:connector_api_key}

Operation example (operation/<tag>.yml) — references a connector by tag:

operation:
  <operation_tag>:
    name: <operation name>
    type: api
    connector: ${connector.<connector_tag>}
    endpoint: /<path>
    method: GET
    parameters:
      <param>: <value>

Root example (root.yml) — wires everything together for a given environment:

application_configuration:
  env: ${oc.env:APP_ENV,debug}
  run: async

  connector:
    api:
      <connector_tag>: ${connector.<connector_tag>}
    file:
      <connector_tag>: ${connector.<connector_tag>}
    database:
      <connector_tag>: ${connector.<connector_tag>}
    telemetry:
      <connector_tag>: ${connector.<connector_tag>}
    
  operation:
    <operation_tag>: ${operation.<operation_tag>}
    # ...

Connectors and operations both declare a type, which determines which fields they take and which concrete object they load as.

Using it in code:

from pathlib import Path

from pycraftcore.application_configuration.adapter.load_application_configuration import (
    LoadApplicationConfiguration,
)
from pycraftcore.application_configuration.adapter.omega_configuration_reader import (
    OmegaConfigurationReader,
)
from pycraftcore.application_configuration.enum.run_type_environment import RunTypeEnvironment
from pycraftcore.logger.adapter import StandardLogger

reader = OmegaConfigurationReader(RunTypeEnvironment.deploy, Path("config"))
loader = LoadApplicationConfiguration(reader, StandardLogger())

config = loader.load()

connector = config.connector.api("<connector_tag>")  # ApiConnector
operation = config.operation.api("<operation_tag>")  # ApiOperation

config.connector/config.operation return the concrete connector/operation type for a given tag (.api(), .database(), .file(), .telemetry() where applicable) instead of a raw dict — see pycraftcore.application_configuration for the full API.

Logging

Standard logging, one format for every line. Call configure_logging once at startup:

from pycraftcore.logger import configure_logging
from pycraftcore.logger.adapter import StandardLogger

configure_logging("INFO")  # level name or number
logger = StandardLogger()
logger.info("booted")

2026-09-27 10:06:17.679 | INFO     | 1bddfefb-… | controller:execute:51 - stream request accepted

• The request id comes from pycraftcore.context.request_id_context (set by RequestIDMiddleware from the X-Request-ID header): every line logged while it is set shows it, - otherwise. Do not write it in the message.
• Uvicorn's loggers are routed through the same format; httpx, httpcore, mcp, pymongo and other chatty libraries stay at WARNING (QUIET_LOGGERS).
• Calling it again replaces the console handler instead of adding a second one.

Development

Pre-commit hooks

This repo uses pre-commit to run the unit test suite before every commit and push (see .pre-commit-config.yaml). Git hooks live under .git/hooks/ and aren't tracked by git, so after cloning or pulling this change, install them once:

uv run pre-commit install --hook-type pre-commit --hook-type pre-push

After that, git commit and git push will run uv run pytest automatically and abort on failure. To run the hooks manually against the whole repo:

uv run pre-commit run --all-files --hook-stage pre-commit

Makefile commands

make install_dev   # uv sync --group dev
make test           # uv run pytest
make lint            # uv run ruff check
make format          # uv run ruff format
make typecheck        # uv run ty check (strict mode)

Run pytest --cov=pycraftcore --cov-report=term-missing for a coverage breakdown by module.