zabbix-crontroller 0.0.1__tar.gz

zabbix_crontroller-0.0.1/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

zabbix_crontroller-0.0.1/CONTRIBUTE.md

@@ -0,0 +1,151 @@
+# Contributing
+
+Use Python 3.14 or later and uv. The deployment target is Linux with cron
+installed; other operating systems are not supported deployment targets.
+
+## Development setup
+
+Install the package and run all tests:
+
+```sh
+uv sync
+uv run python -m unittest discover -s tests -v
+```
+
+The tests use Python's standard library. They cover the public parser API,
+documentation and repository examples, importing the package from outside the
+repository, and actual wrapper subprocesses. Runtime tests exercise byte capture,
+signals, concurrent runs, retention and injected storage/forwarding failures.
+All tests must pass before a change is accepted. Linux is the deployment target;
+passing tests on another POSIX platform does not establish cron compatibility.
+
+Use `uv run zabbix-crontroller --help` to exercise the installed entry point. The
+wrapper is also available as `uv run python -m zabbix_crontroller.app`. Test run
+evidence belongs in temporary directories, with `ZC_STATE_DIR` set explicitly.
+See [runtime behaviour](docs/RUNTIME.md) for the evidence format and a Linux cron
+integration procedure. Do not install a test crontab over a user's real jobs.
+
+## Automated Linux checks
+
+The CI workflow runs on branch pushes and pull requests that change a `.py` file
+at any depth, `.python-version`, `LICENSE`, `pyproject.toml` or `uv.lock`. Every
+matching run executes the full suite, including `LICENSE`-only changes.
+Documentation-only and workflow-only changes do not trigger CI, as required by
+[AGENTS.md](AGENTS.md). A separate tag-push workflow always runs the same checks,
+regardless of changed paths, before building release packages.
+
+The shared [Linux workflow](.github/workflows/linux-tests.yml) runs Black and
+tests these distribution families on GitHub's Ubuntu x86-64 Docker runners:
+
+| Distribution | Container base | Cron package |
+| --- | --- | --- |
+| Ubuntu 24.04 LTS | `ubuntu:24.04` | `cron` |
+| Debian 13 | `debian:13-slim` | `cron` |
+| Fedora 44 | `fedora:44` | `cronie` |
+| Rocky Linux 9 | `rockylinux:9` | `cronie` |
+| openSUSE Leap 16.0 | `opensuse/leap:16.0` | `cronie` |
+| Alpine 3.24 | `alpine:3.24` | `cronie` |
+
+uv installs the latest patch of the Python version in `.python-version`, including
+the musl build on Alpine. Alpine uses Cronie explicitly; these checks do not
+establish compatibility with BusyBox crond. Each container runs every unittest
+as root and `zc-test`, then starts the native cron daemon and waits for actual
+minute-boundary dispatch. Three monitored jobs per account plus an unwrapped
+control check exit status, stdout/stderr capture and forwarding, `%` handling,
+stdin, environment, working directory, umask, shell selection, correlation IDs
+and evidence permissions. Both executable installation locations and both
+candidate-file and `crontab -l` validation are exercised.
+
+The checkout is mounted read-only and copied into the disposable container. The
+test installation is editable and uses a placeholder version; CI does not create
+release distributions. The harness refuses to replace existing crontabs. The
+Alpine image removes its stock maintenance crontab during image preparation.
+Containers do not run systemd, so service-manager integration and host security
+policies such as SELinux remain separate deployment checks.
+
+To reproduce one matrix entry locally, run these commands from the repository
+root with Docker available. Change `BASE_IMAGE` to another value from the table:
+
+```sh
+docker build --pull --build-arg BASE_IMAGE=debian:13-slim \
+  --build-arg PYTHON_VERSION="$(cat .python-version)" \
+  --tag zc-linux-tests tests/linux
+docker run --name zc-linux-tests --init \
+  --mount "type=bind,source=$PWD,target=/source,readonly" zc-linux-tests
+# Collect evidence even if the preceding test command failed.
+mkdir -p /tmp/zc-linux-reports
+docker cp zc-linux-tests:/reports/. /tmp/zc-linux-reports/
+docker logs zc-linux-tests > /tmp/zc-linux-reports/container.log 2>&1
+docker rm -f zc-linux-tests
+```
+
+The workflow uploads `linux-DISTRIBUTION` diagnostic artefacts for 14 days, even
+on failure. They contain the full unittest logs, cron configuration and daemon
+log, captured run evidence and `result.json` with operating system, architecture,
+Python and cron versions. Local Docker uses the host's architecture by default;
+use `--platform linux/amd64` for both build and run to reproduce GitHub's target
+on an ARM host. The cron check normally completes within a minute after the
+suite; it fails after 100 seconds without the expected run evidence.
+
+## Code and documentation
+
+Follow PEP 8 and PEP 257, use Python docstrings, and keep implementations simple.
+Prefer standard-library solutions where suitable. Write documentation, docstrings
+and commit messages in British English.
+
+Format Python changes with Black and check formatting before submitting:
+
+```sh
+uvx black src tests
+uvx black --check src tests
+```
+
+Follow the frozen [Syntax Specification](docs/SYNTAX_SPECIFICATION.md) and keep
+the [Syntax User Guide](README.md#syntax), examples and tests consistent with it.
+Changes to published syntax require a new syntax version; published versions
+must remain supported. The required wrapper invocation was added to version `1.0`
+before its first publication. Keep the parser importable independently of the
+application; filesystem checks belong to `zc validate`, not `parse_crontab`.
+
+## Commits and releases
+
+Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#specification).
+The `master` branch is not guaranteed to be stable. Follow
+[Semantic Versioning](https://semver.org) for package releases.
+
+Build and publish release packages through GitHub workflows triggered by a pushed
+tag. Those workflows build both source distributions and wheels, then publish
+them to PyPI and GitHub Releases. Commits alone must not trigger release builds
+or publishing. See [AGENTS.md](AGENTS.md) for repository workflow rules.
+
+The [release workflow](.github/workflows/release.yml) accepts `vMAJOR.MINOR.PATCH`
+tags, for example `v1.0.0`. Pre-release tags use `-alpha.N`, `-beta.N` or `-rc.N`,
+for example `v1.0.0-rc.1`, which becomes Python package version `1.0.0rc1`.
+Other tag formats fail before testing or building. Choose the version according
+to SemVer and never move an already published release tag.
+
+After the Linux matrix and Black pass, `uv build --sdist --wheel` builds both
+distributions. Twine checks the metadata, and both package versions must match
+the tag. The same uploaded artefacts are then published to PyPI and attached to
+a GitHub Release with generated notes. Pre-releases are marked accordingly.
+PyPI publishing uses short-lived OIDC credentials through
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/), without an API
+token secret. The PyPI job alone has `id-token: write`; the GitHub Release job
+alone has `contents: write`. Publishing is never triggered by a branch or pull
+request run.
+
+Before the first release, a maintainer must:
+
+1. Create the GitHub environment `pypi` and restrict its deployment policy to
+   release tags. Add reviewers if the project requires release approval.
+2. Register a PyPI Trusted Publisher (or a pending publisher for a new project)
+   with owner `theriverman`, repository `zabbix-crontroller`, workflow filename
+   `release.yml`, and environment `pypi`.
+3. Allow GitHub Actions in the repository and protect release tags with a
+   repository ruleset appropriate for the maintainers.
+
+Retry failed publishing jobs from the existing workflow run so they reuse the
+validated distributions. uv checks PyPI for identical existing files before
+uploading; a conflicting file fails. The GitHub job can finish attaching the
+same artefacts to an existing release. Do not run release builds or publish
+packages locally to work around a failed workflow.

zabbix_crontroller-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kristof Daja
+
+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.

zabbix_crontroller-0.0.1/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.5
+Name: zabbix-crontroller
+Version: 0.0.1
+Summary: Monitor cron jobs in Zabbix with crontab as the single source of truth.
+Project-URL: Homepage, https://github.com/theriverman/zabbix-crontroller
+Project-URL: Repository, https://github.com/theriverman/zabbix-crontroller
+Author-email: Kristof Daja <22156894+theriverman@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: No Input/Output (Daemon)
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# Zabbix-cRontroller
+Monitor cron jobs in Zabbix with crontab as the single source of truth
+
+# Introduction
+Keep job schedules and metadata in the user's crontab. The `zc` execution wrapper
+records each run's exit status, duration, stdout and stderr in private per-user
+storage. It forwards output to cron or the entry's existing redirections.
+
+This implementation provides local run evidence. Zabbix integration and direct
+file, syslog and journal collection are not implemented yet.
+
+# Installation & Integration
+
+Use Python 3.14 and uv on Linux with cron installed. From a checkout, install for
+the current user and create the short-name symlink:
+
+```sh
+UV_TOOL_BIN_DIR="$HOME/.local/bin" uv tool install --python 3.14 .
+ln -s zabbix-crontroller "$HOME/.local/bin/zc"
+```
+
+For a system installation with sudo:
+
+```sh
+sudo env UV_TOOL_DIR=/opt/zabbix-crontroller/tools \
+  UV_PYTHON_INSTALL_DIR=/opt/zabbix-crontroller/python \
+  UV_TOOL_BIN_DIR=/usr/local/bin uv tool install --python 3.14 .
+sudo ln -s zabbix-crontroller /usr/local/bin/zc
+```
+
+These are local installations, not release builds. Release packages are produced
+only by tagged GitHub workflows. The executable is `zabbix-crontroller`; `zc`
+must be a symlink to it. Use its absolute path in cron, or explicitly set cron's
+`PATH` to include its directory. A non-root example is
+`PATH=/home/batch/.local/bin:/usr/bin:/bin`; cron does not expand `$HOME` in PATH.
+For system installations, the uv tool environment and interpreter must be readable
+and executable by the job owners; the shared `/opt` locations avoid placing them
+inside root's private home. Validate from each job owner's account.
+
+Validate a candidate file, or the current user's installed crontab:
+
+```sh
+zc validate example.crontab
+zc validate
+```
+
+Validation checks the complete syntax and then wrapper and shell availability as
+the invoking user. It never executes a job. Success returns `0`; invalid input,
+acquisition failures and unavailable executables return `1`. Missing crontabs are
+failures, not successful empty configurations.
+
+# Syntax
+
+Keep schedules and commands in your normal user crontab. The
+[Syntax Specification](docs/SYNTAX_SPECIFICATION.md) defines the frozen `1.0`
+notation supported by the parser.
+
+1. Declare `# zc:version = "1.0"` exactly once, before `# zc:start`.
+2. Enclose all monitored jobs in one section, from `# zc:start` to `# zc:end`.
+3. Start each job declaration with `job`: a stable, unique identifier using
+   lowercase ASCII letters, digits, underscores or hyphens, beginning with a letter.
+4. Add a required `name` and, if useful, an optional `description`. These can
+   contain Unicode; the description may appear before or after the name.
+5. Put exactly one cron entry immediately after its metadata. It completes the
+   job declaration. `# zc:end` closes the entire section, not an individual job.
+6. Begin the command with `zc run JOB -- 'COMMAND'`, repeating the exact `job`
+   identifier. Use one literally quoted shell command. Both executable names and
+   absolute paths ending in `zc` or `zabbix-crontroller` are accepted.
+
+For example, a description is not required:
+
+```cron
+# zc:version = "1.0"
+PATH=/usr/local/bin:/usr/bin:/bin
+# zc:start
+# zc:job = "backup-postgres"
+# zc:name = "Orders database backup"
+30 1 * * * zc run backup-postgres -- '/opt/company/maintenance/bin/backup-postgres --database orders'
+# zc:end
+```
+
+Write one property per line using a quoted TOML string. Keep each metadata header
+and its cron entry together. Blank lines, ordinary comments and environment
+assignments may appear between completed jobs. Delimiters may have trailing
+`#` comments, but take no value. Changing a name or command does not require
+changing the job identifier.
+
+The wrapper executes the quoted command using cron's `SHELL`, or `/bin/sh` when
+unset. Put pipelines, command chains and substitutions inside single quotes so
+they execute within the monitored shell. Keep existing output redirections
+outside the quotes if they should receive forwarded output while capture stays
+separate. Use `'"'"'` to include an apostrophe in a single-quoted command.
+Cron still requires escaping literal percentages as `\%`, even inside quotes.
+See [runtime behaviour and evidence](docs/RUNTIME.md) for limits and failure
+handling.
+
+Every cron entry inside the section needs its own metadata. An additional entry
+without metadata is an error, including after the final job. Unannotated entries
+are allowed before and after the section. Job metadata outside the section is
+an error. An empty section is valid, but both delimiters remain required.
+
+Commenting out only a job's cron entry is an error: its metadata will not attach
+to a later entry. To stop discovering a job while keeping it running, remove its
+metadata header **and move its cron entry outside the monitored section**.
+Preserve the relevant environment settings when moving it; section boundaries
+do not reset the cron environment. Removing only the header inside the section
+is an error. Remove the entire declaration to remove both monitoring and execution.
+Malformed configurations prevent publication of the discovery snapshot.
+
+## Syntax example
+
+The [example crontab](example.crontab) contains five monitored jobs and a separate
+unmonitored entry:
+
+```cron
+# Production batch jobs — svc_batch@lon-batch-01
+# Owner: Platform Operations
+# Host timezone: Europe/London. Change requests must reference an approved ticket.
+
+# zc:version = "1.0"
+
+SHELL=/bin/bash
+PATH=/usr/local/bin:/usr/bin:/bin
+MAILTO=platform-operations@example.com
+HOME=/var/lib/batch
+
+# zc:start
+
+# zc:job = "supplier-sync"
+# zc:name = "Supplier stock synchronisation"
+# zc:description = "Collect supplier stock feeds during business hours, Monday–Friday."
+12 7-19 * * 1-5 zc run supplier-sync -- '/usr/bin/flock -n /var/lib/batch/locks/supplier-sync.lock /opt/company/integrations/bin/supplier-sync --config /etc/company/supplier-sync.toml' >> /var/log/batch/supplier-sync.log 2>&1
+
+# zc:job = "backup-postgres"
+# zc:name = "Orders database backup"
+# zc:description = "Nightly database backup; credentials supplied via .pgpass."
+30 1 * * * zc run backup-postgres -- '/opt/company/maintenance/bin/backup-postgres --database orders --retention-days 14' >> /var/log/batch/backup-postgres.log 2>&1
+
+# zc:job = "reconcile-payments"
+# zc:name = "Reconcile payments"
+# zc:description = "Generate the previous business day's reconciliation report before Finance arrives."
+15 6 * * 1-5 zc run reconcile-payments -- '/opt/company/finance/bin/reconcile-payments --period previous-business-day' >> /var/log/batch/reconcile-payments.log 2>&1
+
+# zc:job = "staging-cleanup"
+# zc:name = "Staging cleanup"
+# zc:description = "Remove expired integration staging files during the Sunday maintenance window."
+45 3 * * 0 zc run staging-cleanup -- '/usr/bin/find /var/lib/batch/staging -xdev -type f -mtime +30 -delete' >> /var/log/batch/staging-cleanup.log 2>&1
+
+# zc:job = "sap-export"
+# zc:name = "SAP export"
+# zc:description = "Forward pending warehouse transactions to SAP; prevent overlapping runs."
+*/5 * * * * zc run sap-export -- '/usr/bin/flock -n /var/lib/batch/locks/sap-export.lock /opt/company/integrations/bin/sap-export --env production' >> /var/log/batch/sap-export.log 2>&1
+
+# zc:end
+
+# This separate cron entry runs outside monitoring.
+45 3 * * 0 /usr/bin/find /var/lib/batch/staging -xdev -type f -mtime +30 -delete >> /var/log/batch/staging-cleanup.log 2>&1
+```
+
+# Library usage
+
+Import the parser independently of the application. The caller supplies the
+crontab text; the parser does not run `crontab -l`, execute jobs, read files or
+contact Zabbix.
+
+```python
+from pathlib import Path
+
+from zabbix_crontroller.parser import parse_crontab
+
+text = Path("example.crontab").read_text(encoding="utf-8")
+crontab = parse_crontab(text)
+
+for job in crontab.jobs:
+    print(job.job_id, job.name, job.schedule, job.command)
+```
+
+`parse_crontab(text: str) -> Crontab` returns the declared `version` and a tuple of
+`CronJob` records in source order. Jobs contain the identifier, name, optional
+description, schedule, complete command, `wrapper_executable`, environment
+snapshot and source line numbers. The wrapper field contains its decoded name
+or absolute path; parsing does not check whether that executable is installed.
+Records and their environment mappings are read-only. Missing or blank
+descriptions become `None`. An explicitly empty monitored section returns an
+empty `jobs` tuple.
+
+The parser extracts five-field schedules and `@` nicknames. Schedule field
+values, nickname availability, calendar ranges, time zones and daemon-specific
+extensions are **not validated**. This is a metadata parser, not a replacement
+for the daemon's crontab validator. Input is interpreted as a user crontab, with
+no seconds or username column. Commands retain their internal and trailing
+whitespace, quoting and cron percent sequences without evaluation. Only the
+literal wrapper invocation is validated; the inner shell programme remains
+opaque. Unmonitored commands retain their previous parsing behaviour.
+
+Each environment snapshot contains only preceding explicit assignments, in file
+order, with outer quotes removed. It does not add process environment variables
+or cron defaults, perform substitutions, or model daemon-specific overrides.
+
+Invalid input raises `ParseError`, with `ConfigurationError` for version errors
+and `CrontabSyntaxError` for other parsing errors. Exceptions expose `message`,
+`line_number`, `job_id`, `declaration_line_number` and `previous_line_number`;
+inapplicable locations are `None`. Source lines are one-based. The exception text
+includes the relevant locations. Parsing returns a complete result or raises an
+error; it never returns partial discovery data. Non-string input raises
+`TypeError`.
+
+# Contributing
+
+See [CONTRIBUTE.md](CONTRIBUTE.md) for development setup, tests and contribution
+guidelines.