From 2c27202475e8e69b40c2416e0b20647edd8392b8 Mon Sep 17 00:00:00 2001 From: Bryan Deng Date: Sun, 5 Jul 2026 19:19:13 -0400 Subject: [PATCH] docs: add missing module-level docstrings add a short module docstring to the modules that had none (main.py, api/routes, db, utils, calendars, and the undocumented service/runtime modules) so per-module purpose lives in the code itself, complementing the co-located AGENTS.md files. no behavior change. Co-Authored-By: Claude Opus 4.8 --- builders/server/core/api/routes.py | 2 ++ builders/server/core/calendars/definitions/always_open.py | 2 ++ builders/server/core/calendars/definitions/everyday.py | 2 ++ builders/server/core/calendars/definitions/nyse_daily.py | 2 ++ builders/server/core/calendars/definitions/weekday.py | 2 ++ builders/server/core/calendars/interface.py | 2 ++ builders/server/core/calendars/registry.py | 2 ++ builders/server/core/calendars/utils.py | 2 ++ builders/server/core/db/connection.py | 2 ++ builders/server/core/db/datasets.py | 2 ++ builders/server/core/runtime/config.py | 2 ++ builders/server/core/runtime/loader.py | 2 ++ builders/server/core/runtime/registry.py | 2 ++ builders/server/core/runtime/runner.py | 2 ++ builders/server/core/runtime/validator.py | 2 ++ builders/server/core/service/builder.py | 2 ++ builders/server/core/service/catalog.py | 2 ++ builders/server/core/service/locks.py | 2 ++ builders/server/core/service/models.py | 2 ++ builders/server/core/utils/retry.py | 2 ++ builders/server/core/utils/semver.py | 2 ++ builders/server/main.py | 2 ++ 22 files changed, 44 insertions(+) diff --git a/builders/server/core/api/routes.py b/builders/server/core/api/routes.py index 2e77e534..a14e4a08 100644 --- a/builders/server/core/api/routes.py +++ b/builders/server/core/api/routes.py @@ -1,3 +1,5 @@ +"""HTTP endpoint handlers for the public and authenticated routers.""" + from datetime import datetime import structlog diff --git a/builders/server/core/calendars/definitions/always_open.py b/builders/server/core/calendars/definitions/always_open.py index 803e216f..3bd61385 100644 --- a/builders/server/core/calendars/definitions/always_open.py +++ b/builders/server/core/calendars/definitions/always_open.py @@ -1,3 +1,5 @@ +"""AlwaysOpenCalendar: accepts any timestamp regardless of date or time.""" + from datetime import datetime, timedelta from core.calendars.interface import Calendar diff --git a/builders/server/core/calendars/definitions/everyday.py b/builders/server/core/calendars/definitions/everyday.py index d6c4260a..14ce6359 100644 --- a/builders/server/core/calendars/definitions/everyday.py +++ b/builders/server/core/calendars/definitions/everyday.py @@ -1,3 +1,5 @@ +"""EverydayCalendar ('everyday'): accepts every day; the default calendar.""" + from datetime import datetime, timedelta from core.calendars.interface import Calendar diff --git a/builders/server/core/calendars/definitions/nyse_daily.py b/builders/server/core/calendars/definitions/nyse_daily.py index 13e5326a..af5e0939 100644 --- a/builders/server/core/calendars/definitions/nyse_daily.py +++ b/builders/server/core/calendars/definitions/nyse_daily.py @@ -1,3 +1,5 @@ +"""NyseDailyCalendar: registered as 'nyse-daily', accepts NYSE trading days only.""" + from datetime import datetime, timedelta import exchange_calendars as xcals diff --git a/builders/server/core/calendars/definitions/weekday.py b/builders/server/core/calendars/definitions/weekday.py index c1397767..bc2db008 100644 --- a/builders/server/core/calendars/definitions/weekday.py +++ b/builders/server/core/calendars/definitions/weekday.py @@ -1,3 +1,5 @@ +"""WeekdayCalendar: registered as 'weekday', accepts Monday through Friday only.""" + from datetime import datetime, timedelta from core.calendars.interface import Calendar diff --git a/builders/server/core/calendars/interface.py b/builders/server/core/calendars/interface.py index 593bf182..2551ccac 100644 --- a/builders/server/core/calendars/interface.py +++ b/builders/server/core/calendars/interface.py @@ -1,3 +1,5 @@ +"""The Calendar ABC defining which timestamps are valid for a dataset.""" + from abc import ABC, abstractmethod from datetime import datetime, timedelta diff --git a/builders/server/core/calendars/registry.py b/builders/server/core/calendars/registry.py index 48d8f4c5..71e7d544 100644 --- a/builders/server/core/calendars/registry.py +++ b/builders/server/core/calendars/registry.py @@ -1,3 +1,5 @@ +"""CALENDARS_MAP: registry mapping calendar name to Calendar instance.""" + from core.calendars.definitions.always_open import AlwaysOpenCalendar from core.calendars.definitions.everyday import EverydayCalendar from core.calendars.definitions.nyse_daily import NyseDailyCalendar diff --git a/builders/server/core/calendars/utils.py b/builders/server/core/calendars/utils.py index 5b3f6178..4dc71eb3 100644 --- a/builders/server/core/calendars/utils.py +++ b/builders/server/core/calendars/utils.py @@ -1,3 +1,5 @@ +"""Shared helpers for calendar implementations.""" + from datetime import datetime diff --git a/builders/server/core/db/connection.py b/builders/server/core/db/connection.py index 2e9e3a5c..60875c07 100644 --- a/builders/server/core/db/connection.py +++ b/builders/server/core/db/connection.py @@ -1,3 +1,5 @@ +"""Postgres connection pool lifecycle and per-request connection access.""" + import structlog from psycopg_pool import ConnectionPool diff --git a/builders/server/core/db/datasets.py b/builders/server/core/db/datasets.py index 16c25929..df22610b 100644 --- a/builders/server/core/db/datasets.py +++ b/builders/server/core/db/datasets.py @@ -1,3 +1,5 @@ +"""SQL queries for the datasets table: existence, reads, and bulk insert.""" + from collections import defaultdict from datetime import datetime diff --git a/builders/server/core/runtime/config.py b/builders/server/core/runtime/config.py index 60a51781..a2564d4e 100644 --- a/builders/server/core/runtime/config.py +++ b/builders/server/core/runtime/config.py @@ -1,3 +1,5 @@ +"""Parses and validates config.toml into DatasetConfig; owns SCRIPTS_DIR resolution.""" + import os import re from dataclasses import dataclass diff --git a/builders/server/core/runtime/loader.py b/builders/server/core/runtime/loader.py index f3c7faa3..af2fd9c9 100644 --- a/builders/server/core/runtime/loader.py +++ b/builders/server/core/runtime/loader.py @@ -1,3 +1,5 @@ +"""Dynamically imports a builder module from its script directory.""" + import importlib.util import sys from collections.abc import Callable diff --git a/builders/server/core/runtime/registry.py b/builders/server/core/runtime/registry.py index 08b32a48..23ccfe1b 100644 --- a/builders/server/core/runtime/registry.py +++ b/builders/server/core/runtime/registry.py @@ -1,3 +1,5 @@ +"""Startup config preload + in-memory registry; validates the dependency graph.""" + import tomllib from collections.abc import Generator from pathlib import Path diff --git a/builders/server/core/runtime/runner.py b/builders/server/core/runtime/runner.py index c6104966..f240b614 100644 --- a/builders/server/core/runtime/runner.py +++ b/builders/server/core/runtime/runner.py @@ -1,3 +1,5 @@ +"""Runs a builder in an isolated subprocess with retry, using its venv if present.""" + import subprocess import sys import time diff --git a/builders/server/core/runtime/validator.py b/builders/server/core/runtime/validator.py index cb1fc8f9..8569a181 100644 --- a/builders/server/core/runtime/validator.py +++ b/builders/server/core/runtime/validator.py @@ -1,3 +1,5 @@ +"""Validates builder output rows against the dataset's [schema] declaration.""" + from core.runtime.config import SchemaType diff --git a/builders/server/core/service/builder.py b/builders/server/core/service/builder.py index dbcd3462..a735cc8b 100644 --- a/builders/server/core/service/builder.py +++ b/builders/server/core/service/builder.py @@ -1,3 +1,5 @@ +"""Public build API: build_dataset() and get_data(); selects the store.""" + from dataclasses import dataclass from datetime import datetime diff --git a/builders/server/core/service/catalog.py b/builders/server/core/service/catalog.py index 9e97a1de..cf5b36c3 100644 --- a/builders/server/core/service/catalog.py +++ b/builders/server/core/service/catalog.py @@ -1,3 +1,5 @@ +"""list_datasets(): registered datasets annotated with DB data presence.""" + from dataclasses import dataclass import core.db.datasets diff --git a/builders/server/core/service/locks.py b/builders/server/core/service/locks.py index e1352ef1..3d27232c 100644 --- a/builders/server/core/service/locks.py +++ b/builders/server/core/service/locks.py @@ -1,3 +1,5 @@ +"""Per-dataset build lock registry serializing concurrent builds of the same dataset.""" + import threading _lock_map: dict[tuple[str, str], threading.Lock] = {} diff --git a/builders/server/core/service/models.py b/builders/server/core/service/models.py index 1f84e2b6..32feefc7 100644 --- a/builders/server/core/service/models.py +++ b/builders/server/core/service/models.py @@ -1,3 +1,5 @@ +"""Build data types: JobDescriptor, JobResult, and BuildPlan.""" + from dataclasses import dataclass from datetime import datetime diff --git a/builders/server/core/utils/retry.py b/builders/server/core/utils/retry.py index 9b5ea603..f5ba3ea7 100644 --- a/builders/server/core/utils/retry.py +++ b/builders/server/core/utils/retry.py @@ -1,3 +1,5 @@ +"""Generic retry-with-exponential-backoff helper used to wrap flaky operations.""" + import time from collections.abc import Callable diff --git a/builders/server/core/utils/semver.py b/builders/server/core/utils/semver.py index 8eb1e18a..642eb8ea 100644 --- a/builders/server/core/utils/semver.py +++ b/builders/server/core/utils/semver.py @@ -1,3 +1,5 @@ +"""SemVer parsing and comparison (strict major.minor.patch, no leading zeros).""" + import re from dataclasses import dataclass diff --git a/builders/server/main.py b/builders/server/main.py index 4834f7ed..ed9e2533 100644 --- a/builders/server/main.py +++ b/builders/server/main.py @@ -1,3 +1,5 @@ +"""FastAPI entrypoint: builds the app, mounts routers, runs the lifespan.""" + import os import uuid from collections.abc import AsyncIterator