pyinc 1.0.0__py3-none-any.whl

pyinc/__init__.py

@@ -0,0 +1,57 @@
+from .core import Input, query
+from .errors import (
+    CycleError,
+    MutationError,
+    PyIncError,
+    UnsupportedValueError,
+    UntrackedReadError,
+)
+from .explain import InspectionNode
+from .resources import (
+    DirectoryResource,
+    EnvResource,
+    FileResource,
+    FileStatResource,
+    FileStatSnapshot,
+)
+from .runtime import Database, DatabaseStatistics, DependencyGraphNode, QueryProfile
+from .value import (
+    FrozenAdapterValue,
+    FrozenDict,
+    FrozenList,
+    FrozenRecord,
+    FrozenSet,
+    ValueAdapter,
+    freeze,
+    semantic_equal,
+    thaw,
+)
+
+__all__ = [
+    "CycleError",
+    "Database",
+    "DatabaseStatistics",
+    "DependencyGraphNode",
+    "DirectoryResource",
+    "EnvResource",
+    "FileResource",
+    "FileStatResource",
+    "FileStatSnapshot",
+    "FrozenAdapterValue",
+    "FrozenDict",
+    "FrozenList",
+    "FrozenRecord",
+    "FrozenSet",
+    "Input",
+    "InspectionNode",
+    "MutationError",
+    "PyIncError",
+    "QueryProfile",
+    "UnsupportedValueError",
+    "UntrackedReadError",
+    "ValueAdapter",
+    "freeze",
+    "query",
+    "semantic_equal",
+    "thaw",
+]

pyinc/core.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from functools import wraps
+from typing import TYPE_CHECKING, Any, Concatenate, Generic, ParamSpec, TypeVar, overload
+
+from .value import semantic_equal
+
+if TYPE_CHECKING:
+    from .runtime import Database
+
+P = ParamSpec("P")
+T = TypeVar("T")
+EqFn = Callable[[Any, Any], bool]
+CutoffFn = Callable[[Any], Any]
+
+
+@dataclass(frozen=True)
+class Input(Generic[T]):
+    name: str
+    eq: EqFn | None = None
+    cutoff: CutoffFn | None = None
+
+    def __post_init__(self) -> None:
+        if self.eq is not None and self.cutoff is not None:
+            raise ValueError("Input() accepts either eq= or cutoff=, but not both.")
+
+    def read(self, db: Database) -> T:
+        return db._read_input(self)
+
+
+class Query(Generic[P, T]):
+    def __init__(
+        self,
+        fn: Callable[Concatenate[Database, P], T],
+        *,
+        eq: EqFn | None = None,
+        cutoff: CutoffFn | None = None,
+    ) -> None:
+        if eq is not None and cutoff is not None:
+            raise ValueError("@query accepts either eq= or cutoff=, but not both.")
+        self.fn = fn
+        self.eq = eq
+        self.cutoff = cutoff
+        self.query_id = f"{fn.__module__}:{fn.__qualname__}"
+        self.__name__ = fn.__name__
+        self.__doc__ = fn.__doc__
+        self.__module__ = fn.__module__
+        self.__wrapped__ = fn
+        wraps(fn)(self)
+
+    def __call__(self, db: Database, *args: P.args, **kwargs: P.kwargs) -> T:
+        return db.get(self, *args, **kwargs)
+
+    def compare(self, old_value: Any, new_value: Any) -> bool:
+        if self.cutoff is not None:
+            return semantic_equal(self.cutoff(old_value), self.cutoff(new_value))
+        comparator = self.eq or semantic_equal
+        return comparator(old_value, new_value)
+
+
+@overload
+def query(
+    fn: Callable[Concatenate[Database, P], T],
+    *,
+    eq: EqFn | None = None,
+    cutoff: CutoffFn | None = None,
+) -> Query[P, T]: ...
+
+
+@overload
+def query(
+    fn: None = None,
+    *,
+    eq: EqFn | None = None,
+    cutoff: CutoffFn | None = None,
+) -> Callable[[Callable[Concatenate[Database, P], T]], Query[P, T]]: ...
+
+
+def query(
+    fn: Callable[Concatenate[Database, P], T] | None = None,
+    *,
+    eq: EqFn | None = None,
+    cutoff: CutoffFn | None = None,
+) -> Query[P, T] | Callable[[Callable[Concatenate[Database, P], T]], Query[P, T]]:
+    def decorate(wrapped: Callable[Concatenate[Database, P], T]) -> Query[P, T]:
+        return Query(wrapped, eq=eq, cutoff=cutoff)
+
+    if fn is None:
+        return decorate
+    return decorate(fn)

