arthexis 0.1.9__py3-none-any.whl → 0.1.26__py3-none-any.whl

nodes/reports.py

@@ -0,0 +1,411 @@
+"""Utilities for generating Celery-focused admin reports."""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone as dt_timezone
+import numbers
+import re
+from pathlib import Path
+from typing import Iterable, Iterator
+
+from django.conf import settings
+from django.utils import timezone
+from django.utils.translation import gettext_lazy as _
+
+
+@dataclass(frozen=True)
+class ReportPeriod:
+    """Representation of an available reporting window."""
+
+    key: str
+    label: str
+    delta: timedelta
+
+
+REPORT_PERIOD_ORDER = ("1d", "7d", "30d")
+REPORT_PERIODS: dict[str, ReportPeriod] = {
+    "1d": ReportPeriod("1d", _("Single day"), timedelta(days=1)),
+    "7d": ReportPeriod("7d", _("Seven days"), timedelta(days=7)),
+    "30d": ReportPeriod("30d", _("Monthly"), timedelta(days=30)),
+}
+
+
+@dataclass(frozen=True)
+class ScheduledTaskSummary:
+    """Human-friendly representation of a Celery scheduled task."""
+
+    name: str
+    task: str
+    schedule_type: str
+    schedule_description: str
+    next_run: datetime | None
+    enabled: bool
+    source: str
+
+
+@dataclass(frozen=True)
+class CeleryLogEntry:
+    """A parsed log entry relevant to Celery activity."""
+
+    timestamp: datetime
+    level: str
+    logger: str
+    message: str
+    source: str
+
+
+@dataclass(frozen=True)
+class CeleryLogCollection:
+    """Container for log entries and the sources scanned."""
+
+    entries: list[CeleryLogEntry]
+    checked_sources: list[str]
+
+
+_LOG_LINE_PATTERN = re.compile(
+    r"^(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}(?:,\d{1,6})?) "
+    r"\[(?P<level>[A-Z]+)\] (?P<logger>[^:]+): (?P<message>.*)$"
+)
+
+
+def iter_report_periods() -> Iterator[ReportPeriod]:
+    """Yield configured reporting periods in display order."""
+
+    for key in REPORT_PERIOD_ORDER:
+        period = REPORT_PERIODS[key]
+        yield period
+
+
+def resolve_period(period_key: str | None) -> ReportPeriod:
+    """Return the requested reporting period or fall back to the default."""
+
+    if not period_key:
+        return REPORT_PERIODS[REPORT_PERIOD_ORDER[0]]
+    return REPORT_PERIODS.get(period_key, REPORT_PERIODS[REPORT_PERIOD_ORDER[0]])
+
+
+def collect_scheduled_tasks(now: datetime, window_end: datetime) -> list[ScheduledTaskSummary]:
+    """Return Celery tasks scheduled to run before ``window_end``.
+
+    Tasks with unknown scheduling information are included to avoid omitting
+    potentially important configuration.
+    """
+
+    summaries: list[ScheduledTaskSummary] = []
+    summaries.extend(_collect_db_tasks(now))
+    summaries.extend(_collect_settings_tasks(now))
+
+    filtered: list[ScheduledTaskSummary] = []
+    for summary in summaries:
+        if summary.next_run is None or summary.next_run <= window_end:
+            filtered.append(summary)
+
+    far_future = datetime.max.replace(tzinfo=dt_timezone.utc)
+    filtered.sort(
+        key=lambda item: (
+            item.next_run or far_future,
+            item.name.lower(),
+        )
+    )
+    return filtered
+
+
+def collect_celery_log_entries(
+    start: datetime, end: datetime, *, max_lines: int = 500
+) -> CeleryLogCollection:
+    """Return Celery-related log entries within ``start`` and ``end``."""
+
+    entries: list[CeleryLogEntry] = []
+    checked_sources: list[str] = []
+
+    for path in _candidate_log_files():
+        checked_sources.append(path.name)
+        for entry in _read_log_entries(path, max_lines=max_lines):
+            if entry.timestamp < start or entry.timestamp > end:
+                continue
+            entries.append(entry)
+
+    entries.sort(key=lambda item: item.timestamp, reverse=True)
+    return CeleryLogCollection(entries=entries, checked_sources=checked_sources)
+
+
+def _collect_db_tasks(now: datetime) -> list[ScheduledTaskSummary]:
+    try:  # pragma: no cover - optional dependency guard
+        from django_celery_beat.models import PeriodicTask
+    except Exception:
+        return []
+
+    try:
+        tasks = list(
+            PeriodicTask.objects.select_related(
+                "interval", "crontab", "solar", "clocked"
+            )
+        )
+    except Exception:  # pragma: no cover - database unavailable
+        return []
+
+    summaries: list[ScheduledTaskSummary] = []
+    for task in tasks:
+        schedule = getattr(task, "schedule", None)
+        next_run = _estimate_next_run(now, schedule, task.last_run_at, task.start_time)
+        schedule_type = _determine_schedule_type(task)
+        schedule_description = _describe_db_schedule(task)
+        summaries.append(
+            ScheduledTaskSummary(
+                name=task.name,
+                task=task.task,
+                schedule_type=schedule_type,
+                schedule_description=schedule_description,
+                next_run=next_run,
+                enabled=bool(task.enabled),
+                source=str(_("Database")),
+            )
+        )
+    return summaries
+
+
+def _collect_settings_tasks(now: datetime) -> list[ScheduledTaskSummary]:
+    schedule_config = getattr(settings, "CELERY_BEAT_SCHEDULE", {})
+    summaries: list[ScheduledTaskSummary] = []
+
+    for name, config in schedule_config.items():
+        task_name = str(config.get("task", ""))
+        schedule = config.get("schedule")
+        next_run = _estimate_next_run(now, schedule, None, None)
+        schedule_type = _describe_schedule_type(schedule)
+        schedule_description = _describe_settings_schedule(schedule)
+        summaries.append(
+            ScheduledTaskSummary(
+                name=name,
+                task=task_name,
+                schedule_type=schedule_type,
+                schedule_description=schedule_description,
+                next_run=next_run,
+                enabled=True,
+                source=str(_("Settings")),
+            )
+        )
+
+    return summaries
+
+
+def _determine_schedule_type(task) -> str:
+    if getattr(task, "clocked_id", None):
+        return "clocked"
+    if getattr(task, "solar_id", None):
+        return "solar"
+    if getattr(task, "crontab_id", None):
+        return "crontab"
+    if getattr(task, "interval_id", None):
+        return "interval"
+    return "unknown"
+
+
+def _estimate_next_run(
+    now: datetime,
+    schedule,
+    last_run_at: datetime | None,
+    start_time: datetime | None,
+) -> datetime | None:
+    if schedule is None:
+        return None
+
+    if isinstance(schedule, timedelta):
+        return now + schedule
+
+    if isinstance(schedule, numbers.Real):
+        return now + timedelta(seconds=float(schedule))
+
+    if isinstance(schedule, datetime):
+        candidate = _make_aware(schedule)
+        if candidate and candidate >= now:
+            return candidate
+        return candidate
+
+    schedule_now = _schedule_now(schedule, now)
+    candidate_start = _coerce_with_schedule(schedule, start_time)
+    if candidate_start and candidate_start > schedule_now:
+        return candidate_start
+
+    reference = _coerce_with_schedule(schedule, last_run_at) or schedule_now
+
+    try:
+        remaining = schedule.remaining_estimate(reference)
+        if remaining is None:
+            return None
+        return schedule_now + remaining
+    except Exception:
+        try:
+            due, next_time_to_run = schedule.is_due(reference)
+        except Exception:
+            return None
+        if due:
+            return schedule_now
+        try:
+            seconds = float(next_time_to_run)
+        except (TypeError, ValueError):
+            return None
+        return schedule_now + timedelta(seconds=seconds)
+
+
+def _schedule_now(schedule, fallback: datetime) -> datetime:
+    if hasattr(schedule, "now") and hasattr(schedule, "maybe_make_aware"):
+        try:
+            current = schedule.maybe_make_aware(schedule.now())
+            if isinstance(current, datetime):
+                return current
+        except Exception:
+            pass
+    return fallback
+
+
+def _coerce_with_schedule(schedule, value: datetime | None) -> datetime | None:
+    if value is None:
+        return None
+    if hasattr(schedule, "maybe_make_aware"):
+        try:
+            coerced = schedule.maybe_make_aware(value)
+            if isinstance(coerced, datetime):
+                return coerced
+        except Exception:
+            pass
+    return _make_aware(value)
+
+
+def _make_aware(value: datetime) -> datetime:
+    if timezone.is_naive(value):
+        try:
+            return timezone.make_aware(value)
+        except Exception:
+            return value
+    return value
+
+
+def _describe_db_schedule(task) -> str:
+    schedule = getattr(task, "schedule", None)
+    if schedule is None:
+        return ""
+
+    try:
+        human_readable = getattr(schedule, "human_readable", None)
+        if callable(human_readable):
+            return str(human_readable())
+        if isinstance(human_readable, str):
+            return human_readable
+    except Exception:
+        pass
+
+    for attr in ("clocked", "solar", "crontab", "interval"):
+        obj = getattr(task, attr, None)
+        if obj is not None:
+            return str(obj)
+    return str(schedule)
+
+
+def _describe_schedule_type(schedule) -> str:
+    type_name = type(schedule).__name__ if schedule is not None else "unknown"
+    return type_name.replace("Schedule", "").lower()
+
+
+def _describe_settings_schedule(schedule) -> str:
+    if schedule is None:
+        return ""
+
+    try:
+        human_readable = getattr(schedule, "human_readable", None)
+        if callable(human_readable):
+            return str(human_readable())
+        if isinstance(human_readable, str):
+            return human_readable
+    except Exception:
+        pass
+
+    if isinstance(schedule, timedelta):
+        return str(schedule)
+    if isinstance(schedule, numbers.Real):
+        return _("Every %(seconds)s seconds") % {"seconds": schedule}
+    return str(schedule)
+
+
+def _candidate_log_files() -> Iterable[Path]:
+    log_dir = Path(settings.LOG_DIR)
+    candidates = [
+        log_dir / "celery.log",
+        log_dir / "celery-worker.log",
+        log_dir / "celery-beat.log",
+        log_dir / getattr(settings, "LOG_FILE_NAME", ""),
+    ]
+
+    seen: set[Path] = set()
+    for path in candidates:
+        if not path:
+            continue
+        if path in seen:
+            continue
+        seen.add(path)
+        if path.exists():
+            yield path
+
+
+def _read_log_entries(path: Path, *, max_lines: int) -> Iterator[CeleryLogEntry]:
+    try:
+        with path.open("r", encoding="utf-8", errors="ignore") as handle:
+            lines = deque(handle, maxlen=max_lines)
+    except OSError:  # pragma: no cover - filesystem errors
+        return iter(())
+
+    return (
+        entry
+        for entry in (_parse_log_line(line, path.name) for line in lines)
+        if entry is not None
+    )
+
+
+def _parse_log_line(line: str, source: str) -> CeleryLogEntry | None:
+    match = _LOG_LINE_PATTERN.match(line)
+    if not match:
+        return None
+
+    timestamp = _parse_timestamp(match.group("timestamp"))
+    if timestamp is None:
+        return None
+
+    logger_name = match.group("logger").strip()
+    message = match.group("message").strip()
+    level = match.group("level").strip()
+
+    if not _is_celery_related(logger_name, message):
+        return None
+
+    return CeleryLogEntry(
+        timestamp=timestamp,
+        level=level,
+        logger=logger_name,
+        message=message,
+        source=source,
+    )
+
+
+def _parse_timestamp(value: str) -> datetime | None:
+    for fmt in ("%Y-%m-%d %H:%M:%S,%f", "%Y-%m-%d %H:%M:%S"):
+        try:
+            dt = datetime.strptime(value, fmt)
+            return _make_aware(dt)
+        except ValueError:
+            continue
+    try:
+        dt = datetime.fromisoformat(value)
+    except ValueError:
+        return None
+    return _make_aware(dt)
+
+
+def _is_celery_related(logger_name: str, message: str) -> bool:
+    logger_lower = logger_name.lower()
+    message_lower = message.lower()
+    if any(keyword in logger_lower for keyword in ("celery", "task", "beat")):
+        return True
+    return "celery" in message_lower or "task" in message_lower
+

