liberata_metrics package

Overview

This is the top-level package for the Liberata Scientometrics library. It exposes logging utilities and organizes the core API into domain-specific subpackages for metrics, generators, utilities, integrations, and visualization.

Package Map

Package	Purpose	Reference
liberata_metrics.metrics	Portfolio, market, distribution, graph, and system-health metrics.	Metrics API
liberata_metrics.generators	Synthetic data generation for references, shares, and capital matrices.	Generators API
liberata_metrics.utils	Data loading, wrangling, and sparse matrix helper utilities.	Utils API
liberata_metrics.visualizations	Matrix and time-series visualization helpers.	Visualizations API
liberata_metrics.integrations	External system integrations (including Supabase paths).	Integrations API

Top-Level Public API

The top-level liberata_metrics namespace exposes logging setup helpers.

liberata_metrics.configure_logging([level, ...])	Configure application-level logging for scripts/CLIs.
liberata_metrics.get_logger([name])	Return a library logger.

Subpackage Reference

Use the pages below for full module-level and function-level documentation.

• liberata_metrics.generators package
  • Submodules
  • Module contents
• liberata_metrics.integrations package
  • Submodules
  • Module contents
• liberata_metrics.metrics package
  • Submodules
  • Module contents
• liberata_metrics.utils package
  • Submodules
  • Module contents
• liberata_metrics.visualizations package
  • Submodules
  • Module contents

Internal Modules

• liberata_metrics.logging module
  • configure_logging()
  • get_logger()

Module Contents

liberata_metrics.configure_logging(level: str | None = None, log_file: str | None = None, max_bytes: int = 10000000, backup_count: int = 5, fmt: str | None = None) → None

Configure application-level logging for scripts/CLIs.

Call this once from top-level entrypoints (scripts, CLI) before performing work.

Parameters:

• level (Optional[str]) – Logging level name (e.g., “DEBUG”, “INFO”). If None, reads from environment variable LOG_LEVEL or defaults to “INFO”.

• log_file (Optional[str]) – Path to a rotating log file. If provided, a RotatingFileHandler is added. Parent directories are created if necessary.

• max_bytes (int) – Maximum bytes per log file before rotation.

• backup_count (int) – Number of rotated log files to keep.

• fmt (Optional[str]) – Optional log format string. If None, a sensible default is used.

Notes

• This function configures the root logger. Library modules should not call this; only application code (scripts or CLI entrypoints) should configure logging.

• Multiple calls are safe: if the root logger already has handlers, the function sets the level and returns early to avoid duplicate handlers in interactive runs.

Example

from liberata_metrics.logging import configure_logging configure_logging(level=”DEBUG”, log_file=”logs/run.log”)

liberata_metrics.get_logger(name: str | None = None) → Logger

Return a library logger.

Usage (inside library modules):

logger = get_logger(__name__) logger.debug(“message”)

This logger installs a NullHandler by default so importing the library does not configure application logging or emit output. Application code (scripts/CLI) should call configure_logging() once at startup to enable handlers/formatting.

Parameters:

name (Optional[str]) – Optional module name to append to the library logger root. If provided the returned logger name will be “liberata_metrics.<name>”.

Returns:

Configured logger object (may carry NullHandler by default).

Return type:

logging.Logger