pyinc/errors.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+
+class PyIncError(Exception):
+    """Base error for pyinc."""
+
+
+class MutationError(PyIncError):
+    """Raised when a query mutates one of its boundary inputs."""
+
+
+class UntrackedReadError(PyIncError):
+    """Raised when code performs an undeclared external read."""
+
+
+class UnsupportedValueError(PyIncError):
+    """Raised when a value cannot cross a cached boundary safely."""
+
+
+class CycleError(PyIncError):
+    """Raised when query evaluation encounters a dependency cycle."""

pyinc/explain.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class InspectionNode:
+    label: str
+    kind: str
+    changed_at: int
+    verified_at: int
+    last_decision: str
+    last_recompute: str
+    reason: str
+    untracked_reasons: tuple[str, ...] = ()
+    dependencies: tuple[InspectionNode, ...] = ()
+
+    @property
+    def is_untracked(self) -> bool:
+        return bool(self.untracked_reasons)
+
+
+def format_explanation(root: InspectionNode) -> str:
+    lines: list[str] = []
+
+    def walk(current: InspectionNode, depth: int) -> None:
+        indent = "  " * depth
+        lines.append(
+            f"{indent}- {current.label}: {current.last_decision}"
+            f" [last_recompute={current.last_recompute}]"
+            f" (changed_at={current.changed_at}, verified_at={current.verified_at})"
+        )
+        if current.reason:
+            lines.append(f"{indent}  reason: {current.reason}")
+        for item in current.untracked_reasons:
+            lines.append(f"{indent}  untracked: {item}")
+        for dependency in current.dependencies:
+            walk(dependency, depth + 1)
+
+    walk(root, 0)
+    return "\n".join(lines)

pyinc/integrations/__init__.py