nodes/rfid_sync.py

@@ -0,0 +1,210 @@
+"""Helper utilities for synchronizing RFID records between nodes."""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, TYPE_CHECKING
+
+from django.utils.dateparse import parse_datetime
+
+from core.models import EnergyAccount, RFID
+
+if TYPE_CHECKING:  # pragma: no cover - imported only for type checking
+    from nodes.models import Node
+
+
+@dataclass(slots=True)
+class RFIDSyncOutcome:
+    """Result of applying an RFID payload to the local database."""
+
+    instance: RFID | None = None
+    created: bool = False
+    updated: bool = False
+    accounts_linked: int = 0
+    missing_accounts: list[str] = field(default_factory=list)
+    account_data_provided: bool = False
+    ok: bool = False
+    error: str | None = None
+
+
+def serialize_rfid(tag: RFID) -> dict[str, Any]:
+    """Return a dictionary representation suitable for the node API."""
+
+    accounts = list(tag.energy_accounts.all())
+    return {
+        "rfid": tag.rfid,
+        "custom_label": tag.custom_label,
+        "key_a": tag.key_a,
+        "key_b": tag.key_b,
+        "data": tag.data,
+        "key_a_verified": tag.key_a_verified,
+        "key_b_verified": tag.key_b_verified,
+        "allowed": tag.allowed,
+        "color": tag.color,
+        "kind": tag.kind,
+        "released": tag.released,
+        "external_command": tag.external_command,
+        "post_auth_command": tag.post_auth_command,
+        "last_seen_on": tag.last_seen_on.isoformat() if tag.last_seen_on else None,
+        "energy_accounts": [account.id for account in accounts],
+        "energy_account_names": [
+            account.name for account in accounts if account.name
+        ],
+    }
+
+
+def apply_rfid_payload(
+    entry: Mapping[str, Any], *, origin_node: Node | None = None
+) -> RFIDSyncOutcome:
+    """Create or update an :class:`RFID` instance from API payload data."""
+
+    outcome = RFIDSyncOutcome()
+    rfid_value = str(entry.get("rfid") or "").strip()
+    if not rfid_value:
+        outcome.error = "Missing RFID value"
+        return outcome
+
+    external_command = entry.get("external_command")
+    if not isinstance(external_command, str):
+        external_command = ""
+    else:
+        external_command = external_command.strip()
+    post_auth_command = entry.get("post_auth_command")
+    if not isinstance(post_auth_command, str):
+        post_auth_command = ""
+    else:
+        post_auth_command = post_auth_command.strip()
+
+    defaults: dict[str, Any] = {
+        "custom_label": entry.get("custom_label", ""),
+        "key_a": entry.get("key_a", RFID._meta.get_field("key_a").default),
+        "key_b": entry.get("key_b", RFID._meta.get_field("key_b").default),
+        "data": entry.get("data", []) or [],
+        "key_a_verified": bool(entry.get("key_a_verified", False)),
+        "key_b_verified": bool(entry.get("key_b_verified", False)),
+        "allowed": bool(entry.get("allowed", True)),
+        "color": entry.get("color", RFID.BLACK),
+        "kind": entry.get("kind", RFID.CLASSIC),
+        "released": bool(entry.get("released", False)),
+        "external_command": external_command,
+        "post_auth_command": post_auth_command,
+    }
+
+    if origin_node is not None:
+        defaults["origin_node"] = origin_node
+
+    if "last_seen_on" in entry:
+        last_seen = entry.get("last_seen_on")
+        defaults["last_seen_on"] = parse_datetime(last_seen) if last_seen else None
+
+    obj, created = RFID.update_or_create_from_code(rfid_value, defaults=defaults)
+
+    outcome.instance = obj
+    outcome.created = created
+    outcome.updated = not created
+    outcome.ok = True
+
+    accounts, missing, provided = _resolve_accounts(entry)
+    outcome.account_data_provided = provided
+    if provided:
+        obj.energy_accounts.set(accounts)
+        outcome.accounts_linked = len(accounts)
+    else:
+        outcome.accounts_linked = 0
+    outcome.missing_accounts = missing
+
+    return outcome
+
+
+def _resolve_accounts(
+    entry: Mapping[str, Any]
+) -> tuple[list[EnergyAccount], list[str], bool]:
+    """Return matching accounts and missing identifiers from payload data."""
+
+    has_account_data = "energy_accounts" in entry or "energy_account_names" in entry
+    if not has_account_data:
+        return [], [], False
+
+    accounts: list[EnergyAccount] = []
+    missing: list[str] = []
+    seen_ids: set[int] = set()
+    matched_names: "OrderedDict[str, None]" = OrderedDict()
+
+    # Resolve by numeric identifiers first to preserve ordering.
+    id_values = _coerce_values(entry.get("energy_accounts"))
+    parsed_ids: list[tuple[str, int]] = []
+    invalid_ids: list[str] = []
+    for raw in id_values:
+        try:
+            parsed_ids.append((raw, int(raw)))
+        except (TypeError, ValueError):
+            invalid_ids.append(raw)
+
+    existing_by_id = (
+        EnergyAccount.objects.in_bulk([pk for _, pk in parsed_ids])
+        if parsed_ids
+        else {}
+    )
+
+    for raw, pk in parsed_ids:
+        account = existing_by_id.get(pk)
+        if account and account.id not in seen_ids:
+            accounts.append(account)
+            seen_ids.add(account.id)
+            if account.name:
+                matched_names[account.name.strip().upper()] = None
+        else:
+            missing.append(raw)
+
+    missing.extend(invalid_ids)
+
+    # Resolve remaining accounts by name.
+    name_values = _coerce_values(entry.get("energy_account_names"))
+    processed_names: "OrderedDict[str, None]" = OrderedDict()
+    for raw in name_values:
+        normalized = raw.strip().upper()
+        if not normalized or normalized in processed_names:
+            continue
+        processed_names[normalized] = None
+        if normalized in matched_names:
+            continue
+        account = (
+            EnergyAccount.objects.filter(name__iexact=raw.strip())
+            .order_by("pk")
+            .first()
+        )
+        if account and account.id not in seen_ids:
+            accounts.append(account)
+            seen_ids.add(account.id)
+            if account.name:
+                matched_names[account.name.strip().upper()] = None
+        else:
+            missing.append(raw)
+
+    # Deduplicate missing entries while preserving order.
+    missing_unique = list(OrderedDict.fromkeys(raw for raw in missing if raw))
+
+    return accounts, missing_unique, True
+
+
+def _coerce_values(values: Any) -> list[str]:
+    """Return a list of trimmed string values from the payload field."""
+
+    if values is None:
+        return []
+    if isinstance(values, str):
+        values = values.split(",")
+    if isinstance(values, Mapping):
+        values = list(values.values())
+    if not isinstance(values, Iterable) or isinstance(values, (bytes, bytearray)):
+        return []
+
+    result: list[str] = []
+    for value in values:
+        text = str(value or "").strip()
+        if text:
+            result.append(text)
+    return result
+

nodes/signals.py

@@ -0,0 +1,18 @@
+"""Signal handlers for the :mod:`nodes` application."""
+
+from __future__ import annotations
+
+from django.db.models.signals import post_save
+from django.dispatch import receiver
+
+from .classifiers import run_default_classifiers, should_skip_default_classifiers
+from .models import ContentSample
+
+
+@receiver(post_save, sender=ContentSample)
+def run_classifiers_on_sample_creation(sender, instance: ContentSample, created: bool, **_: object):
+    """Execute default classifiers whenever a new sample is stored."""
+
+    if not created or should_skip_default_classifiers():
+        return
+    run_default_classifiers(instance)