perfaud 0.1.0__py3-none-any.whl

perfaud/__init__.py

@@ -0,0 +1,9 @@
+"""Audit changes in reported portfolio performance."""
+
+from importlib.metadata import version
+
+from perfaud.workspace import run
+
+__version__ = version("perfaud")
+
+__all__ = ["run", "__version__"]

perfaud/aliases.py

@@ -0,0 +1,48 @@
+"""Define exact-default source columns for normalized Audit datasets.
+
+Vendor and site-specific source headings belong in explicit schema YAML. When
+no schema mapping is configured for a normalized field, Audit accepts only the
+exact normalized field name, including case.
+"""
+
+from __future__ import annotations
+
+# Project imports
+from perfaud import schema as pc_cols
+from perfaud.source_loader import ColumnAliases
+
+
+def _exact_aliases(columns: tuple[str, ...]) -> ColumnAliases:
+    """Return one exact source-name candidate per normalized column."""
+    return {column: (column,) for column in columns}
+
+
+PORTFOLIO_PERFORMANCE_REQUIRED_ALIASES = _exact_aliases(
+    pc_cols.PORTFOLIO_PERFORMANCE_REQUIRED_COLUMNS
+)
+PORTFOLIO_PERFORMANCE_OPTIONAL_ALIASES = _exact_aliases(
+    pc_cols.PORTFOLIO_PERFORMANCE_OPTIONAL_COLUMNS
+)
+
+SECURITY_PERFORMANCE_REQUIRED_ALIASES = _exact_aliases(
+    pc_cols.SECURITY_PERFORMANCE_REQUIRED_COLUMNS
+)
+SECURITY_PERFORMANCE_OPTIONAL_ALIASES = _exact_aliases(
+    pc_cols.SECURITY_PERFORMANCE_OPTIONAL_COLUMNS
+)
+
+SPLITS_REQUIRED_ALIASES = _exact_aliases(pc_cols.SPLITS_REQUIRED_COLUMNS)
+SPLITS_OPTIONAL_ALIASES = _exact_aliases(pc_cols.SPLITS_OPTIONAL_COLUMNS)
+
+TRANSACTIONS_REQUIRED_ALIASES = _exact_aliases(pc_cols.TRANSACTIONS_REQUIRED_COLUMNS)
+TRANSACTIONS_OPTIONAL_ALIASES = _exact_aliases(pc_cols.TRANSACTIONS_OPTIONAL_COLUMNS)
+
+HOLDINGS_REQUIRED_ALIASES = _exact_aliases(pc_cols.HOLDINGS_REQUIRED_COLUMNS)
+HOLDINGS_OPTIONAL_ALIASES = _exact_aliases(pc_cols.HOLDINGS_OPTIONAL_COLUMNS)
+
+SECURITY_MASTER_REQUIRED_ALIASES = _exact_aliases(
+    pc_cols.SECURITY_MASTER_REQUIRED_COLUMNS
+)
+SECURITY_MASTER_OPTIONAL_ALIASES = _exact_aliases(
+    pc_cols.SECURITY_MASTER_OPTIONAL_COLUMNS
+)

perfaud/atomic_directory.py

