detectkit 0.8.1__tar.gz → 0.9.0__tar.gz

{detectkit-0.8.1/detectkit.egg-info → detectkit-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.8.1
+Version: 0.9.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT

{detectkit-0.8.1 → detectkit-0.9.0}/detectkit/__init__.py

@@ -4,7 +4,7 @@ detectk - Anomaly Detection for Time-Series Metrics
 A Python library for data analysts and engineers to monitor metrics with automatic anomaly detection.
 """
 
-__version__ = "0.8.1"
+__version__ = "0.9.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.8.1 → detectkit-0.9.0}/detectkit/alerting/channels/base.py

@@ -36,6 +36,15 @@ class AlertData:
             as ``{project_name}`` in templates and as a ``[name] `` prefix
             in the default error title. Lets multiple projects share the
             same alert channel without ambiguity.
+
+    Alert-rule fields (``min_detectors``, ``direction_policy``,
+    ``consecutive_required``, ``detector_count``) describe *why the alert
+    fired* — the configured quorum/direction/consecutive thresholds plus
+    the observed number of agreeing detectors. They are filled by the
+    orchestrator from :class:`AlertConditions` and are deliberately kept
+    distinct from the observed ``direction``/``consecutive_count`` above so
+    templates can contrast "required vs actual". They default to ``None``
+    so direct-API callers (and non-anomaly alerts) still render cleanly.
     """
 
     metric_name: str
@@ -58,6 +67,11 @@ class AlertData:
     description: str | None = None
     mentions: list[str] = field(default_factory=list)
     project_name: str | None = None
+    # Alert rule (the parameters the alert fired with) — see class docstring.
+    min_detectors: int | None = None
+    direction_policy: str | None = None
+    consecutive_required: int | None = None
+    detector_count: int = 1
 
 
 class BaseAlertChannel(ABC):
@@ -123,10 +137,17 @@ class BaseAlertChannel(ABC):
         - {value} / {value_display}
         - {confidence_lower}
         - {confidence_upper}
+        - {confidence_interval} — "[lower, upper]" or "N/A"
+        - {expected_range} — one-sided aware: ">= lo", "<= hi",
+          "[lo, hi]" or "N/A" (renders one-sided detector bounds cleanly)
         - {detector_name}
-        - {direction}
+        - {detector_count} — observed detectors that agreed (the quorum)
+        - {direction} — observed/locked direction of the anomaly
+        - {direction_policy} — configured direction rule ("same"/"any"/...)
+        - {min_detectors} — configured quorum threshold (the rule)
+        - {consecutive_count} — observed consecutive points
+        - {consecutive_required} — configured consecutive threshold (rule)
         - {severity}
-        - {consecutive_count}
         - {status}
 
         Args:
@@ -177,6 +198,40 @@ class BaseAlertChannel(ABC):
         else:
             confidence_str = "N/A"
 
+        # One-sided-aware expected range. A NaN/inf bound means "no bound on
+        # that side" (e.g. ManualBounds with only ``lower_bound`` set), so we
+        # render ">= lo" / "<= hi" instead of the confusing "[7.00, nan]".
+        def _bounded(b: Any) -> bool:
+            return b is not None and not (isinstance(b, float) and (math.isnan(b) or math.isinf(b)))
+
+        lo_ok = _bounded(alert_data.confidence_lower)
+        hi_ok = _bounded(alert_data.confidence_upper)
+        if lo_ok and hi_ok:
+            expected_range = (
+                f"[{alert_data.confidence_lower:.2f}, {alert_data.confidence_upper:.2f}]"
+            )
+        elif lo_ok:
+            expected_range = f">= {alert_data.confidence_lower:.2f}"
+        elif hi_ok:
+            expected_range = f"<= {alert_data.confidence_upper:.2f}"
+        else:
+            expected_range = "N/A"
+
+        # Alert-rule display values. The orchestrator fills these from the
+        # configured AlertConditions; for direct-API/non-anomaly callers that
+        # leave them unset we fall back to the observed counts so the default
+        # templates never render a bare "None".
+        detector_count = alert_data.detector_count
+        min_detectors = (
+            alert_data.min_detectors if alert_data.min_detectors is not None else detector_count
+        )
+        consecutive_required = (
+            alert_data.consecutive_required
+            if alert_data.consecutive_required is not None
+            else alert_data.consecutive_count
+        )
+        direction_policy = alert_data.direction_policy or alert_data.direction
+
         # Display-safe value: stays usable even when value is None/NaN (no-data).
         raw_value = alert_data.value
         if raw_value is None or (isinstance(raw_value, float) and math.isnan(raw_value)):
@@ -221,11 +276,16 @@ class BaseAlertChannel(ABC):
                 confidence_lower=alert_data.confidence_lower,
                 confidence_upper=alert_data.confidence_upper,
                 confidence_interval=confidence_str,
+                expected_range=expected_range,
                 detector_name=alert_data.detector_name,
+                detector_count=detector_count,
                 detector_params=alert_data.detector_params,
                 direction=alert_data.direction,
+                direction_policy=direction_policy,
+                min_detectors=min_detectors,
                 severity=alert_data.severity,
                 consecutive_count=alert_data.consecutive_count,
+                consecutive_required=consecutive_required,
                 status=status,
                 error_type=alert_data.error_type or "",
                 error_message=alert_data.error_message or "",
@@ -312,12 +372,19 @@ class BaseAlertChannel(ABC):
             Default template string
         """
         return (
-            "Anomaly detected in metric: {metric_name}\n"
+            "⚠ Alert: {metric_name}\n"
             "{description_line}"
-            "Time: {timestamp}\n"
-            "Value: {value} | CI: {confidence_interval}\n"
-            "Direction: {direction} | Severity: {severity:.2f} | Consecutive: {consecutive_count}\n"
-            "Detector: {detector_name}\n"
+            "Quorum {detector_count}/{min_detectors} · "
+            "direction {direction} (policy {direction_policy}) · "
+            "consecutive {consecutive_count}/{consecutive_required}\n"
+            "Rule: min_detectors={min_detectors} · "
+            "direction={direction_policy} · consecutive={consecutive_required}\n"
+            "\n"
+            "Latest point (evidence):\n"
+            "· Time: {timestamp}\n"
+            "· Value: {value_display} | Expected: {expected_range}\n"
+            "· Severity: {severity:.2f}\n"
+            "Detectors: {detector_name}\n"
             "Parameters: {detector_params}"
             "{mentions_line}"
         )
@@ -330,12 +397,17 @@ class BaseAlertChannel(ABC):
             Default recovery template string
         """
         return (
-            "Metric recovered: {metric_name}\n"
+            "✅ Alert cleared: {metric_name}\n"
             "{description_line}"
-            "Time: {timestamp}\n"
-            "Value: {value} | CI: {confidence_interval}\n"
-            "Detector: {detector_name}\n"
-            "Status: metric returned to normal"
+            "The alert condition no longer holds — "
+            "the metric is back within expected bounds.\n"
+            "Rule: min_detectors={min_detectors} · "
+            "direction={direction_policy} · consecutive={consecutive_required}\n"
+            "\n"
+            "Latest point:\n"
+            "· Time: {timestamp}\n"
+            "· Value: {value_display} | Expected: {expected_range}\n"
+            "Detectors: {detector_name}"
             "{mentions_line}"
         )
 
@@ -348,7 +420,7 @@ class BaseAlertChannel(ABC):
         Returns:
             Default title template string
         """
-        return "Anomaly detected: {metric_name}"
+        return "⚠ Alert: {metric_name}"
 
     def get_default_recovery_title_template(self) -> str:
         """
@@ -357,7 +429,7 @@ class BaseAlertChannel(ABC):
         Returns:
             Default recovery title template string
         """
-        return "Metric recovered: {metric_name}"
+        return "✅ Alert cleared: {metric_name}"
 
     def get_default_no_data_template(self) -> str:
         """

{detectkit-0.8.1 → detectkit-0.9.0}/detectkit/alerting/channels/email.py

@@ -54,7 +54,7 @@ class EmailChannel(BaseAlertChannel):
         smtp_username: str | None = None,
         smtp_password: str | None = None,
         use_tls: bool = True,
-        subject_template: str = "Anomaly Alert: {metric_name}",
+        subject_template: str = "⚠ Alert: {metric_name}",
         template: str | None = None,
         **kwargs,
     ):

