quaxdim 0.9.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
quaxdim/__init__.py ADDED
@@ -0,0 +1,82 @@
1
+ """QuaxDim: lazily-loaded public API.
2
+
3
+ The high-volume advisor does not import pandas, Spark, Polars or DuckDB merely
4
+ because the top-level package was imported. Engines load only when requested.
5
+ """
6
+
7
+ from importlib import import_module
8
+ from typing import Any
9
+
10
+ from ._version import __version__ as __version__
11
+
12
+ _EXPORTS = {
13
+ **{
14
+ k: "core"
15
+ for k in ("Check", "QualitySuite", "QualityReport", "RuleResult")
16
+ },
17
+ "profile": "profile",
18
+ **{k: "catalog" for k in ("CATALOG", "DimensionSpec", "list_dimensions")},
19
+ **{
20
+ k: "applicability"
21
+ for k in (
22
+ "ApplicabilityPlanner",
23
+ "EvaluationPlan",
24
+ "Decision",
25
+ "Reason",
26
+ "Capability",
27
+ "ContractError",
28
+ "load_contract",
29
+ )
30
+ },
31
+ **{
32
+ k: "execution"
33
+ for k in (
34
+ "ContractExecutor",
35
+ "ContractExecutionReport",
36
+ "ContractRuleResult",
37
+ "EvaluationError",
38
+ )
39
+ },
40
+ **{
41
+ k: "spark_backend"
42
+ for k in ("SparkContractExecutor", "SparkBackendUnavailableError")
43
+ },
44
+ "evaluate_contract": "runtime",
45
+ **{
46
+ k: "optimized"
47
+ for k in (
48
+ "plan_optimized",
49
+ "evaluate_optimized",
50
+ "OptimizedPlan",
51
+ "OptimizedReport",
52
+ )
53
+ },
54
+ **{k: "approval" for k in ("build_reviewed_contract", "ApprovalError")},
55
+ **{
56
+ k: "discovery"
57
+ for k in ("discover", "DiscoveryReport", "Recommendation")
58
+ },
59
+ **{k: "evaluator_registry" for k in ("list_evaluators", "REGISTRY")},
60
+ **{
61
+ k: "advanced_discovery"
62
+ for k in (
63
+ "discover_advanced",
64
+ "DiscoveryBudget",
65
+ "AdvancedDiscoveryReport",
66
+ "Advice",
67
+ )
68
+ },
69
+ }
70
+ __all__ = list(_EXPORTS)
71
+
72
+
73
+ def __getattr__(name: str) -> Any:
74
+ if name in _EXPORTS:
75
+ value = getattr(import_module("." + _EXPORTS[name], __name__), name)
76
+ globals()[name] = value
77
+ return value
78
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
79
+
80
+
81
+ def __dir__() -> list[str]:
82
+ return sorted(set(globals()) | set(_EXPORTS))
quaxdim/__main__.py ADDED
@@ -0,0 +1,6 @@
1
+ """Run the QuaxDim CLI with ``python -m quaxdim``."""
2
+
3
+ from quaxdim.cli import main
4
+
5
+ if __name__ == "__main__":
6
+ raise SystemExit(main())
quaxdim/_io.py ADDED
@@ -0,0 +1,58 @@
1
+ """Small file-system helpers shared by reports and the CLI."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import tempfile
7
+ from datetime import datetime, timezone
8
+ from pathlib import Path
9
+
10
+
11
+ def write_text_atomic(path: str | Path, text: str) -> None:
12
+ """Write ``text`` to ``path`` so readers never see a partial file.
13
+
14
+ The content goes to a temporary file in the same directory and is
15
+ moved into place with ``os.replace``, which is atomic on POSIX and on
16
+ Windows. A crash mid-write leaves the previous file untouched.
17
+ """
18
+ target = Path(path)
19
+ target.parent.mkdir(parents=True, exist_ok=True)
20
+ handle, temporary = tempfile.mkstemp(
21
+ prefix=f".{target.name}.", suffix=".tmp", dir=target.parent
22
+ )
23
+ try:
24
+ with os.fdopen(handle, "w", encoding="utf-8", newline="\n") as f:
25
+ f.write(text)
26
+ f.flush()
27
+ os.fsync(f.fileno())
28
+ os.replace(temporary, target)
29
+ except BaseException:
30
+ Path(temporary).unlink(missing_ok=True)
31
+ raise
32
+
33
+
34
+ def describe_source(source: object) -> dict[str, object]:
35
+ """Describe a data source for the audit trail without reading it.
36
+
37
+ File sources record path, size and modification time, enough to tell
38
+ later whether the same file was evaluated. In-memory frames record
39
+ only their type: the report never stores rows or values.
40
+ """
41
+ if isinstance(source, (str, Path)):
42
+ path = Path(source)
43
+ description: dict[str, object] = {
44
+ "kind": "file",
45
+ "path": str(path),
46
+ }
47
+ try:
48
+ stat = path.stat()
49
+ except OSError:
50
+ description["exists"] = False
51
+ return description
52
+ description["size_bytes"] = stat.st_size
53
+ description["modified_at"] = datetime.fromtimestamp(
54
+ stat.st_mtime, tz=timezone.utc
55
+ ).isoformat()
56
+ return description
57
+ kind = type(source)
58
+ return {"kind": "in_memory", "type": f"{kind.__module__}.{kind.__name__}"}
quaxdim/_lazy.py ADDED
@@ -0,0 +1,45 @@
1
+ """Lazy access to optional third-party modules.
2
+
3
+ pandas and numpy are optional extras (``pip install "quaxdim[pandas]"``).
4
+ Modules that need them bind a :class:`LazyModule` at import time, so the
5
+ package stays importable without them and fails only when a pandas-based
6
+ feature is actually used, with an actionable message.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import importlib
12
+ from types import ModuleType
13
+ from typing import Any
14
+
15
+
16
+ class LazyModule:
17
+ """Proxy that imports ``module_name`` on first attribute access.
18
+
19
+ Args:
20
+ module_name: Importable module name, for example ``"pandas"``.
21
+ extra: Name of the ``quaxdim`` extra that installs the module.
22
+ """
23
+
24
+ def __init__(self, module_name: str, extra: str) -> None:
25
+ self._module_name = module_name
26
+ self._extra = extra
27
+ self._module: ModuleType | None = None
28
+
29
+ def _load(self) -> ModuleType:
30
+ if self._module is None:
31
+ try:
32
+ self._module = importlib.import_module(self._module_name)
33
+ except ImportError as exc:
34
+ raise ImportError(
35
+ f"This feature requires {self._module_name!r}. "
36
+ f'Install it with: pip install "quaxdim[{self._extra}]"'
37
+ ) from exc
38
+ return self._module
39
+
40
+ def __getattr__(self, name: str) -> Any:
41
+ return getattr(self._load(), name)
42
+
43
+ def __repr__(self) -> str:
44
+ state = "loaded" if self._module is not None else "not loaded"
45
+ return f"<LazyModule {self._module_name!r} ({state})>"
quaxdim/_types.py ADDED
@@ -0,0 +1,16 @@
1
+ """Shared type aliases.
2
+
3
+ Optional engines (PySpark, Polars, DuckDB) are never imported at
4
+ type-checking time, so their objects are typed with documented aliases.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from typing import Any, TypeAlias
10
+
11
+ #: A PySpark ``DataFrame`` (PySpark is an optional dependency).
12
+ SparkFrame: TypeAlias = Any
13
+ #: A PySpark ``Column`` expression.
14
+ SparkColumn: TypeAlias = Any
15
+ #: An optional engine module passed around lazily (``polars``, ``functions``).
16
+ EngineModule: TypeAlias = Any
quaxdim/_version.py ADDED
@@ -0,0 +1,3 @@
1
+ """Single source of truth for the package version."""
2
+
3
+ __version__ = "0.9.0"