action0-celery-sched 0.1.0__tar.gz

action0_celery_sched-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,99 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# cancel superseded runs of the same branch / PR
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    name: checks (python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    continue-on-error: ${{ matrix.experimental }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+        experimental: [false]
+        include:
+          # 3.15 is still a pre-release: run it, but don't fail the whole
+          # workflow while parts of the toolchain don't support it yet
+          - python-version: "3.15"
+            experimental: true
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: ruff format
+        run: uv run ruff format --check
+
+      - name: ruff check
+        run: uv run ruff check
+
+      - name: mypy
+        run: uv run mypy
+
+      - name: pyright
+        run: uv run pyright
+
+      - name: ty
+        run: uv run ty check
+
+      - name: pytest
+        run: uv run pytest
+
+  docs:
+    name: docs build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+
+      - name: Install dependencies
+        run: uv sync --locked --group docs
+
+      - name: Build documentation (warnings are errors)
+        run: uv run --group docs sphinx-build -W --keep-going -b html docs docs/_build/html
+
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/_build/html
+
+  deploy-docs:
+    name: deploy docs
+    # publish only what landed on main
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: docs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    # the Pages site itself was enabled once via
+    # `gh api repos/<owner>/<repo>/pages -X POST -f build_type=workflow`;
+    # creating it from a workflow is impossible (GITHUB_TOKEN cannot get
+    # repo-administration rights)
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

action0_celery_sched-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,62 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    name: check and build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Run all checks
+        run: |
+          uv run ruff format --check
+          uv run ruff check
+          uv run mypy
+          uv run pyright
+          uv run ty check
+          uv run pytest
+
+      - name: Check that the tag matches __version__
+        run: |
+          version=$(uv run python -c "from action0.celery_sched import __version__; print(__version__)")
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "tag $GITHUB_REF_NAME does not match __version__ $version" >&2
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/action0-celery-sched
+    permissions:
+      # OIDC token for PyPI trusted publishing
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

action0_celery_sched-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Editor files
+.idea
+
+# Claude Code local state
+.claude/settings.local.json
+.claude/worktrees/
+
+# Sphinx build output
+docs/_build/

action0_celery_sched-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

action0_celery_sched-0.1.0/CLAUDE.md

@@ -0,0 +1,83 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+`action0-celery-sched` is a Python library that reads Celery beat schedules from YAML or TOML files (or already-parsed mappings) and turns them into the value of Celery's `beat_schedule` setting (`app.conf.beat_schedule = load_beat_schedule("beat.yaml")`). It ships the `action0.celery_sched` package (`action0` is a PEP 420 namespace package) from a `src/` layout, is built with hatchling, and uses `uv` for environment/dependency management. The only runtime dependency is `celery`: TOML uses the stdlib `tomllib`, YAML needs the optional `yaml` extra (PyYAML), and the optional `solar` extra adds `ephem`, which Celery needs to build `solar` schedules. Importing the package must never import PyYAML — `test_without_pyyaml.py` guards that.
+
+## Rules
+
+- **Never commit without asking.** Also never push, tag, or publish on your own.
+- **Branches + PRs.** All changes go through feature branches and GitHub pull requests that Simon reviews and merges — never commit to `main` directly. (Only the initial implementation is built directly on `main`; once that phase is over, this applies without exception.)
+- **Discuss first.** Always present the plan and the intended edits and get agreement before changing files.
+- Every code change comes with: tests, docstrings, inline comments where the code isn't self-explanatory, and updated usage examples in `README.md` and the Sphinx docs (`docs/usage.md`).
+- Before considering work done, run ruff, mypy, pyright, ty and pytest (commands below) and fix what they report.
+- Supported Python versions: 3.11 up to the latest release. Don't use syntax or stdlib features introduced after 3.11 (no PEP 695 `type` aliases or generics — use `TypeAlias`), and don't rely on behavior removed in newer versions.
+- Prefer many small modules and short functions over large ones.
+
+## Commands
+
+`uv run` syncs the environment automatically (the dev dependency group is installed by default), so no separate install step is needed.
+
+```sh
+uv run pytest                                               # all tests
+uv run pytest tests/action0/celery_sched/test_loader.py  # one file
+uv run pytest tests/action0/celery_sched/test_loader.py::MergeTestCase::test_replace  # one test
+
+uv run ruff check      # lint (add --fix to autofix)
+uv run ruff format     # format
+uv run mypy            # type-check (strict; files are configured in pyproject.toml)
+uv run pyright         # type-check
+uv run ty check        # type-check
+
+uv run --group docs sphinx-build -W --keep-going -b html docs docs/_build/html  # build docs
+
+uv build               # build sdist + wheel into dist/
+```
+
+`pytest` also runs the `>>>` examples in the docstrings as doctests (`--doctest-modules` over `src/`), so docstring examples must produce their shown output exactly.
+
+## Architecture
+
+The file format is the same in YAML and TOML — Simon's requirement: an entry is identical regardless of format. A top-level mapping of entry name → entry; entry keys `task` (required), `schedule` (required), `params` (positional args), `kw` (keyword args), `options` (passed to `apply_async`), `enabled`. The `schedule` has exactly one of `every` / `crontab` / `solar` (plus `relative`, only next to `every`). The names `kw`/`params` are the user-facing names chosen by Simon; they map to Celery's `kwargs`/`args`.
+
+Data flow: source (path / stream / mapping) → `sources.read_source` → `formats.detect_format` + `formats.parse_text` → `yaml_loader.load_yaml` or `toml_loader.load_toml` → plain Python data → `loader._parse_document` → `entries.parse_entry` (and below it the format-agnostic parsers) → `Entry` → `to_celery()`. Everything from `_parse_document` down never knows which format the data came from; keep it that way.
+
+Modules under `src/action0/celery_sched/`, one concern each, from the leaves up:
+
+- `errors.py` — `ScheduleError` base; `DefinitionError` carries `reason` plus a location (`source` file, `entry` name, key `path`) rendered as `beat.yaml: entry 'X': schedule.crontab.hour: reason`; `DuplicateEntryError`; `UnknownTaskError` (with `missing`). `located(*keys, entry=, source=)` is the context manager that fills the location in on the way up — parsers only ever raise with a reason and wrap each descent in `with located("key"):`.
+- `values.py` — shared validators: `expect_mapping`, `check_keys` (unknown keys are errors — the typo guard), `as_number`, `as_bool`, `describe`. Number/boolean validators accept string spellings because `!ENV` always yields strings.
+- `durations.py` — `parse_duration`: seconds (number or numeric string), duration strings (`1h30m`, units `w d h m s ms`, lowercase only), or a `timedelta`-kwargs mapping; must be positive and finite.
+- `crontabs.py` — `parse_crontab`: five-field cron string (cron order; own whitespace split because Celery's `crontab.from_string` splits on single spaces only), `@daily`-style nicknames, or a mapping of Celery's field names. Each field is validated by constructing a one-field `crontab` so the error is pinned to its key.
+- `solar.py` — `SolarEvent` (StrEnum of Celery's events) and `parse_solar`; range checks happen before construction, and a missing `ephem` becomes an `ImportError` naming the `solar` extra.
+- `schedules.py` — `parse_schedule` dispatches on the one kind key. Intervals become `celery.schedules.schedule(timedelta, relative=...)` objects, so every kind comes out as a `BaseSchedule` that beat takes as-is.
+- `entries.py` — `Entry` (frozen dataclass; `source` excluded from equality), `BeatEntry` (TypedDict of one `beat_schedule` value), `parse_entry`. Argument containers are deep-copied so YAML-anchor-shared mappings are never shared at runtime.
+- `envvars.py` — `substitute_env` for `${VAR}` / `${VAR:-fallback}`; textual, never re-parsed (same semantics as action0-service's `!ENV`).
+- `yaml_loader.py` — `load_yaml` (wraps `yaml.YAMLError` into `DefinitionError`) and `ScheduleLoader`, a `SafeLoader` with the `!ENV` tag (unset variables are reported with their line — entry/key aren't known while parsing) and duplicate-key detection. Duplicates are checked in `flatten_mapping` (the one hook that sees a mapping's own pairs before merge keys are spliced in), once per node — a node can be flattened again as a merge source after it was rewritten, which would otherwise produce false duplicates (there are tests for exactly that). A duplicate at the root is a `DuplicateEntryError`.
+- `toml_loader.py` — `load_toml`: `tomllib.loads` (syntax errors, which include TOML's own duplicate-key errors, become `DefinitionError`), then a walk substituting strings that start with `!ENV` + whitespace — TOML has no tags, so the tag is spelled as a string prefix (precedent: dynaconf's `"@int ..."`). The walk runs under `located()`, so unset variables report entry and key path. Keys are never substituted.
+- `formats.py` — `Format` (StrEnum YAML/TOML), `FormatLike` (`Format | Literal[...]`, like action0-pipeline's `ErrorPolicyLike`), `SUFFIXES`, `detect_format` (explicit `format` wins, else suffix — case-insensitive `.yaml`/`.yml`/`.toml`; anything else raises `ValueError`, deliberately no default), `parser_for` (imports `yaml_loader` lazily; an `ImportError` whose `name` is `"yaml"` becomes one naming the `yaml` extra, any other `ImportError` propagates untouched) and `parse_text` (dispatch through `parser_for`). Nothing may import `yaml_loader` at module level.
+- `sources.py` — `Source` (path | `IO[str]` | `IO[bytes]` | `Mapping`) and `read_source`: mappings pass through unnamed (no `!ENV`, no format); paths and streams get their format detected and their parser obtained *before* any I/O (so an unknown format or a missing PyYAML fails without touching the file), binary streams are decoded as UTF-8 (tomllib users open files `"rb"`).
+- `loader.py` — `load_entries(*sources, replace=False, format=None)` (all entries incl. disabled, merged in order across formats; cross-source duplicates raise unless `replace`, which keeps the first position) and `load_beat_schedule` (enabled entries → `to_celery()`). `_parse_document` is the format-agnostic document layer: `None` → empty, top level must be a mapping, top-level keys starting with `.` are templates (anchor carriers in YAML, merely skipped in TOML).
+- `tasks.py` — `check_tasks(app, schedule=None)` compares task names with `app.tasks` (default: the app's own `beat_schedule`). Documented to run in a `beat_init` handler, because beat imports task modules right before sending that signal.
+
+Deliberate decisions worth keeping:
+
+- **Strict over lenient**: unknown keys, duplicate keys and invalid crontab fields fail at load time — a silently dropped schedule is the failure mode this library exists to prevent.
+- **Explicit schedule kinds** (`every` / `crontab` / `solar`), no shape-inferred scalar shorthand — chosen by Simon.
+- `replace=True` replaces whole entries; there is no field-level patching across files.
+- Format differences that are inherent and documented, not papered over: anchors/templates are YAML-only; a duplicate entry within one TOML file is a TOML syntax error (a `DefinitionError`, not a `DuplicateEntryError` — parsing tomllib's message would be fragile); TOML has no null, so empty `kw:`-style values are simply omitted.
+- `tests/action0/celery_sched/test_format_parity.py` loads one feature-complete schedule written in both formats and requires identical entries (including `schedule.relative`, which Celery's `schedule.__eq__` ignores). Any new entry feature must be added to both spellings there.
+
+Conventions:
+
+- The version is single-sourced as `__version__` in `src/action0/celery_sched/__init__.py`; hatch extracts it with the regex in `[tool.hatch.version]`. Bump it only there.
+- Releases: pushing a `vX.Y.Z` tag triggers `.github/workflows/release.yml`, which re-runs all checks, verifies the tag matches `__version__`, builds, and publishes to PyPI via trusted publishing (environment `pypi`). Never bump the version, tag, or publish on your own — releasing is the user's call.
+- Tests mirror the `src/` layout under `tests/action0/celery_sched/` and are `unittest.TestCase` classes, executed via pytest. `test_loader.py` includes an integration test that feeds the result (from both formats) into Celery's own `beat.Scheduler`.
+- `test_without_pyyaml.py` runs a subprocess with `sys.modules["yaml"] = None` (stricter than uninstalling: it also catches indirect imports) and checks that the package imports, TOML and mapping sources load, and a YAML source raises the extra's `ImportError` before any I/O.
+- Celery ships no type information; the dev group includes `celery-types` (stubs), `pyyaml` (the `yaml` extra, for tests and docs) and `types-pyyaml`. Where the stubs lack something (e.g. `solar._all_events`), use `getattr` with a comment rather than an ignore. When an ignore is unavoidable, silence each checker with its own syntax (`# type: ignore[code]  # ty: ignore[code]`).
+- Ruff enforces one import per line (isort `force-single-line`), line length 99, `action0` as first-party. Ruff only honours `.gitignore` inside a git repository.
+- Docs live in `docs/` (Sphinx + Furo, MyST Markdown pages, sphinx-design tabs, autodoc for the API reference, intersphinx to Python and Celery). Docstrings are Sphinx-reST (`:param:`, `:py:func:` roles). CI builds them with `-W` on every run and deploys to GitHub Pages on pushes to `main`. Examples in `docs/usage.md` and `README.md` show real outputs and error messages — keep them truthful, and keep every fenced `yaml`/`toml` block valid.
+- **Both formats, equally (Simon's rule):** every example is given in YAML *and* TOML — in the guide, the index, the README and docstring examples. YAML comes first, TOML second. In Sphinx pages, use a sphinx-design tab-set with `:sync-group: format` and tab items `YAML` (`:sync: yaml`) then `TOML` (`:sync: toml`); a shown error message goes inside the tab next to the input that causes it. On GitHub-rendered files (README) and in docstrings, a YAML block followed by the equivalent TOML block. Each pair must mean the same (identical entries). Prose stays format-neutral: write `schedule`, not `schedule:` or `schedule =`. Only features that exist in one format alone (YAML anchors/templates) are shown in one format, next to how the other format does without.
+- The GitHub Pages site must be enabled once per repo before `deploy-docs` can run: `gh api repos/LaughInJar/action0-celery-sched/pages -X POST -f build_type=workflow`.
+- The README carries an AI-usage disclosure section — keep it accurate when the development workflow changes.

action0_celery_sched-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LaughInJar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

action0_celery_sched-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.5
+Name: action0-celery-sched
+Version: 0.1.0
+Summary: Celery beat schedules defined in YAML or TOML files
+Project-URL: Homepage, https://github.com/LaughInJar/action0-celery-sched
+Project-URL: Documentation, https://laughinjar.github.io/action0-celery-sched/
+Project-URL: Source, https://github.com/LaughInJar/action0-celery-sched
+Project-URL: Issues, https://github.com/LaughInJar/action0-celery-sched/issues
+Author: Simon Lachinger
+License-Expression: MIT
+License-File: LICENSE
+Keywords: beat,celery,celery-beat,crontab,periodic-tasks,schedule,toml,yaml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Celery
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: celery>=5.3
+Provides-Extra: solar
+Requires-Dist: ephem>=4.1; extra == 'solar'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# Action0-Celery-Sched
+
+[![CI](https://github.com/LaughInJar/action0-celery-sched/actions/workflows/ci.yml/badge.svg)](https://github.com/LaughInJar/action0-celery-sched/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/action0-celery-sched)](https://pypi.org/project/action0-celery-sched/)
+
+Celery beat schedules defined in YAML or TOML files: which task runs when,
+with which arguments, kept out of the code and validated when the app starts.
+
+Requires Python 3.11 or newer and Celery 5.3 or newer.
+
+Full documentation including the API reference:
+<https://laughinjar.github.io/action0-celery-sched/>
+
+**Status:** early. The file format in YAML and TOML, all three kinds of Celery
+schedule, the validation and the task check work and are covered by tests; the
+API may still move.
+
+## Installation
+
+```shell
+pip install action0-celery-sched                # TOML schedules
+pip install "action0-celery-sched[yaml]"        # YAML schedules too (PyYAML)
+pip install "action0-celery-sched[solar]"       # solar schedules (ephem)
+pip install "action0-celery-sched[yaml,solar]"  # all of it
+```
+
+TOML needs nothing beyond the standard library's `tomllib`; YAML needs PyYAML,
+which the `yaml` extra brings along. (`uv add` works the same way.)
+
+## Usage
+
+Write the schedule down, in YAML or in TOML — the entries are the same in
+both:
+
+```yaml
+# beat.yaml
+"Poll feed":
+  task: myapp.feeds.tasks.poll
+  schedule:
+    every: 5m                  # or 300, 90s, 1h30m, {minutes: 5}
+
+"Nightly report":
+  task: myapp.reports.tasks.nightly
+  kw:                          # keyword arguments
+    recipients: [ops@example.com]
+  params:                      # positional arguments
+    - daily
+  schedule:
+    crontab: "0 3 * * *"       # or {minute: 0, hour: 3}, or @daily
+  options:                     # passed on to apply_async()
+    queue: reports
+
+"Sunset lights":
+  task: myapp.home.tasks.lights_on
+  schedule:
+    solar: {event: sunset, lat: 48.21, lon: 16.37}
+```
+
+```toml
+# beat.toml
+["Poll feed"]
+task = "myapp.feeds.tasks.poll"
+schedule = { every = "5m" }                 # or 300, "90s", "1h30m", { minutes = 5 }
+
+["Nightly report"]
+task = "myapp.reports.tasks.nightly"
+kw = { recipients = ["ops@example.com"] }   # keyword arguments
+params = ["daily"]                          # positional arguments
+schedule = { crontab = "0 3 * * *" }        # or { minute = 0, hour = 3 }, or "@daily"
+options = { queue = "reports" }             # passed on to apply_async()
+
+["Sunset lights"]
+task = "myapp.home.tasks.lights_on"
+schedule = { solar = { event = "sunset", lat = 48.21, lon = 16.37 } }
+```
+
+And hand it to Celery:
+
+```python
+from celery import Celery
+from action0.celery_sched import load_beat_schedule
+
+app = Celery("myapp")
+app.conf.beat_schedule = load_beat_schedule("beat.yaml")
+# or
+app.conf.beat_schedule = load_beat_schedule("beat.toml")
+```
+
+The suffix decides the format (`format="yaml"` or `format="toml"` for anything
+else). A mapping works too, e.g. the `beat` part of a larger YAML or TOML
+config: `load_beat_schedule(settings["beat"])`.
+
+The result is plain Celery, a `beat_schedule` dict of `schedule`, `crontab`
+and `solar` objects:
+
+```python
+{'Poll feed': {'task': 'myapp.feeds.tasks.poll',
+               'schedule': <freq: 5.00 minutes>,
+               'args': (),
+               'kwargs': {},
+               'options': {}},
+ ...}
+```
+
+Everything is validated while loading. An unknown key such as a misspelled
+`shedule`, an impossible crontab field, or an entry name used twice is an
+error naming the file, the entry and the key — the same message for both
+formats, here for the crontab `"0 25 * * *"`:
+
+```text
+beat.yaml: entry 'Nightly report': schedule.crontab.hour: invalid value '25': Invalid end range: 25 > 23.
+beat.toml: entry 'Nightly report': schedule.crontab.hour: invalid value '25': Invalid end range: 25 > 23.
+```
+
+Values that differ per environment can come from environment variables, and
+entries can be switched off without deleting them. In YAML `!ENV` is a tag;
+TOML has no tags, so there it is a prefix of the string:
+
+```yaml
+"Nightly report":
+  task: myapp.reports.tasks.nightly
+  schedule:
+    crontab: !ENV ${REPORT_CRON:-0 3 * * *}
+  enabled: !ENV ${REPORTS_ENABLED:-true}
+```
+
+```toml
+["Nightly report"]
+task = "myapp.reports.tasks.nightly"
+schedule = { crontab = "!ENV ${REPORT_CRON:-0 3 * * *}" }
+enabled = "!ENV ${REPORTS_ENABLED:-true}"
+```
+
+Several files merge in order, whatever their format. With `replace=True` a
+later file may override or disable entries of an earlier one:
+
+```python
+app.conf.beat_schedule = load_beat_schedule(
+    "beat/common.yaml", f"beat/{environment}.toml", replace=True
+)
+```
+
+A misspelled `task` name would only surface when the task is first due. Catch
+it when beat starts instead:
+
+```python
+from celery.signals import beat_init
+from action0.celery_sched import check_tasks
+
+
+@beat_init.connect
+def check_schedule(sender, **kwargs):
+    check_tasks(sender.app)  # raises UnknownTaskError listing every unknown name
+```
+
+See the [usage guide](https://laughinjar.github.io/action0-celery-sched/usage.html)
+for the full file format, every example in both YAML and TOML: every interval
+and crontab spelling, `relative` intervals, how the two formats differ,
+templates and anchors, and the error types.
+
+The `action0` namespace is simply the one the author likes to use for
+personal projects.
+
+## Development
+
+```shell
+uv run pytest          # tests (incl. doctests in src/)
+uv run ruff check      # lint
+uv run ruff format     # format
+uv run mypy            # type-check (strict)
+uv run pyright         # type-check
+uv run ty check        # type-check
+```
+
+## AI disclosure
+
+This library is developed with heavy use of AI coding tools: the code,
+tests, and documentation are largely written by
+[Claude Code](https://claude.com/claude-code), working from the author's
+design brief and reviewed by the author. If that changes how much you want
+to rely on this package, that's a fair call — read the source, it's small.
+
+## License
+
+MIT — see [LICENSE](https://github.com/LaughInJar/action0-celery-sched/blob/main/LICENSE).