Development
Adding Features
In order to add a feature to bezier
:
Discuss: File an issue to notify maintainer(s) of the proposed changes (i.e. just sending a large PR with a finished feature may catch maintainer(s) off guard).
Add tests: The feature must work fully on CPython versions 3.10, 3.11 and 3.12 and on PyPy 3; on Linux, macOS and Windows. In addition, the feature should have 100% line coverage.
Documentation: The feature must (should) be documented with helpful doctest examples wherever relevant.
libbezier
To build the Fortran shared library directly, use CMake version
3.5
or later:
$ SRC_DIR="src/fortran/"
$ BUILD_DIR=".../libbezier-debug/build"
$ INSTALL_PREFIX=".../libbezier-debug/usr"
$ mkdir -p "${BUILD_DIR}"
$ cmake \
> -DCMAKE_BUILD_TYPE=Debug \
> -DCMAKE_INSTALL_PREFIX:PATH="${INSTALL_PREFIX}" \
> -DCMAKE_VERBOSE_MAKEFILE:BOOL=ON \
> -S "${SRC_DIR}" \
> -B "${BUILD_DIR}"
$ cmake \
> --build "${BUILD_DIR}" \
> --config Debug \
> --target install
Binary Extension
Many low-level computations have alternate implementations in Fortran. See the Python Binary Extension page for a more detailed description.
Building / Compiling
To compile the binary extension (with libbezier
built and installed
already) run:
$ # One of
$ BEZIER_INSTALL_PREFIX=.../usr/ python -m pip wheel .
$ BEZIER_INSTALL_PREFIX=.../usr/ python -m pip install .
$ BEZIER_INSTALL_PREFIX=.../usr/ python setup.py build_ext
$ BEZIER_INSTALL_PREFIX=.../usr/ python setup.py build_ext --inplace
Using a Release build of libbezier
may make debugging more difficult.
Instead, a Debug build of libbezier
will include debug symbols, without
optimizations that move code around, etc.
To explicitly disable the building of the extension, the
BEZIER_NO_EXTENSION
environment variable can be used:
$ BEZIER_NO_EXTENSION=True .../bin/python -m pip wheel .
This environment variable is actually used for the nox --session docs
session to emulate the RTD build environment (where no Fortran compiler is
present).
Dependencies
Currently, the src/fortran/quadpack.f90
file has a subset of Fortran 77
subroutines from QUADPACK converted into Fortran 90 by John Burkardt.
This code is Public Domain, so does not conflict with the Apache 2.0 license
(as far as we know).
QUADPACK is used to perform numerical quadrature to compute the length of a curve segment.
Windows
Building the binary extension requires a Fortran compiler. Unfortunately, there
is no Fortran compiler provided by MSVC. The MinGW-w64 suite of tools is a
port of the GNU Compiler Collection (gcc
) for Windows. In particular, MinGW
includes gfortran
.
To install MinGW-w64, download a recent MSYS2 Installer (e.g.
msys2-x86_64-20230526.exe
). When installing, take note of the install
location. It should default to C:\msys64
. After installing, use
pacman
(provided by MSYS2) to install the MinGW-w64 toolchain:
> pacman -S --needed base-devel mingw-w64-x86_64-toolchain
After doing this, you may want to permanently add the MinGW bin directory
(e.g. C:\msys64\mingw64\bin
) to your PATH
. If you don’t want to make
a permanent change, you’ll need to temporarily modify your PATH
in shell
sessions where bezier
is being developed:
> $env:Path = "C:\msys64\mingw64\bin;" + $env:Path
Additionally, the BEZIER_EXTRA_DLL
environment variable may need to be
set for nox
sessions if the MinGW-w64 DLLs cannot be found (to be added the
DLL search path):
> $env:BEZIER_EXTRA_DLL = "C:\msys64\mingw64\bin"
In addition to a Fortran toolchain, you will also need the MSVC toolchain that was used to build each version of Python. The Microsoft C++ Build Tools can be installed to enable this toolchain.
Running Unit Tests
We recommend using Nox to run unit tests:
$ nox --session "unit-3.10"
$ nox --session "unit-3.11"
$ nox --session "unit-3.12"
$ nox --session "unit-pypy3"
$ nox --session unit # Run all versions
However, pytest can be used directly (though it won’t manage dependencies or build the binary extension):
$ PYTHONPATH=src/python/ python3.10 -m pytest tests/unit/
$ PYTHONPATH=src/python/ python3.11 -m pytest tests/unit/
$ PYTHONPATH=src/python/ python3.12 -m pytest tests/unit/
$ PYTHONPATH=src/python/ pypy3 -m pytest tests/unit/
Testing the Binary Extension
When using nox
, libbezier
will be built and installed into a well-known
BEZIER_INSTALL_PREFIX
within the nox
envdir (typically .nox/
), the
bezier
package will automatically be installed into a virtual environment
and the binary extension will be built during install.
However, if the tests are run directly from the source tree via
$ PYTHONPATH=src/python/ python -m pytest tests/unit/
some unit tests may be skipped. The unit tests that explicitly exercise the
binary extension will skip (rather than fail) if the extension isn’t
compiled (with build_ext --inplace
) and present in the source tree.
Test Coverage
bezier
has 100% line coverage. The coverage is checked
on every build and uploaded to coveralls.io via the
COVERALLS_REPO_TOKEN
environment variable set in
the GitHub Actions secrets.
To run the coverage report locally:
$ nox --session cover
$ # OR
$ PYTHONPATH=src/python/ python -m pytest \
> --cov=bezier \
> --cov=tests.unit \
> tests/unit/
Slow Tests
To run unit tests without test cases that have been (explicitly)
marked slow, use the --ignore-slow
flag:
$ nox --session "unit-3.10" -- --ignore-slow
$ nox --session "unit-3.11" -- --ignore-slow
$ nox --session "unit-3.12" -- --ignore-slow
$ nox --session unit -- --ignore-slow
These slow tests have been identified via:
$ ...
$ nox --session "unit-3.11" -- --durations=10
and then marked with pytest.mark.skipif
.
Slow Install
Installing NumPy with PyPy can take upwards of two minutes (however the NumPy project has started publishing built wheels for PyPy) and installing SciPy can take as much as seven minutes. This makes it prohibitive to create a new environment for testing.
In order to avoid this penalty, the WHEELHOUSE
environment variable can be
used to instruct nox
to install NumPy and SciPy from locally built wheels
when installing the pypy3
sessions.
To pre-build NumPy and SciPy wheels:
$ pypy3 -m virtualenv pypy3-venv
$ pypy3-venv/bin/python -m pip wheel --wheel-dir="${WHEELHOUSE}" numpy
$ pypy3-venv/bin/python -m pip install "${WHEELHOUSE}/numpy*.whl"
$ pypy3-venv/bin/python -m pip wheel --wheel-dir="${WHEELHOUSE}" scipy
$ rm -fr pypy3-venv/
In addition to the WHEELHOUSE
environment variable, the paths
${HOME}/wheelhouse
and /wheelhouse
will also be searched for
pre-built wheels.
Functional Tests
Line coverage and unit tests are not entirely sufficient to
test numerical software. As a result, there is a fairly
large collection of functional tests for bezier
.
These give a broad sampling of curve-curve intersection, triangle-triangle intersection and segment-box intersection problems to check both the accuracy (i.e. detecting all intersections) and the precision of the detected intersections.
To run the functional tests:
$ nox --session "functional-3.10"
$ nox --session "functional-3.11"
$ nox --session "functional-3.12"
$ nox --session "functional-pypy3"
$ nox --session functional # Run all versions
$ # OR
$ PYTHONPATH=src/python/ python3.10 -m pytest tests/functional/
$ PYTHONPATH=src/python/ python3.11 -m pytest tests/functional/
$ PYTHONPATH=src/python/ python3.12 -m pytest tests/functional/
$ PYTHONPATH=src/python/ pypy3 -m pytest tests/functional/
For example, the following curve-curve intersection is a functional test case:
and there is a Curve-Curve Intersection document which captures many of the cases in the functional tests.
A triangle-triangle intersection functional test case:
a segment-box functional test case:
and a “locate point on triangle” functional test case:
Functional Test Data
The curve-curve and triangle-triangle intersection test cases are stored in JSON files:
This way, the test cases are programming language agnostic and can be
repurposed. The JSON schema for these files are stored in the
tests/functional/schema
directory.
Coding Style
Code is PEP8 compliant and this is enforced with flake8 and Pylint.
To check compliance:
$ nox --session lint
A few extensions and overrides have been specified in the pylintrc
configuration for bezier
.
Docstring Style
We require docstrings on all public objects and enforce this with
our lint
checks. The docstrings mostly follow PEP257
and are written in the Google style, e.g.
Args:
path (str): The path of the file to wrap
field_storage (FileStorage): The :class:`FileStorage` instance to wrap
temporary (bool): Whether or not to delete the file when the File
instance is destructed
Returns:
BufferedFileStorage: A buffered writable file descriptor
In order to support these in Sphinx, we use the Napoleon extension. In addition, the sphinx-docstring-typing Sphinx extension is used to allow for type annotation for arguments and result (introduced in Python 3.5).
Documentation
The documentation is built with Sphinx and automatically
updated on RTD every time a commit is pushed to main
.
To build the documentation locally:
$ nox --session docs
$ # OR (from a Python 3.10 or later environment)
$ PYTHONPATH=src/python/ ./scripts/build-docs.sh
Documentation Snippets
A large effort is made to provide useful snippets in documentation. To make sure these snippets are valid (and remain valid over time), doctest is used to check that the interpreter output in the snippets are valid.
To run the documentation tests:
$ nox --session doctest
$ # OR (from a Python 3.10 or later environment)
$ PYTHONPATH=src/python/:. sphinx-build -W \
> -b doctest \
> -d docs/build/doctrees \
> docs \
> docs/build/doctest
Documentation Images
Many images are included to illustrate the curves / triangles / etc. under consideration and to display the result of the operation being described. To keep these images up-to-date with the doctest snippets, the images are created as doctest cleanup.
In addition, the images in the Curve-Curve Intersection document and this document are generated as part of the functional tests.
To regenerate all the images:
$ nox --session docs_images
$ # OR (from a Python 3.10 or later environment)
$ export MATPLOTLIBRC=docs/ GENERATE_IMAGES=True PYTHONPATH=src/python/
$ sphinx-build -W \
> -b doctest \
> -d docs/build/doctrees \
> docs \
> docs/build/doctest
$ python tests/functional/make_segment_box_images.py
$ python tests/functional/make_triangle_locate_images.py
$ python tests/functional/make_curve_curve_images.py
$ python tests/functional/make_triangle_triangle_images.py
$ unset MATPLOTLIBRC GENERATE_IMAGES PYTHONPATH
Continuous Integration
Tests are run on GitHub Actions (Linux, macOS and Windows) after every commit. To see which tests are run, see the Linux config, the macOS config and the Windows config.
Release Process / Deploying New Versions
New versions are pushed to PyPI manually after a git
tag is
created. The process is manual (rather than automated) for several
reasons:
The documentation and README (which acts as the landing page text on PyPI) will be updated with links scoped to the versioned tag (rather than
main
). This update occurs via thedoc_template_release.py
script.Several badges on the documentation landing page (
index.rst
) are irrelevant to a fixed version (such as the “latest” version of the package).The build badges in the README and the documentation will be changed to point to a fixed (and passing) build that has already completed (will be the build that occurred when the tag was pushed). If the builds pushed to PyPI automatically, a build would need to link to itself while being run.
Wheels need to be built for Linux, macOS and Windows. Building wheels occurs via the Building Wheels workflow. After being built, each wheel will be pushed directly to PyPI via twine.
The release will be manually pushed to TestPyPI so the landing page can be visually inspected and the package can be installed from TestPyPI rather than from a local file.
Supported Python Versions
bezier
explicitly supports:
Supported versions can be found in the noxfile.py
config.
Versioning
bezier
follows calendar versioning.
Environment Variables
This project uses environment variables for building the
bezier._speedup
binary extension:
BEZIER_INSTALL_PREFIX
: A directory wherelibbezier
is installed, including the shared library (lib/
) and headers (include/
). This environment variable is required to build the binary extension.BEZIER_NO_EXTENSION
: If set, this will indicate that only the pure Python package should be built and installed (i.e. without the binary extension).BEZIER_IGNORE_VERSION_CHECK
: Will instructpip
andsetup.py
to ignore a check on the current version of Python. By default, Python installs ofbezier
will explicitly check for supported versions and this opts out of that check (e.g. if a new version of Python was just released). This will only be relevant when installing from source, but a new version of Python will also mean the existing wheels on PyPI won’t support that new version.BEZIER_EXTRA_DLL
: Used to add (optional) extra directory to DLL search path on Windows. This is intended to be used in tests primarily, but may also be required when building from source. Multiple directories can be provided, separated by the Windows path separator (;
).
and for running tests and interacting with Continuous Integration services:
WHEELHOUSE
: If set, this gives a path to prebuilt NumPy and SciPy wheels for PyPy 3.GENERATE_IMAGES
: Indicates tonox --session doctest
that images should be generated during cleanup of each test case.READTHEDOCS
: Indicates currently running on Read The Docs (RTD). This is used to tell Sphinx to use the RTD theme when not running on RTD.COVERALLS_REPO_TOKEN
: To upload the coverage report.