Commit 6c6bf28

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Scitrera Application Framework (SAF) is a lightweight Python application framework for services, CLIs, and desktop apps. It provides:

- Environment/variables abstraction with layered sources and ergonomic access

- Structured logging with JSON formatting option

- Simple plugin/extension system supporting dependency injection and OSGi-style multi-extensions

- Optional stateful working directory management

- Background execution, multi-tenant configuration, and Pyroscope profiling plugins

pip install -e .

pip install pytest pytest-cov python-dotenv

pytest tests/ -v

pytest tests/test_api_variables.py -v

pytest tests/test_api_variables.py::TestVariablesBasic::test_set_and_get -v

pytest tests/ --cov=scitrera_app_framework --cov-report=term-missing

1. `init_framework(app_name)` → creates/returns a `Variables` instance

2. Logging is configured (JSON or %-format based on `LOGGING_FORMAT`)

3. Stateful paths optionally set up under `STATEFUL_ROOT`

4. Shutdown hooks registered (SIGTERM or atexit)

5. Plugins registered and initialized

Alternate init functions with different defaults:

- `init_framework_desktop()` – uses `~/.config/$APP_NAME`, atexit hooks

- `init_framework_test_harness()` – DEBUG logging, no stateful/shutdown

- `init_framework_embedded()` – avoids overriding external logging config

The `Variables` class is the central configuration container. It searches sources in priority order:

1. Process environment (`os.environ` with uppercase keys)

2. Local settings (`v.set()`)

3. Additional sources added via `v.add_source()`

4. Fallback defaults

Key methods:

- `v.environ(key, default=, type_fn=)` – get with default/type registration

- `v.set(key, value)` – set local value

- `v.get_by_prefix(prefix)` – extract namespaced config as dict (useful for kwargs)

- `v.import_from_env_by_prefix(prefix)` – import env vars matching prefix

`EnvPlacement` enum controls where environment appears in search order (TOP, BOTTOM, BOTTOM2, IGNORED).

Plugins implement the `Plugin` abstract class:

- `extension_point_name(v)` – the named slot this plugin fills

- `is_enabled(v)` – for single-extension mode (dependency injection)

- `is_multi_extension(v)` – for OSGi-style multiple implementations

- `get_dependencies(v)` – list of extension points that must init first

- `initialize(v, logger)` – returns the extension value

- `shutdown(v, logger, value)` – cleanup

Registration:

register_plugin(MyPlugin, v, init=True) # register and initialize

value = get_extension('ext-name', v) # single extension

values = get_extensions('ext-name', v) # multi-extension (returns dict)

Built-in plugins:

- `EXT_BACKGROUND_EXEC` – thread pool via `get_background_exec()`

- `EXT_PROGRESS_TRACKER` – progress tracking for UIs

- Internal framework variables use "epp" keys: `=|name|` (equal-pipe-pipe pattern)

- Type functions for environment parsing: `ext_parse_bool`, `ext_parse_csv`, `ext_get_python`

- Use lazy string formatting in logging: `logger.debug("item: %s", item)` not f-strings

- The `v` parameter is conventionally the Variables instance; `None` uses the default singleton

Core:

- `APP_NAME` – override computed app name

- `LOGGING_LEVEL` – log level (default from init kwarg)

- `LOGGING_FORMAT` – `'json'` for JSON logs, or a %-format string

Stateful:

- `STATEFUL_ROOT` – root directory for stateful data (default: `./scratch`)

- `SAF_SETUP_STATEFUL` – enable/disable stateful features

- `SAF_STATEFUL_CHDIR` – whether to chdir into stateful path

Plugins:

- `SAF_BASE_PLUGINS` – auto-register base plugins

- `PYROSCOPE_ENABLED` – enable Pyroscope profiling

- `SAF_MULTITENANT_ENABLED` – enable multi-tenant plugin

testpaths = tests

python_files = test_*.py

python_classes = Test*

python_functions = test_*

addopts = -v --tb=short

filterwarnings =

ignore::DeprecationWarning

ignore::PendingDeprecationWarning

markers =

slow: marks tests as slow (deselect with '-m "not slow"')

integration: marks tests as integration tests

# Test dependencies for scitrera-app-framework

pytest>=7.0.0

pytest-cov>=4.0.0

# Optional: for testing env file functionality

python-dotenv>=1.0.0

version="0.0.60",

author_email="open-source-team@scitrera.com",

'python-json-logger>=4.0.0',

import os

import sys

import pytest

import logging

def reset_framework_state():

"""Reset framework global state before each test."""

# Import here to avoid circular imports

import scitrera_app_framework.core.core as core_module

import scitrera_app_framework.core.plugins as plugins_module

# Store original state

original_default_vars = core_module._default_vars_inst

original_sigterm_hooks = core_module._sigterm_hooks.copy()

yield

# Reset state after test

core_module._default_vars_inst = original_default_vars

core_module._sigterm_hooks.clear()

core_module._sigterm_hooks.extend(original_sigterm_hooks)

def clean_env():

"""Provide a clean environment, removing SAF-related env vars temporarily."""

saf_vars = {k: v for k, v in os.environ.items()

if k.startswith('SAF_') or k.startswith('LOGGING_') or k == 'APP_NAME'}

for k in saf_vars:

del os.environ[k]

yield

# Restore

os.environ.update(saf_vars)

def temp_env():

"""Context manager to temporarily set environment variables."""

original = {}

def _set_env(**kwargs):

for k, v in kwargs.items():

if k in os.environ:

original[k] = os.environ[k]

os.environ[k] = str(v)

yield _set_env

# Cleanup

for k in list(os.environ.keys()):

if k in original:

os.environ[k] = original[k]

elif k not in original and k in os.environ:

# Only delete if we added it

pass

def fresh_variables():

"""Create a fresh Variables instance for testing."""

from scitrera_app_framework.api import Variables

return Variables()

def capture_logs():

"""Capture log output for assertions."""

class LogCapture(logging.Handler):

def __init__(self):

super().__init__()

self.records = []

def emit(self, record):

self.records.append(record)

def get_messages(self, level=None):

if level is None:

return [r.getMessage() for r in self.records]

return [r.getMessage() for r in self.records if r.levelno == level]

handler = LogCapture()

handler.setLevel(logging.DEBUG)

yield handler

# Cleanup happens automatically as handler goes out of scope