stogger.config

Configuration handling for stogger.

Classes

ProjectStructure	Detected project layout used for source and test discovery.
FormatConfig	Configuration for log format settings, loaded from [tool.stogger.format].
StoggerConfig	Central configuration for stogger, merged from [tool.stogger] in

Functions

detect_project_structure([project_root])

Detect project structure using smart heuristics.

Module Contents

class stogger.config.ProjectStructure

Detected project layout used for source and test discovery.

Attributes:

source_dirs: Relative paths to source directories (e.g. ["src"]). test_dirs: Relative paths to test directories (e.g. ["tests"]). exclude_patterns: Glob patterns for files excluded from logging analysis. detection_source: How the structure was determined — "pyproject.toml",

"heuristics", or "defaults".

project_root: Absolute path to the project root directory.

source_dirs: list[str]

exclude_patterns: list[str]

detection_source: str

project_root: pathlib.Path

get_source_paths()

Resolve source directories to absolute paths.

Returns:

List of absolute Paths joining project_root with each entry in source_dirs.

Return type:

list[pathlib.Path]

should_exclude_from_logging_analysis(file_path)

Check whether a file should be excluded from logging analysis.

Files inside test_dirs or matching any exclude_patterns glob are excluded. Files outside project_root are always excluded.

Args:

file_path: Absolute path to the file to check.

Returns:

True if the file should be excluded.

Parameters:

file_path (pathlib.Path)

Return type:

bool

class stogger.config.FormatConfig

Configuration for log format settings, loaded from [tool.stogger.format].

Attributes:

timestamp_precision: Timestamp format — "iso", "iso_seconds",

"iso_no_z", or "relative". Default "iso_seconds".

min_level: Minimum log level to display. Default "info". show_code_info: Include file name and line number. Default False. pad_event_width: Minimum width for the event column. Default 30.

timestamp_precision: str = 'iso_seconds'

min_level: str = 'info'

show_code_info: bool = False

pad_event_width: int = 30

class stogger.config.StoggerConfig(**kwargs)

Central configuration for stogger, merged from [tool.stogger] in pyproject.toml and keyword arguments passed at construction.

Key attributes (with defaults):

Attributes:

verbose (bool): Enable verbose output. Default False. logdir (Path | None): Directory for log files. Default None. log_cmd_output (bool): Log subprocess command output. Default False. log_to_console (bool): Also log to the console. Default True. syslog_identifier (str): Identifier for syslog/systemd journal.

Default "stogger".

show_caller_info (bool): Include caller file/line in log output.

Default False.

translation_dir (Path | None): Directory containing message

translations. Default None.

language (str): Language code for log messages. Default "en". log_format (str): Output format — "simple" or "json".

Default "simple".

async_logging (bool): Use asynchronous log writing. Default False. enable_systemd (bool): Enable systemd/journal integration.

Default True.

systemd_facility (str | None): Syslog facility for systemd output.

Default None.

src_dir (str): Primary source directory name. Default "src". format (FormatConfig): Format configuration. Default FormatConfig(). ast_respect_gitignore (bool): Honor .gitignore during AST

analysis. Default True.

ast_max_parameters (int): Max parameters before flagging a function.

Default 8.

ast_logging_focus (bool): Focus AST analysis on logging patterns.

Default True.

ast_enabled_patterns (list | None): Specific AST patterns to enable.

None enables all. Default None.

Parameters:

kwargs (Any)

verbose: bool = False

logdir: pathlib.Path | None = None

log_cmd_output: bool = False

log_to_console: bool = True

syslog_identifier: str = 'stogger'

show_caller_info: bool = False

translation_dir: pathlib.Path | None = None

language: str = 'en'

log_format: str = 'simple'

async_logging: bool = False

enable_systemd: bool = True

systemd_facility: str | None = None

enable_postgres: bool = False

postgres_dsn: str | None = None

postgres_table: str = 'stogger_logs'

src_dir: str = 'src'

format: FormatConfig

ast_respect_gitignore: bool = True

ast_max_parameters: int = 8

ast_logging_focus: bool = True

ast_enabled_patterns: list | None = None

stogger.config.detect_project_structure(project_root=None)

Detect project structure using smart heuristics.

Args:

project_root: Project root directory. If None, uses current working directory.

Returns:

ProjectStructure with detected information.

Raises:

ValueError: If project structure cannot be determined and user configuration is required.

Parameters:

project_root (pathlib.Path | None)

Return type:

ProjectStructure