{detectkit-0.8.1 → detectkit-0.9.0}/detectkit/alerting/channels/webhook.py

@@ -155,10 +155,17 @@ class WebhookChannel(BaseAlertChannel):
         """
         return (
             "{description_line}"
-            "Time: {timestamp}\n"
-            "Value: {value} | CI: {confidence_interval}\n"
-            "Direction: {direction} | Severity: {severity:.2f} | Consecutive: {consecutive_count}\n"
-            "Detector: {detector_name}\n"
+            "Quorum {detector_count}/{min_detectors} · "
+            "direction {direction} (policy {direction_policy}) · "
+            "consecutive {consecutive_count}/{consecutive_required}\n"
+            "Rule: min_detectors={min_detectors} · "
+            "direction={direction_policy} · consecutive={consecutive_required}\n"
+            "\n"
+            "Latest point (evidence):\n"
+            "· Time: {timestamp}\n"
+            "· Value: {value_display} | Expected: {expected_range}\n"
+            "· Severity: {severity:.2f}\n"
+            "Detectors: {detector_name}\n"
             "Parameters: {detector_params}"
             "{mentions_line}"
         )
@@ -171,10 +178,15 @@ class WebhookChannel(BaseAlertChannel):
         """
         return (
             "{description_line}"
-            "Time: {timestamp}\n"
-            "Value: {value} | CI: {confidence_interval}\n"
-            "Detector: {detector_name}\n"
-            "Status: metric returned to normal"
+            "The alert condition no longer holds — "
+            "the metric is back within expected bounds.\n"
+            "Rule: min_detectors={min_detectors} · "
+            "direction={direction_policy} · consecutive={consecutive_required}\n"
+            "\n"
+            "Latest point:\n"
+            "· Time: {timestamp}\n"
+            "· Value: {value_display} | Expected: {expected_range}\n"
+            "Detectors: {detector_name}"
             "{mentions_line}"
         )
 