@@ -0,0 +1,183 @@
+from .csv_data import (
+    CsvAnalysis,
+    CsvColumn,
+    csv_analysis,
+    workspace_csv_analysis,
+)
+from .deep_module_resolution import (
+    DeepModuleResolutionAnalysis,
+    ModulePathEntry,
+    NamespacePackage,
+    PthDirective,
+    ResolvedModuleLocation,
+    deep_module_resolution_analysis,
+    resolve_module_path,
+)
+from .dependency_check import (
+    DependencyCheckAnalysis,
+    DependencyStatus,
+    UndeclaredImport,
+    dependency_check_analysis,
+    workspace_dependency_check,
+)
+from .env_file import (
+    EnvEntry,
+    EnvFileAnalysis,
+    env_analysis,
+    workspace_env_analysis,
+)
+from .installed_packages import (
+    ImportNameResolution,
+    InstalledPackageRef,
+    InstalledPackagesAnalysis,
+    installed_packages_analysis,
+    resolve_import_name,
+)
+from .json_config import (
+    JsonAnalysis,
+    JsonKey,
+    JsonSection,
+    json_analysis,
+    workspace_json_analysis,
+)
+from .python_source import (
+    DefinitionRef,
+    DependencySurface,
+    Diagnostic,
+    ImportRef,
+    PythonFileAnalysis,
+    PythonModuleAnalysis,
+    PythonWorkspaceAnalysis,
+    ResolvedImportRef,
+    directory_analysis,
+    file_analysis,
+    module_analysis,
+    workspace_analysis,
+)
+from .requirement_evaluation import (
+    ApplicableRequirement,
+    ApplicableRequirementsAnalysis,
+    MarkerEvaluation,
+    PythonEnvironmentSnapshot,
+    VersionSpecifierEvaluation,
+    applicable_requirements,
+    evaluate_markers,
+    evaluate_version_specifier,
+    workspace_applicable_requirements,
+)
+from .requirements_txt import (
+    FileReference,
+    IndexDirective,
+    RequirementRef,
+    RequirementsAnalysis,
+    deep_requirements_analysis,
+    requirements_analysis,
+    workspace_requirements_analysis,
+)
+from .symbol_resolution import (
+    ModuleSymbolTable,
+    Parameter,
+    ResolvedSymbol,
+    Signature,
+    Symbol,
+    WorkspaceSymbolEntry,
+    WorkspaceSymbolIndex,
+    module_symbol_table,
+    resolve_symbol,
+    workspace_symbol_index,
+)
+from .toml_config import (
+    ConfigAnalysis,
+    ConfigKey,
+    ConfigSection,
+    config_analysis,
+    workspace_config_analysis,
+)
+from .xml_config import (
+    XmlAnalysis,
+    XmlAttribute,
+    XmlElement,
+    workspace_xml_analysis,
+    xml_analysis,
+)
+
+__all__ = [
+    "ApplicableRequirement",
+    "ApplicableRequirementsAnalysis",
+    "ConfigAnalysis",
+    "ConfigKey",
+    "ConfigSection",
+    "CsvAnalysis",
+    "CsvColumn",
+    "DeepModuleResolutionAnalysis",
+    "DefinitionRef",
+    "DependencyCheckAnalysis",
+    "DependencyStatus",
+    "DependencySurface",
+    "Diagnostic",
+    "EnvEntry",
+    "EnvFileAnalysis",
+    "FileReference",
+    "ImportNameResolution",
+    "ImportRef",
+    "IndexDirective",
+    "InstalledPackageRef",
+    "InstalledPackagesAnalysis",
+    "JsonAnalysis",
+    "JsonKey",
+    "JsonSection",
+    "MarkerEvaluation",
+    "ModulePathEntry",
+    "ModuleSymbolTable",
+    "NamespacePackage",
+    "Parameter",
+    "PthDirective",
+    "PythonEnvironmentSnapshot",
+    "PythonFileAnalysis",
+    "PythonModuleAnalysis",
+    "PythonWorkspaceAnalysis",
+    "RequirementRef",
+    "RequirementsAnalysis",
+    "ResolvedImportRef",
+    "ResolvedModuleLocation",
+    "ResolvedSymbol",
+    "Signature",
+    "Symbol",
+    "UndeclaredImport",
+    "VersionSpecifierEvaluation",
+    "WorkspaceSymbolEntry",
+    "WorkspaceSymbolIndex",
+    "XmlAnalysis",
+    "XmlAttribute",
+    "XmlElement",
+    "applicable_requirements",
+    "config_analysis",
+    "csv_analysis",
+    "deep_module_resolution_analysis",
+    "deep_requirements_analysis",
+    "dependency_check_analysis",
+    "directory_analysis",
+    "env_analysis",
+    "evaluate_markers",
+    "evaluate_version_specifier",
+    "file_analysis",
+    "installed_packages_analysis",
+    "json_analysis",
+    "module_analysis",
+    "module_symbol_table",
+    "requirements_analysis",
+    "resolve_import_name",
+    "resolve_module_path",
+    "resolve_symbol",
+    "workspace_analysis",
+    "workspace_applicable_requirements",
+    "workspace_config_analysis",
+    "workspace_csv_analysis",
+    "workspace_dependency_check",
+    "workspace_env_analysis",
+    "workspace_json_analysis",
+    "workspace_requirements_analysis",
+    "workspace_symbol_index",
+    "workspace_xml_analysis",
+    "xml_analysis",
+]

