@@ -5,95 +5,49 @@ CrateDB Python developer guide
55Setup
66=====
77
8- Optionally install Python package and project manager `uv `_,
9- in order to significantly speed up the package installation::
10-
11- {apt,brew,pip,zypper} install uv
12- alias pip="uv pip"
13-
14- To start things off, bootstrap the sandbox environment::
8+ Clone the repository::
159
1610 git clone https://github.com/crate/crate-python
1711 cd crate-python
18- source bootstrap.sh
19-
20- This command should automatically install all prerequisites for the development
21- sandbox and drop you into the virtualenv, ready for invoking further commands.
22-
23-
24- Running tests
25- =============
26-
27- All tests will be invoked using the Python interpreter that was used when
28- creating the Python virtualenv. The test runner is `zope.testrunner `_.
29-
30- Some examples are outlined below. In order to learn about more details,
31- see, for example, `useful command-line options for zope-testrunner `_.
32-
33- Run all tests::
3412
35- poe test
13+ Setup a virtualenv and install the package::
3614
37- Run specific tests::
15+ python -m venv .venv
16+ source .venv/bin/activate
17+ python -m pip install --group dev --group docs -e .
3818
39- # Select modules.
40- bin/test -t test_cursor
41- bin/test -t client
42- bin/test -t testing
19+ Or if using `uv `_::
4320
44- # Select doctests.
45- bin/test -t http.rst
21+ uv venv .venv
22+ source .venv/bin/activate
23+ uv pip install --group dev --group docs -e .
4624
47- Ignore specific test directories::
4825
49- bin/test --ignore_dir=testing
50-
51- The ``LayerTest `` test cases have quite some overhead. Omitting them will save
52- a few cycles (~70 seconds runtime)::
53-
54- bin/test -t '!LayerTest'
55-
56- Invoke all tests without integration tests (~10 seconds runtime)::
57-
58- bin/test --layer '!crate.testing.layer.crate' --test '!LayerTest'
59-
60- Yet ~60 test cases, but only ~1 second runtime::
26+ Running tests
27+ =============
6128
62- bin/test --layer '!crate.testing.layer.crate' --test '!LayerTest' \
63- -t '!test_client_threaded' -t '!test_no_retry_on_read_timeout' \
64- -t '!test_wait_for_http' -t '!test_table_clustered_by'
29+ Ensure the virtualenv is active and run tests using `pytest `_::
6530
66- To inspect the whole list of test cases, run::
31+ python -m pytest
6732
68- bin/test --list-tests
6933
70- The CI setup on GitHub Actions (GHA) provides a full test matrix covering
71- relevant Python versions. You can invoke the software tests against a specific
72- Python interpreter or multiple `Python versions `_ on your workstation using
73- `uv `_, by supplying the ``--python `` command-line option, or by defining the
74- `UV_PYTHON `_ environment variable prior to invoking ``source bootstrap.sh ``.
34+ See also:
7535
76- *Note *: Before running the tests, make sure to stop all CrateDB instances which
77- are listening on the default CrateDB transport port to avoid side effects with
78- the test layer.
36+ - `How to invoke pytest <https://docs.pytest.org/en/stable/how-to/usage.html> ` for more information.
7937
8038
8139Formatting and linting code
8240===========================
8341
84- To use Ruff for code formatting, according to the standards configured in
85- ``pyproject.toml ``, use::
86-
87- poe format
88-
89- To lint the code base using Ruff and mypy, use::
42+ Use `ruff `_ for code formatting and linting::
9043
91- poe lint
44+ ruff format --check .
45+ ruff check .
9246
93- Linting and software testing, all together now::
9447
95- poe check
48+ Use `` mypy `` for type checking::
9649
50+ mypy
9751
9852Renew certificates
9953==================
@@ -147,7 +101,7 @@ Writing documentation
147101
148102The docs live under the ``docs `` directory.
149103
150- The docs are written written with ReStructuredText _ and processed with Sphinx _.
104+ The docs are written with ReStructuredText _ and processed with Sphinx _.
151105
152106Build the docs by running::
153107
@@ -171,4 +125,4 @@ nothing special you need to do to get the live docs to update.
171125.. _uv : https://docs.astral.sh/uv/
172126.. _UV_PYTHON : https://docs.astral.sh/uv/configuration/environment/#uv_python
173127.. _versions hosted on ReadTheDocs : https://readthedocs.org/projects/crate-python/versions/
174- .. _ zope.testrunner : https://pypi. org/project/zope.testrunner /
128+ .. _ pytest : https://docs.pytest. org/en/stable /
0 commit comments