{detectkit-0.8.1 → detectkit-0.9.0}/detectkit/alerting/orchestrator/_decision.py

@@ -207,6 +207,23 @@ class _DecisionMixin(_OrchestratorBase):
             detector_params = primary.detector_params
             combined_metadata = primary.detection_metadata
 
+        # Observed direction shown in the message. For "same"/"up"/"down" the
+        # caller passes the locked/policy direction. For "any" it passes None
+        # because the quorum may combine directions — collapse to the shared
+        # side only when every quorum member agrees, otherwise label it
+        # "mixed" so the message never claims an agreement that did not happen
+        # (e.g. one up + one down satisfying min_detectors=2).
+        if direction:
+            observed_direction = direction
+        else:
+            quorum_dirs = {d.direction for d in anomalies if d.direction in ("up", "down")}
+            if len(quorum_dirs) == 1:
+                observed_direction = next(iter(quorum_dirs))
+            elif len(quorum_dirs) >= 2:
+                observed_direction = "mixed"
+            else:
+                observed_direction = primary.direction
+
         return AlertData(
             metric_name=self.metric_name,
             timestamp=primary.timestamp,
@@ -216,12 +233,18 @@ class _DecisionMixin(_OrchestratorBase):
             confidence_upper=primary.confidence_upper,
             detector_name=detector_name,
             detector_params=detector_params,
-            direction=direction or primary.direction,
+            direction=observed_direction,
             severity=max_severity,
             detection_metadata=combined_metadata,
             consecutive_count=consecutive_count,
             description=self.description,
             mentions=self.mentions,
+            # Alert rule the message foregrounds: configured thresholds plus
+            # the observed quorum size that satisfied them.
+            min_detectors=self.conditions.min_detectors,
+            direction_policy=self.conditions.direction,
+            consecutive_required=self.conditions.consecutive_anomalies,
+            detector_count=len(anomalies),
         )
 
     def should_alert_no_data(

{detectkit-0.8.1 → detectkit-0.9.0}/detectkit/alerting/orchestrator/_recovery.py

@@ -176,4 +176,9 @@ class _RecoveryMixin(_OrchestratorBase):
             is_recovery=True,
             description=self.description,
             mentions=self.mentions,
+            # Echo the rule that had fired so the recovery message names the
+            # same alert condition that just cleared.
+            min_detectors=self.conditions.min_detectors,
+            direction_policy=self.conditions.direction,
+            consecutive_required=self.conditions.consecutive_anomalies,
         )