pyinc/integrations/csv_data.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import csv
+import hashlib
+import io
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TypeAlias, cast
+
+from pyinc.core import query
+from pyinc.resources import DirectoryResource, _file_read_snapshot
+from pyinc.runtime import Database
+from pyinc.value import freeze, thaw
+
+CsvColumnPayload: TypeAlias = tuple[str, int]
+DiagnosticPayload: TypeAlias = tuple[str, str]
+CsvMetaPayload: TypeAlias = tuple[int, str, bool]
+CsvAnalysisPayload: TypeAlias = tuple[
+    str,                              # path
+    tuple[CsvColumnPayload, ...],     # columns
+    int,                              # row_count
+    str,                              # delimiter
+    bool,                             # has_header
+    tuple[DiagnosticPayload, ...],    # diagnostics
+]
+
+
+@dataclass(frozen=True)
+class CsvColumn:
+    name: str
+    index: int
+
+
+@dataclass(frozen=True)
+class CsvAnalysis:
+    path: str
+    columns: tuple[CsvColumn, ...]
+    row_count: int
+    delimiter: str
+    has_header: bool
+    diagnostics: tuple[tuple[str, str], ...]
+
+
+# ---------------------------------------------------------------------------
+# Resources
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class _CsvFileResource:
+    encoding: str = "utf-8"
+
+    def read(self, db: Database, path: str | os.PathLike[str]) -> str:
+        return cast(str, db._read_resource(self, os.fspath(path)))
+
+    def label(self, path: str) -> str:
+        return f"csvfile[{path}]"
+
+    def probe(self, path: str) -> tuple[str, str] | tuple[str]:
+        file_path = Path(path)
+        if not file_path.exists():
+            return ("missing",)
+        return ("present", hashlib.sha256(file_path.read_bytes()).hexdigest())
+
+    def load(self, db: Database, path: str) -> str:
+        file_path = Path(path)
+        if not file_path.exists():
+            return ""
+        with db._allow_raw_open():
+            return file_path.read_text(encoding=self.encoding)
+
+    def probe_and_load(
+        self, db: Database, path: str
+    ) -> tuple[tuple[str, str] | tuple[str], str]:
+        probe, text = _file_read_snapshot(path, self.encoding)
+        return probe, text if text is not None else ""
+
+
+_FILES = _CsvFileResource()
+_DIRECTORIES = DirectoryResource()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _detect_delimiter(text: str) -> str:
+    try:
+        dialect = csv.Sniffer().sniff(text[:8192])
+        return dialect.delimiter
+    except csv.Error:
+        return ","
+
+
+def _detect_has_header(text: str) -> bool:
+    try:
+        return csv.Sniffer().has_header(text[:8192])
+    except csv.Error:
+        return False
+
+
+def _parse_csv(
+    text: str,
+) -> tuple[list[CsvColumnPayload], int, str, bool, list[DiagnosticPayload]]:
+    stripped = text.strip()
+    if not stripped:
+        return [], 0, ",", False, []
+
+    delimiter = _detect_delimiter(stripped)
+    has_header = _detect_has_header(stripped)
+
+    reader = csv.reader(io.StringIO(stripped), delimiter=delimiter)
+    rows = list(reader)
+
+    if not rows:
+        return [], 0, delimiter, has_header, []
+
+    diagnostics: list[DiagnosticPayload] = []
+
+    if has_header:
+        header_row = rows[0]
+        data_rows = rows[1:]
+        columns: list[CsvColumnPayload] = [
+            (name, idx) for idx, name in enumerate(header_row)
+        ]
+    else:
+        data_rows = rows
+        col_count = len(rows[0]) if rows else 0
+        columns = [(f"column_{idx}", idx) for idx in range(col_count)]
+
+    expected_cols = len(columns)
+    for row_idx, row in enumerate(data_rows):
+        if len(row) != expected_cols:
+            diagnostics.append(
+                (
+                    "inconsistent-columns",
+                    f"row {row_idx + 1 + (1 if has_header else 0)}: "
+                    f"expected {expected_cols} columns, got {len(row)}",
+                )
+            )
+
+    row_count = len(data_rows)
+    return columns, row_count, delimiter, has_header, diagnostics
+
+
+def _csv_cutoff_token(text: str) -> tuple[str, str]:
+    columns, row_count, delimiter, has_header, _ = _parse_csv(text)
+    snapshot = freeze((columns, row_count, delimiter, has_header))
+    return ("parsed", repr(snapshot))
+
+
+# ---------------------------------------------------------------------------
+# Layer 1 — Payload queries
+# ---------------------------------------------------------------------------
+
+
+@query(cutoff=_csv_cutoff_token)
+def csv_file_text(db: Database, path: str) -> str:
+    return _FILES.read(db, path)
+
+
+@query
+def csv_columns_payload(db: Database, path: str) -> tuple[CsvColumnPayload, ...]:
+    text = csv_file_text(db, path)
+    if not text.strip():
+        return ()
+    columns, _, _, _, _ = _parse_csv(text)
+    return tuple(columns)
+
+
+@query
+def csv_meta_payload(db: Database, path: str) -> CsvMetaPayload:
+    text = csv_file_text(db, path)
+    if not text.strip():
+        return (0, ",", False)
+    _, row_count, delimiter, has_header, _ = _parse_csv(text)
+    return (row_count, delimiter, has_header)
+
+
+@query
+def csv_diagnostics_payload(db: Database, path: str) -> tuple[DiagnosticPayload, ...]:
+    text = csv_file_text(db, path)
+    if not text.strip():
+        return ()
+    _, _, _, _, diagnostics = _parse_csv(text)
+    return tuple(diagnostics)
+
+
+# ---------------------------------------------------------------------------
+# Layer 2 — Composition
+# ---------------------------------------------------------------------------
+
+
+@query
+def csv_analysis_payload(db: Database, path: str) -> CsvAnalysisPayload:
+    columns = csv_columns_payload(db, path)
+    meta = csv_meta_payload(db, path)
+    diagnostics = csv_diagnostics_payload(db, path)
+    row_count, delimiter, has_header = meta
+    return (path, columns, row_count, delimiter, has_header, diagnostics)
+
+
+# ---------------------------------------------------------------------------
+# Layer 3 — Entrypoints
+# ---------------------------------------------------------------------------
+
+
+def csv_analysis(db: Database, path: str | os.PathLike[str]) -> CsvAnalysis:
+    normalized = os.fspath(path)
+    payload = cast(CsvAnalysisPayload, thaw(db.get(csv_analysis_payload, normalized)))
+    path_str, columns, row_count, delimiter, has_header, diagnostics = payload
+    return CsvAnalysis(
+        path=path_str,
+        columns=tuple(CsvColumn(name=c[0], index=c[1]) for c in columns),
+        row_count=row_count,
+        delimiter=delimiter,
+        has_header=has_header,
+        diagnostics=diagnostics,
+    )
+
+
+def workspace_csv_analysis(
+    db: Database,
+    root: str | os.PathLike[str],
+    filename: str = "data.csv",
+) -> CsvAnalysis | None:
+    normalized_root = os.fspath(root)
+    dir_entries = _DIRECTORIES.read(db, normalized_root)
+    csv_path = None
+    for name in dir_entries:
+        if name == filename:
+            csv_path = str(Path(normalized_root) / name)
+            break
+    if csv_path is None:
+        return None
+    return csv_analysis(db, csv_path)
+
+
+__all__ = [
+    "CsvColumn",
+    "CsvAnalysis",
+    "csv_analysis",
+    "workspace_csv_analysis",
+]