@@ -0,0 +1,221 @@
+"""Stage and atomically promote complete Audit output directories."""
+
+from __future__ import annotations
+
+# Python imports
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+import shutil
+import tempfile
+
+# Project imports
+from perfaud.errors import PerfaudError
+import perfaud.paths as util
+
+
+@contextmanager
+def staged_directory(destination: util.PathLike) -> Iterator[Path]:
+    """Yield a sibling staging directory and promote it after successful use.
+
+    Args:
+        destination: Final directory that should receive the staged contents.
+
+    Yields:
+        Empty sibling directory for building and validating complete output.
+
+    Raises:
+        PerfaudError: If the destination exists but is not a directory, or if a
+            failed promotion cannot restore the previous directory.
+        OSError: If staging or promotion fails.
+
+    Notes:
+        The previous destination remains unchanged if work inside the context
+        fails. Promotion briefly renames an existing destination to a sibling
+        backup, installs the staged directory, and then removes the backup.
+    """
+    destination_path = Path(destination)
+    if destination_path.exists() and not destination_path.is_dir():
+        raise PerfaudError(
+            f"{destination_path} exists but is not a directory.",
+        )
+    destination_path.parent.mkdir(parents=True, exist_ok=True)
+    staging_path = Path(
+        tempfile.mkdtemp(
+            prefix=f".{destination_path.name}.staging-",
+            dir=destination_path.parent,
+        )
+    )
+    try:
+        yield staging_path
+    except BaseException:
+        shutil.rmtree(staging_path, ignore_errors=True)
+        raise
+
+    try:
+        _promote_staged_directory(staging_path, destination_path)
+    except BaseException:
+        shutil.rmtree(staging_path, ignore_errors=True)
+        raise
+
+
+@contextmanager
+def staged_children(
+    destination_root: util.PathLike,
+    child_names: tuple[str, ...],
+) -> Iterator[Path]:
+    """Yield a staging root and atomically replace selected child directories.
+
+    Args:
+        destination_root: Parent containing the managed output directories.
+        child_names: Exact child directory names owned by the current run.
+
+    Yields:
+        Empty sibling staging root. A missing managed child at successful
+        promotion removes any older destination child with the same name.
+
+    Raises:
+        PerfaudError: If a managed destination is not a directory or recovery fails.
+        OSError: If staging or promotion fails.
+
+    Notes:
+        Files and directories below ``destination_root`` whose names are not in
+        ``child_names`` remain untouched.
+    """
+    destination_path = Path(destination_root)
+    if destination_path.exists() and not destination_path.is_dir():
+        raise PerfaudError(
+            f"{destination_path} exists but is not a directory.",
+        )
+    if not child_names or len(set(child_names)) != len(child_names):
+        raise ValueError("child_names must contain unique managed directory names.")
+    if any(Path(name).name != name or name in {"", ".", ".."} for name in child_names):
+        raise ValueError("child_names must contain plain directory names.")
+
+    destination_path.parent.mkdir(parents=True, exist_ok=True)
+    staging_root = Path(
+        tempfile.mkdtemp(
+            prefix=f".{destination_path.name}.run-staging-",
+            dir=destination_path.parent,
+        )
+    )
+    try:
+        yield staging_root
+    except BaseException:
+        shutil.rmtree(staging_root, ignore_errors=True)
+        raise
+
+    try:
+        _promote_staged_children(
+            staging_root,
+            destination_path,
+            child_names,
+        )
+    except BaseException:
+        shutil.rmtree(staging_root, ignore_errors=True)
+        raise
+
+
+def remap_staged_path(
+    path: Path,
+    *,
+    staging_root: Path,
+    destination_root: Path,
+) -> Path:
+    """Return the final path corresponding to a path inside a staging root.
+
+    Args:
+        path: Artifact path returned while writing the staging directory.
+        staging_root: Root directory used for the staged build.
+        destination_root: Final promoted directory.
+
+    Returns:
+        Artifact path below ``destination_root`` with the same relative path.
+    """
+    return destination_root / path.relative_to(staging_root)
+
+
+def _promote_staged_directory(staging_path: Path, destination_path: Path) -> None:
+    """Replace one destination directory while preserving recovery on failure."""
+    if not destination_path.exists():
+        staging_path.replace(destination_path)
+        return
+
+    backup_path = Path(
+        tempfile.mkdtemp(
+            prefix=f".{destination_path.name}.backup-",
+            dir=destination_path.parent,
+        )
+    )
+    backup_path.rmdir()
+    destination_path.replace(backup_path)
+    try:
+        staging_path.replace(destination_path)
+    except BaseException as promotion_error:
+        try:
+            backup_path.replace(destination_path)
+        except OSError as restoration_error:
+            raise PerfaudError(
+                "Audit output promotion failed and the previous output could "
+                f"not be restored from {backup_path}: {restoration_error}",
+            ) from promotion_error
+        raise
+    shutil.rmtree(backup_path, ignore_errors=True)
+
+
+def _promote_staged_children(
+    staging_root: Path,
+    destination_root: Path,
+    child_names: tuple[str, ...],
+) -> None:
+    """Promote a complete set of managed children with rollback."""
+    for child_name in child_names:
+        staged_child = staging_root / child_name
+        destination_child = destination_root / child_name
+        if staged_child.exists() and not staged_child.is_dir():
+            raise PerfaudError(
+                f"Staged Audit output {staged_child} is not a directory.",
+            )
+        if destination_child.exists() and not destination_child.is_dir():
+            raise PerfaudError(
+                f"{destination_child} exists but is not a directory.",
+            )
+
+    destination_existed = destination_root.exists()
+    destination_root.mkdir(parents=True, exist_ok=True)
+    backup_root = Path(
+        tempfile.mkdtemp(
+            prefix=f".{destination_root.name}.run-backup-",
+            dir=destination_root.parent,
+        )
+    )
+    promoted_names: list[str] = []
+    try:
+        for child_name in child_names:
+            destination_child = destination_root / child_name
+            if destination_child.exists():
+                destination_child.replace(backup_root / child_name)
+        for child_name in child_names:
+            staged_child = staging_root / child_name
+            if staged_child.exists():
+                staged_child.replace(destination_root / child_name)
+                promoted_names.append(child_name)
+    except BaseException as promotion_error:
+        for child_name in promoted_names:
+            shutil.rmtree(destination_root / child_name, ignore_errors=True)
+        try:
+            for child_name in child_names:
+                backup_child = backup_root / child_name
+                if backup_child.exists():
+                    backup_child.replace(destination_root / child_name)
+            if not destination_existed and not any(destination_root.iterdir()):
+                destination_root.rmdir()
+        except OSError as restoration_error:
+            raise PerfaudError(
+                "Audit run promotion failed and previous report directories "
+                f"could not be restored from {backup_root}: {restoration_error}",
+            ) from promotion_error
+        raise
+
+    shutil.rmtree(backup_root, ignore_errors=True)
+    shutil.rmtree(staging_root, ignore_errors=True)