detectkit-0.9.0/detectkit/cli/_output.py

@@ -0,0 +1,50 @@
+"""Shared CLI output helpers so every command renders in one house style.
+
+Mirrors the load → detect → alert pipeline's tree look (``┌─ / │ / └─``) used by
+``dtk run`` so the maintenance commands (``dtk clean``, ``dtk unlock``) match it
+instead of each inventing its own formatting.
+
+House conventions:
+- A metric *with* something to report is a tree: a cyan-bold ``┌─ <name>``
+  header followed by one child line per item (``│   `` for all but the last,
+  ``└─ `` for the last).
+- A metric with *nothing* to do is a single ``•`` line.
+- A per-metric error is a red ``✗`` line (to stderr).
+- The final summary is a cyan-bold ``Done. …`` line.
+"""
+
+from __future__ import annotations
+
+import click
+
+
+def echo_tree(name: str, children: list[str], *, warnings: list[str] | None = None) -> None:
+    """Print a ``┌─ name`` header with ``│``/``└─`` child lines.
+
+    ``warnings`` (if any) are rendered as yellow ``│`` continuation lines above
+    the children. ``children`` must be non-empty (a metric with no items should
+    use :func:`echo_noop` instead).
+    """
+    click.echo(click.style(f"  ┌─ {name}", fg="cyan", bold=True))
+    for warning in warnings or []:
+        click.echo(click.style(f"  │   ⚠ {warning}", fg="yellow", bold=True))
+    last = len(children) - 1
+    for i, child in enumerate(children):
+        prefix = "  └─ " if i == last else "  │   "
+        click.echo(f"{prefix}{child}")
+
+
+def echo_noop(name: str, reason: str) -> None:
+    """A metric with nothing to do — a single ``•`` line."""
+    click.echo(f"  • {name}: {reason}")
+
+
+def echo_error(name: str, message: str) -> None:
+    """A per-metric failure — a red ``✗`` line on stderr."""
+    click.echo(click.style(f"  ✗ {name}: {message}", fg="red"), err=True)
+
+
+def echo_done(summary: str) -> None:
+    """The closing ``Done. …`` summary (cyan, bold), preceded by a blank line."""
+    click.echo()
+    click.echo(click.style(f"Done. {summary}", fg="cyan", bold=True))

{detectkit-0.8.1 → detectkit-0.9.0}/detectkit/cli/commands/clean.py

@@ -27,6 +27,7 @@ from pathlib import Path
 
 import click
 
+from detectkit.cli._output import echo_done, echo_error, echo_noop, echo_tree
 from detectkit.cli.commands.run import find_project_root, select_metrics
 from detectkit.config.metric_config import MetricConfig
 from detectkit.config.profile import ProfilesConfig
