Contributions are most welcome (but do inform about it if you've used AI or other tools). If the length of this text scares you, then I'd rather want you to skip reading and just produce a pull-request in GitHub. If you find it too difficult to write test code, etc, then you may skip it and hope the maintainer will fix it.
Every submission should ideally include:
- Test code covering the new behaviour or bug fix
- Documentation updates where relevant
- A changelog fragment in
news/(see below)
The change log is assembled by towncrier
at release time. Add one small reStructuredText file per change to news/,
named <issue or PR number>.<type>.rst, for example 42.bugfix.rst. The
types are listed under [tool.towncrier] in pyproject.toml: breaking,
removal, feature, bugfix, documentation, deps, internal, chore
and security. towncrier create makes the file for you. A pull request
touching nothing but tests/ or this file is not checked for one, and any
other with nothing worth mentioning can be labelled skip-changelog.
python3 -m venv .venv
. .venv/bin/activate
make dev
pre-commit install --hook-type pre-commit --hook-type pre-push --hook-type commit-msg
make test
make dev also installs caldav and the embedded Xandikos and Radicale
servers, which the CalDAV backend's conformance tests run against (they are
skipped when missing).
The CalDAV conformance suite and the readable stories in
tests/test_scenarios.py (which also run on the files and memory
backends) can also run against the docker and external servers of
caldav's own test framework, caldav.testing. That needs caldav 3.7.0
or later. The servers are not started for you; start them in a caldav
checkout first:
(cd ~/caldav/tests/docker-test-servers/baikal && ./start.sh)
pytest --caldav-servers=Baikal -k Baikal
--caldav-servers takes a comma-separated list of names, and a named
server that is not running fails its tests. all takes every server
caldav knows of: the docker servers, the external ones in
~/.config/caldav/test_servers.yaml (and in tests/caldav_test_servers.yaml
when caldav is installed from a checkout), and the sections of your
caldav configuration marked test_allowed.
--caldav-servers-config=PATH adds the servers of another such yaml
file, and its entries win over those caldav found itself. Give both
options with =: with a space, pytest takes the value for a test path,
moves its root directory there, never loads tests/conftest.py and
stops with "unrecognized arguments".
Under all, a server that is not running is skipped. Without docker,
caldav lists a docker server only while it is running. For these
servers, the PYTHON_CALDAV_TEST_* switches and caldav's per-server
locks apply, so a caldav test run on the same server is waited for rather
than clobbered; the embedded Xandikos and Radicale always run, and take
no lock.
A run on every server takes hours, most of them on the slowest servers. Run the servers in parallel, spread over the workers, one server per worker at a time:
pytest --caldav-servers=all -n 12 --dist loadgroup
--dist loadgroup is what keeps a server's tests together; plain -n
spreads them, and two workers then fight over one server.
Which servers pass, and why the others do not, is in docs/caldav-servers.md.
The async code in the _async/ directories is the source; the _sync/
directories next to them are generated from it with unasync and committed.
Edit _async/ only, then run
python tools/generate_sync.py
The generator renames AsyncX to SyncX, drops async and await, and
applies the replacement map in tools/generate_sync.py. Every file in
_async/ starts with a one-line comment, which becomes the do-not-edit
header in its copy. tests/test_generated_sync.py fails if a _sync/
copy is stale, and it also rejects what a token rewrite cannot translate:
asyncio, threads, sleeps and anything else with no token-for-token sync equivalent go insrc/calendaring/_concurrency.py, written once per mode, with an entry in the replacement map (agather->gather); blocking I/O, such as the files backend's, goes throughawait ato_thread(call, ...), which runs it in a worker thread in the async mode and directly in the sync one (to_thread);- a third-party
Async*name, such ashttpx.AsyncClient, would become aSyncClientthat does not exist: import it through a mode-free module and map it in the replacement map, as_caldav_io.pydoes for caldav'sAsyncDAVClient; - a library whose methods return
X | Coroutine(caldav's dual-mode objects) hides a missingawaitfrom the type checker: call it only through a thin, honestly typed wrapper in_async/, as_async/dav.pydoes, where one helper resolves the union per mode (_awaited, which the generator turns into_returned); - the token right after
awaitis dropped, meant to be the space: writeawait x, neverawait(x); - a name the generator renames must not sit inside an f-string, since whether it gets renamed there depends on the Python version.
A forgotten await in _async/ is a correct call once the generator has
removed it, so the sync tests cannot catch it. mypy (strict) and ruff
(F841) can, and tests/test_enforcement.py checks that they still do, on
the planted mistakes in tests/specimens/. So keep the code fully
annotated, and do not silence an unused-coroutine error.
- Write it in
src/calendaring/_async/<name>.pyasAsync<Name>BackendandAsync<Name>Collection, subclassingAsyncBackendandAsyncCollection. Setkind = "<name>"on the backend class, soBackend.open(kind="<name>")finds it. The backend implements_openandcollections; the collection implements the primitives (_query,_fetch,_create,_update,_delete). Capability checks, loss policies, client-side filtering and the rest are written once in the base classes._async/memory.py, the reference backend, is the smallest complete example. A backend with a time log of its own (a tracker) also overrides_time_entries,_time_log,_add_time,_amend_timeand_delete_time; the defaults store entries asVEVENTs. - Declare its capabilities honestly, in the
capabilitieseach constructor takes. The conformance suite asserts that an operation declared unsupported fails as specified. - Add both class names to
REPLACEMENTSintools/generate_sync.py, so the sync classes are unprefixed (<Name>Backend, notSync<Name>Backend). A test fails if you forget. - Run the generator, and import both modes from a public module (as
calendaring/memory.pydoes). Import that module incalendaring/__init__.py: a backend registers itskindwhen it is imported, so until thenopen()cannot find it. - Add
tests/_async/test_<name>_conformance.py, with a class that subclassescalendaring.testing.AsyncConformanceand returns the backend fromopen_backend(). The generator writes the sync tests.
Please follow Conventional Commits and write messages in the imperative mood:
fix: correct time-range search handling for recurring eventsfeat: add new checkdocs: update README
Rather than:
This commit fixes the time-range searchAdded new check