perfaud/axys_apx/__init__.py

@@ -0,0 +1 @@
+"""Axys/APX-specific identity and transaction-safety contracts."""

perfaud/axys_apx/security_identity.py

@@ -0,0 +1,394 @@
+"""Construct stable perfaud security identifiers from Axys/APX source fields."""
+
+from __future__ import annotations
+
+# Python imports
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Final, cast
+
+# Third-party imports
+import polars as pl
+
+# Project imports
+from perfaud.errors import PerfaudError
+from perfaud.config import source_file_columns
+import perfaud.paths as util
+
+_SECURITY_ID_KEY: Final = "security_id"
+_COMPONENTS_KEY: Final = "components"
+_SEPARATOR_KEY: Final = "separator"
+_DATASETS_KEY: Final = "datasets"
+_DEFAULT_SEPARATOR: Final = ""
+_DEFAULT_COMPONENTS: Final = ("security_type", "security_symbol")
+_CONFIGURATION_FIELDS: Final = {
+    _COMPONENTS_KEY,
+    _SEPARATOR_KEY,
+    _DATASETS_KEY,
+}
+_DATASET_FIELDS: Final = {
+    _COMPONENTS_KEY,
+    _SEPARATOR_KEY,
+}
+_SECURITY_DATASETS: Final = {
+    "holdings",
+    "security_performance",
+    "security_master",
+    "splits",
+    "transactions",
+}
+
+
+@dataclass(frozen=True)
+class SecurityIdConstruction:
+    """Describe normalized and source fields used to construct a security key.
+
+    Attributes:
+        components: Normalized mapping keys, in concatenation order.
+        source_columns: Exact-case source CSV columns resolved for the dataset.
+        separator: Optional text inserted between adjacent component values.
+    """
+
+    components: tuple[str, ...]
+    source_columns: tuple[str, ...]
+    separator: str
+
+    @property
+    def schema_overrides(self) -> dict[str, type[pl.DataType]]:
+        """Return CSV schema overrides that preserve component text exactly."""
+        return {source_column: pl.String for source_column in self.source_columns}
+
+
+def security_id_construction(
+    values: Mapping[str, object],
+    dataset_name: str,
+    error_message: Callable[[str], str],
+    *,
+    file_name: str | None = None,
+) -> SecurityIdConstruction | None:
+    """Return validated security-ID construction for one source dataset.
+
+    Args:
+        values: Parsed YAML root mapping.
+        dataset_name: Normalized source dataset name.
+        error_message: Callback that adds product-specific error context.
+        file_name: Optional ``files`` dataset-name override. Analytics uses
+            ``security_master`` for its security-master source.
+
+    Returns:
+        Construction settings for a security-bearing dataset. When
+        ``security_id`` is omitted, layouts that do not map ``security_id``
+        directly and do map both ``security_type`` and ``security_symbol`` use
+        the Axys/APX defaults. Other layouts return ``None``.
+
+    Raises:
+        PerfaudError: If the configuration shape, component names, or separator is
+            invalid.
+    """
+    if dataset_name not in _SECURITY_DATASETS:
+        return None
+    configured_file_name = file_name or dataset_name
+    raw_configuration = values.get(_SECURITY_ID_KEY)
+    if raw_configuration is None:
+        columns = source_file_columns(
+            values,
+            configured_file_name,
+            error_message,
+        )
+        if _SECURITY_ID_KEY in columns:
+            return None
+        if not all(component in columns for component in _DEFAULT_COMPONENTS):
+            return None
+        return SecurityIdConstruction(
+            components=_DEFAULT_COMPONENTS,
+            source_columns=_source_columns(
+                values,
+                configured_file_name,
+                _DEFAULT_COMPONENTS,
+                error_message,
+            ),
+            separator=_DEFAULT_SEPARATOR,
+        )
+    configuration = _require_mapping(
+        raw_configuration,
+        _SECURITY_ID_KEY,
+        error_message,
+    )
+    _reject_unknown_fields(
+        configuration,
+        _CONFIGURATION_FIELDS,
+        _SECURITY_ID_KEY,
+        error_message,
+    )
+
+    dataset_configuration: Mapping[str, object] = {}
+    raw_datasets = configuration.get(_DATASETS_KEY, {})
+    datasets = _require_mapping(
+        raw_datasets,
+        f"{_SECURITY_ID_KEY}.{_DATASETS_KEY}",
+        error_message,
+    )
+    _reject_unknown_fields(
+        datasets,
+        _SECURITY_DATASETS,
+        f"{_SECURITY_ID_KEY}.{_DATASETS_KEY}",
+        error_message,
+    )
+    raw_dataset_configuration = datasets.get(dataset_name)
+    if raw_dataset_configuration is not None:
+        dataset_configuration = _require_mapping(
+            raw_dataset_configuration,
+            f"{_SECURITY_ID_KEY}.{_DATASETS_KEY}.{dataset_name}",
+            error_message,
+        )
+        _reject_unknown_fields(
+            dataset_configuration,
+            _DATASET_FIELDS,
+            f"{_SECURITY_ID_KEY}.{_DATASETS_KEY}.{dataset_name}",
+            error_message,
+        )
+
+    components_value = dataset_configuration.get(
+        _COMPONENTS_KEY,
+        configuration.get(_COMPONENTS_KEY),
+    )
+    components = _validate_components(
+        components_value,
+        dataset_name,
+        error_message,
+    )
+    separator_value = dataset_configuration.get(
+        _SEPARATOR_KEY,
+        configuration.get(_SEPARATOR_KEY, _DEFAULT_SEPARATOR),
+    )
+    separator = _validate_separator(
+        separator_value,
+        dataset_name,
+        error_message,
+    )
+    source_columns = _source_columns(
+        values,
+        configured_file_name,
+        components,
+        error_message,
+    )
+    return SecurityIdConstruction(
+        components=components,
+        source_columns=source_columns,
+        separator=separator,
+    )
+
+
+def with_constructed_security_id(
+    frame: pl.DataFrame,
+    construction: SecurityIdConstruction,
+    *,
+    output_column: str,
+    dataset_name: str,
+    source_path: util.PathLike,
+    error_message: Callable[[str], str],
+) -> pl.DataFrame:
+    """Add a validated composite security identifier to a source frame.
+
+    Args:
+        frame: Raw source CSV frame.
+        construction: Ordered source columns and separator.
+        output_column: Temporary or normalized constructed-ID column name.
+        dataset_name: Normalized source dataset name for errors.
+        source_path: Source CSV path for errors.
+        error_message: Callback that adds product-specific error context.
+
+    Returns:
+        A new frame containing ``output_column``.
+
+    Raises:
+        PerfaudError: If a component column is missing, blank, padded with
+            whitespace, or produces an ambiguous composite identifier.
+
+    Notes:
+        Symbols may contain the configured separator. perfaud therefore checks
+        the observed component tuples for ambiguous concatenation instead of
+        rejecting legitimate Axys/APX symbols such as ``FUND_A``.
+    """
+    missing_columns = set(construction.source_columns) - set(frame.columns)
+    if missing_columns:
+        raise PerfaudError(
+            error_message(
+                f"Missing security_id component columns {sorted(missing_columns)} "
+                f"in {str(source_path)!r} for {dataset_name}. CSV columns "
+                f"available are: {sorted(frame.columns)}"
+            ),
+        )
+
+    string_expressions = {
+        component: pl.col(source_column).cast(pl.String, strict=False)
+        for component, source_column in zip(
+            construction.components,
+            construction.source_columns,
+            strict=True,
+        )
+    }
+    for component, source_column in zip(
+        construction.components,
+        construction.source_columns,
+        strict=True,
+    ):
+        string_expression = string_expressions[component]
+        stripped_expression = string_expression.str.strip_chars()
+        invalid_rows = frame.filter(
+            string_expression.is_null()
+            | stripped_expression.eq("")
+            | string_expression.ne(stripped_expression)
+        )
+        if not invalid_rows.is_empty():
+            value = invalid_rows.get_column(source_column)[0]
+            raise PerfaudError(
+                error_message(
+                    f"security_id component {component!r}, mapped to source column "
+                    f"{source_column!r}, contains a blank, null, or "
+                    f"whitespace-padded value {value!r} in {str(source_path)!r} "
+                    f"for {dataset_name}."
+                ),
+            )
+    result = frame.with_columns(
+        pl.concat_str(
+            [string_expressions[component] for component in construction.components],
+            separator=construction.separator,
+        ).alias(output_column)
+    )
+    collisions = (
+        result.select((*construction.source_columns, output_column))
+        .unique()
+        .group_by(output_column)
+        .len()
+        .filter(pl.col("len") > 1)
+    )
+    if not collisions.is_empty():
+        identifier = collisions.get_column(output_column)[0]
+        raise PerfaudError(
+            error_message(
+                f"Distinct security_id component tuples produce ambiguous "
+                f"identifier {identifier!r} in {str(source_path)!r} for "
+                f"{dataset_name}. Choose a different separator."
+            ),
+        )
+    return result
+
+
+def _require_mapping(
+    value: object,
+    field_path: str,
+    error_message: Callable[[str], str],
+) -> Mapping[str, object]:
+    """Return ``value`` as a mapping or raise a configuration error."""
+    if not isinstance(value, Mapping):
+        raise PerfaudError(error_message(f"{field_path} must be a mapping."))
+    return cast(Mapping[str, object], value)
+
+
+def _reject_unknown_fields(
+    values: Mapping[str, object],
+    allowed_fields: set[str],
+    field_path: str,
+    error_message: Callable[[str], str],
+) -> None:
+    """Raise when a security-ID configuration mapping has unknown fields."""
+    unknown_fields = set(values) - allowed_fields
+    if unknown_fields:
+        raise PerfaudError(
+            error_message(
+                f"Unknown fields for {field_path}: "
+                f"{sorted(map(str, unknown_fields))}"
+            ),
+        )
+
+
+def _validate_components(
+    value: object,
+    dataset_name: str,
+    error_message: Callable[[str], str],
+) -> tuple[str, ...]:
+    """Return validated ordered normalized security-ID component names."""
+    if not isinstance(value, list) or len(value) < 2:
+        raise PerfaudError(
+            error_message(
+                f"security_id components for {dataset_name} must be a list of "
+                "at least two normalized field names."
+            ),
+        )
+    if any(not isinstance(component, str) or not component for component in value):
+        raise PerfaudError(
+            error_message(
+                f"security_id components for {dataset_name} must be nonempty strings."
+            ),
+        )
+    components = tuple(value)
+    if len(set(components)) != len(components):
+        raise PerfaudError(
+            error_message(
+                f"security_id components for {dataset_name} must be distinct: "
+                f"{list(components)}"
+            ),
+        )
+    invalid_components = [
+        component
+        for component in components
+        if not component.isidentifier() or component.lower() != component
+    ]
+    if invalid_components:
+        raise PerfaudError(
+            error_message(
+                f"security_id components for {dataset_name} must use normalized "
+                f"field names: {invalid_components}"
+            ),
+        )
+    return components
+
+
+def _source_columns(
+    values: Mapping[str, object],
+    file_name: str,
+    components: tuple[str, ...],
+    error_message: Callable[[str], str],
+) -> tuple[str, ...]:
+    """Resolve normalized identity components through one file layout."""
+    section = source_file_columns(
+        values,
+        file_name,
+        error_message,
+    )
+    source_columns: list[str] = []
+    for component in components:
+        source_column = section.get(component, component)
+        if not isinstance(source_column, str) or not source_column:
+            raise PerfaudError(
+                error_message(
+                    f"files.{file_name}.columns.{component} must be a nonempty "
+                    "source column name."
+                ),
+            )
+        source_columns.append(source_column)
+    if len(set(source_columns)) != len(source_columns):
+        raise PerfaudError(
+            error_message(
+                f"security_id components for files.{file_name}.columns must map "
+                f"to distinct source columns: {source_columns}"
+            ),
+        )
+    return tuple(source_columns)
+
+
+def _validate_separator(
+    value: object,
+    dataset_name: str,
+    error_message: Callable[[str], str],
+) -> str:
+    """Return a validated composite security-ID separator."""
+    if not isinstance(value, str) or "\n" in value or "\r" in value:
+        raise PerfaudError(
+            error_message(
+                f"security_id separator for {dataset_name} must be a single-line "
+                "string."
+            ),
+        )
+    return value

perfaud/axys_apx/transaction_safety.py

@@ -0,0 +1,13 @@
+"""Fail-closed Axys/APX transaction boundaries.
+
+This module intentionally does not assign economic meaning. Local transaction
+meaning belongs in Audit ``transaction_rules``.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+AMBIGUOUS_FLOW_TRANSACTION_CODES: Final[frozenset[str]] = frozenset(
+    {"dp", "li", "lo", "ti", "wd"}
+)