@@ -112,6 +113,8 @@ def _clean_drift(
     total_det_groups = 0
     total_alert_rows = 0
 
+    verb = "deleting" if execute else "would delete"
+
     for _, config in metrics:
         metric_name = config.name
         try:
@@ -120,7 +123,7 @@ def _clean_drift(
             db_detectors = internal_manager.list_detector_ids(metric_name)
             db_alerts = internal_manager.list_alert_config_ids(metric_name)
         except Exception as e:
-            click.echo(click.style(f"  ✗ {metric_name}: error inspecting: {e}", fg="red"), err=True)
+            echo_error(metric_name, f"error inspecting: {e}")
             continue
 
         orphan_detectors = {
@@ -129,55 +132,42 @@ def _clean_drift(
         orphan_alerts = [a for a in db_alerts if a not in valid_alerts]
 
         if not orphan_detectors and not orphan_alerts:
-            click.echo(f"  • {metric_name}: nothing stale")
+            echo_noop(metric_name, "nothing stale")
             continue
 
-        click.echo(click.style(f"  {metric_name}:", bold=True))
+        children = [
+            f"detector {det_id}: {verb} {count:,} detection row(s)"
+            for det_id, count in sorted(orphan_detectors.items())
+        ] + [
+            f"alert_config {alert_id}: {verb} stale alert state"
+            for alert_id in sorted(orphan_alerts)
+        ]
 
         # An empty valid set means EVERY stored row is "orphaned" — usually a
         # config mid-edit, not an intent to wipe the metric. Flag it loudly.
+        warnings = []
         if orphan_detectors and not valid_detectors:
-            click.echo(
-                click.style(
-                    "    ⚠ config defines no detectors — ALL detections below would be removed",
-                    fg="yellow",
-                    bold=True,
-                )
-            )
+            warnings.append("config defines no detectors — ALL detections below would be removed")
         if orphan_alerts and not valid_alerts:
-            click.echo(
-                click.style(
-                    "    ⚠ config defines no alerting — ALL alert states below would be removed",
-                    fg="yellow",
-                    bold=True,
-                )
-            )
+            warnings.append("config defines no alerting — ALL alert states below would be removed")
+
+        echo_tree(metric_name, children, warnings=warnings)
 
-        for det_id, count in sorted(orphan_detectors.items()):
-            total_det_groups += 1
-            verb = "deleting" if execute else "would delete"
-            click.echo(f"    detector {det_id}: {verb} {count:,} detection row(s)")
-            if execute:
+        if execute:
+            for det_id in orphan_detectors:
                 internal_manager.delete_detections(
                     metric_name=metric_name, detector_id=det_id, mutations_sync=True
                 )
-
-        for alert_id in sorted(orphan_alerts):
-            total_alert_rows += 1
-            verb = "deleting" if execute else "would delete"
-            click.echo(f"    alert_config {alert_id}: {verb} stale alert state")
-            if execute:
+            for alert_id in orphan_alerts:
                 internal_manager.delete_alert_state(metric_name, alert_id)
 
-    click.echo()
-    prefix = "Deleted" if execute else "Would delete"
-    click.echo(
-        click.style(
-            f"{prefix} {total_det_groups} orphaned detector group(s) "
-            f"and {total_alert_rows} orphaned alert-state row(s).",
-            fg="cyan",
-            bold=True,
-        )
+        total_det_groups += len(orphan_detectors)
+        total_alert_rows += len(orphan_alerts)
+
+    verb_done = "Removed" if execute else "Would remove"
+    echo_done(
+        f"{verb_done} {total_det_groups} detector group(s) "
+        f"and {total_alert_rows} alert-state row(s)."
     )
     if not execute and (total_det_groups or total_alert_rows):
         click.echo("Re-run with --execute to apply.")
@@ -222,15 +212,10 @@ def _clean_orphaned_metrics(
         try:
             counts = internal_manager.count_metric_rows(name)
         except Exception as e:
-            click.echo(click.style(f"  ✗ {name}: error counting rows: {e}", fg="red"), err=True)
+            echo_error(name, f"error counting rows: {e}")
             continue
-        total = sum(counts.values())
-        verb = "deleting" if execute else "would delete"
-        detail = ", ".join(f"{table}={count:,}" for table, count in counts.items() if count)
-        click.echo(
-            click.style(f"  {name}: {verb} {total:,} row(s)", bold=True)
-            + (f"  [{detail}]" if detail else "")
-        )
+        children = [f"{table}: {count:,} row(s)" for table, count in counts.items() if count]
+        echo_tree(name, children or ["(no rows)"])
 
     if not execute:
         click.echo()
@@ -264,16 +249,10 @@ def _clean_orphaned_metrics(
         try:
             internal_manager.purge_metric(name)
             purged += 1
-            click.echo(click.style(f"  ✓ {name}: purged", fg="green"))
         except Exception as e:
-            click.echo(click.style(f"  ✗ {name}: error purging: {e}", fg="red"), err=True)
+            echo_error(name, f"error purging: {e}")
 
-    click.echo()
-    click.echo(
-        click.style(
-            f"Done. Purged {purged} of {len(orphans)} orphaned metric(s).", fg="cyan", bold=True
-        )
-    )
+    echo_done(f"Purged {purged} of {len(orphans)} orphaned metric(s).")
 
 
 # ── helpers ──────────────────────────────────────────────────────────────────

{detectkit-0.8.1 → detectkit-0.9.0}/detectkit/cli/commands/test_alert.py

@@ -44,6 +44,23 @@ def create_mock_alert_data(
     # different teams). Pull them from the specific config we're testing.
     mentions = list(alerting_config.mentions) if alerting_config else []
 
+    # Preview the alert with the rule it would actually fire on (min_detectors
+    # / direction / consecutive) so the test message matches the alert-centric
+    # default layout. Observed counts are set to satisfy the rule, as a real
+    # firing would.
+    min_detectors = getattr(alerting_config, "min_detectors", 1) or 1
+    direction_policy = getattr(alerting_config, "direction", "same") or "same"
+    consecutive_required = getattr(alerting_config, "consecutive_anomalies", 1) or 1
+    # Observed direction for the preview: a concrete side for up/down/same; for
+    # an "any" quorum of 2+ detectors show "mixed" (its whole point is that
+    # cross-direction anomalies combine), mirroring the real engine output.
+    if direction_policy in ("up", "down"):
+        observed_direction = direction_policy
+    elif direction_policy == "any" and min_detectors >= 2:
+        observed_direction = "mixed"
+    else:
+        observed_direction = "up"
+
     # Create realistic mock data
     return AlertData(
         metric_name=metric_config.name,
@@ -54,7 +71,7 @@ def create_mock_alert_data(
         confidence_upper=0.6234,
         detector_name="MADDetector:threshold=3.0",
         detector_params='{"threshold": 3.0, "window_size": 8640}',
-        direction="above",
+        direction=observed_direction,
         severity=4.52,
         detection_metadata={
             "global_median": 0.5123,
@@ -68,8 +85,12 @@ def create_mock_alert_data(
                 }
             ],
         },
-        consecutive_count=3,
+        consecutive_count=consecutive_required,
         mentions=mentions,
+        min_detectors=min_detectors,
+        direction_policy=direction_policy,
+        consecutive_required=consecutive_required,
+        detector_count=min_detectors,
     )
 
 

{detectkit-0.8.1 → detectkit-0.9.0}/detectkit/cli/commands/unlock.py

@@ -8,6 +8,7 @@ auto-expires after its timeout, but this command clears it immediately.
 
 import click
 
+from detectkit.cli._output import echo_done, echo_error, echo_noop, echo_tree
 from detectkit.cli.commands.run import find_project_root, select_metrics
 from detectkit.config.profile import ProfilesConfig
 from detectkit.database.internal_tables import InternalTablesManager
@@ -83,23 +84,13 @@ def run_unlock(select: str, profile: str | None):
         try:
             was_locked = internal_manager.clear_lock(metric_name)
         except Exception as e:
-            click.echo(
-                click.style(f"  ✗ {metric_name}: error clearing lock: {e}", fg="red"),
-                err=True,
-            )
+            echo_error(metric_name, f"error clearing lock: {e}")
             continue
 
         if was_locked:
             cleared += 1
-            click.echo(click.style(f"  ✓ {metric_name}: lock cleared", fg="green"))
+            echo_tree(metric_name, ["lock cleared"])
         else:
-            click.echo(f"  • {metric_name}: no active lock")
+            echo_noop(metric_name, "no active lock")
 
-    click.echo()
-    click.echo(
-        click.style(
-            f"Done. Cleared {cleared} lock(s) of {len(metrics)} metric(s).",
-            fg="cyan",
-            bold=True,
-        )
-    )
+    echo_done(f"Cleared {cleared} lock(s) of {len(metrics)} metric(s).")

{detectkit-0.8.1 → detectkit-0.9.0/detectkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.8.1
+Version: 0.9.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT

{detectkit-0.8.1 → detectkit-0.9.0}/detectkit.egg-info/SOURCES.txt

@@ -29,6 +29,7 @@ detectkit/alerting/orchestrator/_recovery.py
 detectkit/alerting/orchestrator/_types.py
 detectkit/alerting/orchestrator/orchestrator.py
 detectkit/cli/__init__.py
+detectkit/cli/_output.py
 detectkit/cli/main.py
 detectkit/cli/commands/__init__.py
 detectkit/cli/commands/clean.py