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.
- de_scorpio-0.2.1/.gitignore +12 -0
- de_scorpio-0.2.1/PKG-INFO +31 -0
- de_scorpio-0.2.1/README.md +16 -0
- de_scorpio-0.2.1/pyproject.toml +26 -0
- de_scorpio-0.2.1/src/scorpio/__init__.py +12 -0
- de_scorpio-0.2.1/src/scorpio/freshness.py +49 -0
- de_scorpio-0.2.1/src/scorpio/py.typed +0 -0
- de_scorpio-0.2.1/tests/test_freshness.py +31 -0
|
@@ -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)
|