de-scorpio 0.2.1__tar.gz

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.
@@ -0,0 +1,12 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ *.egg-info/
5
+ dist/
6
+ .coverage
7
+ coverage.xml
8
+ .pytest_cache/
9
+ .ruff_cache/
10
+ .arsenal/
11
+ data/
12
+ .DS_Store
@@ -0,0 +1,31 @@
1
+ Metadata-Version: 2.5
2
+ Name: de-scorpio
3
+ Version: 0.2.1
4
+ Summary: Scorpio — freshness, lineage and operational alerts
5
+ Project-URL: Homepage, https://github.com/KooEric/de-arsenal
6
+ Project-URL: Repository, https://github.com/KooEric/de-arsenal
7
+ License-Expression: Apache-2.0
8
+ Classifier: License :: OSI Approved :: Apache Software License
9
+ Classifier: Operating System :: OS Independent
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.11
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Requires-Python: >=3.11
14
+ Description-Content-Type: text/markdown
15
+
16
+ # Scorpio
17
+
18
+ 운영 관측 패키지. Arsenal 상태 DB의 마지막 완료 시각을 기준으로 freshness를
19
+ 판정하고 stale alert를 만든다.
20
+
21
+ PyPI 배포명은 `de-scorpio`이며 Python import 경로는 `scorpio`를 유지한다.
22
+
23
+ ```bash
24
+ pip install de-scorpio
25
+ ```
26
+
27
+ ```python
28
+ from scorpio import assess_freshness
29
+
30
+ status = assess_freshness(last_completed_at, max_age_seconds=3600)
31
+ ```
@@ -0,0 +1,16 @@
1
+ # Scorpio
2
+
3
+ 운영 관측 패키지. Arsenal 상태 DB의 마지막 완료 시각을 기준으로 freshness를
4
+ 판정하고 stale alert를 만든다.
5
+
6
+ PyPI 배포명은 `de-scorpio`이며 Python import 경로는 `scorpio`를 유지한다.
7
+
8
+ ```bash
9
+ pip install de-scorpio
10
+ ```
11
+
12
+ ```python
13
+ from scorpio import assess_freshness
14
+
15
+ status = assess_freshness(last_completed_at, max_age_seconds=3600)
16
+ ```
@@ -0,0 +1,26 @@
1
+ [project]
2
+ name = "de-scorpio"
3
+ version = "0.2.1"
4
+ description = "Scorpio — freshness, lineage and operational alerts"
5
+ readme = "README.md"
6
+ requires-python = ">=3.11"
7
+ license = "Apache-2.0"
8
+ dependencies = []
9
+ classifiers = [
10
+ "Programming Language :: Python :: 3",
11
+ "Programming Language :: Python :: 3.11",
12
+ "Programming Language :: Python :: 3.12",
13
+ "License :: OSI Approved :: Apache Software License",
14
+ "Operating System :: OS Independent",
15
+ ]
16
+
17
+ [project.urls]
18
+ Homepage = "https://github.com/KooEric/de-arsenal"
19
+ Repository = "https://github.com/KooEric/de-arsenal"
20
+
21
+ [build-system]
22
+ requires = ["hatchling"]
23
+ build-backend = "hatchling.build"
24
+
25
+ [tool.hatch.build.targets.wheel]
26
+ packages = ["src/scorpio"]
@@ -0,0 +1,12 @@
1
+ """Scorpio — operational freshness checks and alerts."""
2
+
3
+ from importlib.metadata import PackageNotFoundError, version
4
+
5
+ try:
6
+ __version__ = version("de-scorpio")
7
+ except PackageNotFoundError:
8
+ __version__ = "0.2.1"
9
+
10
+ from scorpio.freshness import Freshness, assess_freshness
11
+
12
+ __all__ = ["Freshness", "assess_freshness"]
@@ -0,0 +1,49 @@
1
+ """Deterministic freshness evaluation for state-store timestamps."""
2
+
3
+ from dataclasses import dataclass
4
+ from datetime import UTC, datetime
5
+
6
+
7
+ @dataclass(frozen=True)
8
+ class Freshness:
9
+ status: str # fresh | stale | unknown
10
+ age_seconds: float | None
11
+ max_age_seconds: float
12
+ last_completed_at: str | None
13
+ message: str
14
+
15
+ @property
16
+ def alert(self) -> bool:
17
+ return self.status == "stale"
18
+
19
+
20
+ def assess_freshness(
21
+ last_completed_at: str | None,
22
+ *,
23
+ max_age_seconds: float,
24
+ now: datetime | None = None,
25
+ ) -> Freshness:
26
+ """Classify the last completed run as fresh, stale, or unknown."""
27
+ if max_age_seconds <= 0:
28
+ raise ValueError("max_age_seconds must be positive")
29
+ if last_completed_at is None:
30
+ return Freshness(
31
+ status="unknown",
32
+ age_seconds=None,
33
+ max_age_seconds=max_age_seconds,
34
+ last_completed_at=None,
35
+ message="no completed unit has been recorded",
36
+ )
37
+ try:
38
+ completed = datetime.fromisoformat(last_completed_at)
39
+ except ValueError as e:
40
+ raise ValueError(f"invalid completion timestamp: {last_completed_at!r}") from e
41
+ if completed.tzinfo is None:
42
+ completed = completed.replace(tzinfo=UTC)
43
+ reference = now or datetime.now(UTC)
44
+ if reference.tzinfo is None:
45
+ reference = reference.replace(tzinfo=UTC)
46
+ age = max(0.0, (reference - completed).total_seconds())
47
+ status = "fresh" if age <= max_age_seconds else "stale"
48
+ message = f"last completion is {age:.1f}s old (limit {max_age_seconds:.1f}s)"
49
+ return Freshness(status, age, max_age_seconds, last_completed_at, message)
File without changes
@@ -0,0 +1,31 @@
1
+ from datetime import UTC, datetime, timedelta
2
+
3
+ import pytest
4
+ from scorpio import assess_freshness
5
+
6
+ NOW = datetime(2026, 8, 10, 12, 0, tzinfo=UTC)
7
+
8
+
9
+ def test_freshness_is_fresh_within_limit() -> None:
10
+ result = assess_freshness(
11
+ (NOW - timedelta(seconds=30)).isoformat(), max_age_seconds=60, now=NOW
12
+ )
13
+ assert result.status == "fresh"
14
+ assert result.alert is False
15
+
16
+
17
+ def test_freshness_emits_stale_alert() -> None:
18
+ result = assess_freshness(
19
+ (NOW - timedelta(seconds=61)).isoformat(), max_age_seconds=60, now=NOW
20
+ )
21
+ assert result.status == "stale"
22
+ assert result.alert is True
23
+ assert "61.0s" in result.message
24
+
25
+
26
+ def test_freshness_handles_unknown_and_invalid_input() -> None:
27
+ assert assess_freshness(None, max_age_seconds=60, now=NOW).status == "unknown"
28
+ with pytest.raises(ValueError, match="invalid completion"):
29
+ assess_freshness("not-a-timestamp", max_age_seconds=60, now=NOW)
30
+ with pytest.raises(ValueError, match="positive"):
31
+ assess_freshness(None, max_age_seconds=0, now=NOW)