Skip to content

DEVELOPING.md

Latest commit

 

History

History
90 lines (57 loc) · 4.4 KB

DEVELOPING.md

File metadata and controls

90 lines (57 loc) · 4.4 KB
Raw

Developing WFDB-Python

Guidelines

We welcome community contributions in the form of pull requests. When contributing code, please ensure:

  • Documentation is provided. New functions and classes should have numpy/scipy style docstrings. Start the docstring on the line of the opening quotes, with a summary that fits on a single line (the documentation build fails on warnings, so check it with uv run --only-group docs make -C docs html SPHINXOPTS="-W --keep-going").
  • Unit tests are written for new features that are not covered by existing tests.
  • The code style is consistent with the project's formating standards.

Format and lint the code with Ruff:

ruff format .
ruff check .

Commits that only reformat the code are listed in .git-blame-ignore-revs. GitHub skips them in its blame view automatically. To do the same locally, run:

git config blame.ignoreRevsFile .git-blame-ignore-revs

Package and Dependency Management

This project uses uv for package management and distribution.

Development dependencies are specified in the dev dependency group, which uv run installs automatically:

uv add --dev <somepackage>

Ruff is pinned to an exact version because new releases can change formatting and lint results. Dependabot opens monthly pull requests to bump it, along with the pinned documentation dependencies, uv-build, and the GitHub Actions.

Creating Distributions

  1. Bump the version in pyproject.toml.

  2. Add a summary of the changes to the changelog. You may also need to update the documentation. For example, if function arguments have been updated, this change will need to be captured. Open a pull request to merge these changes to the main branch.

  3. After the pull requests above have been merged, go to https://github.com/MIT-LCP/wfdb-python/releases and click "Draft new release" to create a new tag/release of the package. Set the tag to the new version number and draft the release notes (or click "Generate release notes"!).

  4. Publish the project to PyPI, the Python Package Index.

It may be useful to publish to testpypi and preview the changes before publishing to PyPi. However, the project dependencies likely will not be available when trying to install from there.

Setup: create an API token on PyPI (and on TestPyPI for test uploads) and pass it to uv:

export UV_PUBLISH_TOKEN=<my-token>

To build and upload a new distribution:

uv build

uv publish --publish-url https://test.pypi.org/legacy/
uv publish

Creating Documentation

The project's documentation is generated by Sphinx using the content in the docs directory. The generated content is then hosted on readthedocs (RTD) at: http://wfdb.readthedocs.io

To manage the content on RTD, request yourself to be added to the wfdb project. The project has already been configured to import content from the GitHub repository. Documentation for new releases should be automatically built and uploaded. See the import guide for more details.

The documentation dependencies are specified in the docs dependency group in pyproject.toml, which is used both locally and by RTD. To generate the HTML content locally, run:

uv run --only-group docs make -C docs html

Tests

Run tests using pytest:

pytest
# Distribute tests across multiple cores.
# https://github.com/pytest-dev/pytest-xdist
pytest -n auto

Tests that stream or download data from PhysioNet are marked with network. Most of them also exist as a local variant (for example, test_1a[local] and test_1a[physionet]), so a slow or unreachable PhysioNet only affects the physionet variants. If PhysioNet cannot be reached, these tests are skipped instead of failing. To run only the tests that work offline:

pytest -m "not network"