appkit-commons

appkit-commons Best Practices

Read before writing any new feature. Covers configuration, DI, persistence, and scheduling.

---

1. Configuration

App initialization pattern

Define a cached configure() function in config.py. Call it from __init__.py before anything else.

# config.py
from functools import lru_cache
from appkit_commons.configuration import BaseConfig
from appkit_commons.configuration.configuration import Configuration, Environment
from appkit_commons.registry import service_registry


class MyFeatureConfig(BaseConfig):
    api_url: str | None = None
    api_key: str = ""


class ApplicationConfig(BaseConfig):
    version: str
    name: str
    logging: str
    environment: Environment | None = Environment.local
    my_feature: MyFeatureConfig = MyFeatureConfig()


@lru_cache(maxsize=1)
def configure() -> Configuration[ApplicationConfig]:
    return service_registry().configure(ApplicationConfig, env_file=".env")

# __init__.py
import logging
from dotenv import load_dotenv
from myapp.config import configure
from appkit_commons.configuration.logging import init_logging

logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s")

load_dotenv(override=True)
configuration = configure()
init_logging(configuration)

service_registry().configure() auto-registers every nested config object by its own type — ApplicationConfig, MyFeatureConfig, DatabaseConfig, ServerConfig, etc. are all retrievable after this call.

Accessing config anywhere

Use service_registry().get() with the exact config class. Always call inside functions/methods, never at module level.

from appkit_commons.registry import service_registry
from myapp.config import ApplicationConfig, LlmConfig, MyFeatureConfig

# top-level app config
cfg = service_registry().get(ApplicationConfig)
log.info("Starting %s v%s", cfg.name, cfg.version)

# nested sub-config — registered automatically by configure()
llm_cfg = service_registry().get(LlmConfig)
feature_cfg = service_registry().get(MyFeatureConfig)