Contributing

It is recommended that contributions to this project are created within vscode, utilising the devcontainer functionality.

This ensures that all developers are using the same environment and extentions, reducing the risk of additional bugs / formatting issues within the project.

Note

The setup of VSCode devcontainer is outside of the scope of this document additional information can be found within the VSCode documentation.

Setup your environment

  1. Fork the repository

  2. Open the repository in VSCode

  3. Copy the .devcontainer/recommended-devcontainer.json files and rename the copy to devcontainer.json.

  4. Modify the mounts section as required for your environment

  5. Copy the .devcontainer/recommended-docker-compose.yml files and rename the copy to docker.compose.yml

  6. You may need to modify the volumes for your environment

  7. Press ctrl + shift + p and select Remote-Container: Reopen in Container

  8. Once loaded you can begin modification of the module or Documentation

Updating PyArr module

Async & Sync Code Generation

PyArr uses an “Async-first” development model. The core logic resides in src/pyarr/_async/ and uses httpx.AsyncClient. The synchronous version in src/pyarr/_sync/ is automatically generated using a tool called unasync.

Warning

NEVER manually edit files in src/pyarr/_sync/. These files contain a header indicating they are auto-generated. Any manual changes will be overwritten by the CI or the generation script.

When contributing:

  • Only modify files in src/pyarr/_async/.

  • If you modify the async code, you must update the sync version by running:

uv run python3 scripts/generate_sync.py

  • The CI will check for parity. If you forget to run the script, the CI will attempt to auto-fix your PR by committing the generated sync code. However, if you manually edit _sync without changing _async, the CI will fail.

Style & formatting

It is highly recommended to use vsCode devcontainer as this automatically adds the required formatting checks on pre-commit, this will allow for resolution of issues prior to the pull request being submitted.

If you are not using devcontainer please register the pre-commit-config:

poetry run pre-commit install

A few guidelines for approval:

  • Must follow PEP8 / Black formatting. (devcontainer is setup to reformat on save)

  • We recommend using sourcery to ensure code is most efficient, this will be checked when the pull request is opened.

  • All functions must use google docstring format, the devcontainer has an

    autodocstring plugin which will auto fill.

  • pyproject.toml must be updated with a new version, the new versions should

    follow semver.

  • Each feature / bugfix etc. should have its own pull request.

Testing

Tests can be run with the following command: nox -s tests. This command will check code style and typing compliance and will then execute all required``tests``

If you are adding a new method to the library, a test must be added as well. This test should be against the live API, if a mock is required then reason for this should be added to the PR notes.

Updating Documentation

The documentation for this project utilises sphinx. Sphinx allows for automatic documenting of all classes / functions via DocString.

To Update static pages, you can amend the .rst files in the sphinx-docs folder.

To test the documentation locally use command nox -s docs this will create all HTML files in the build directory.

All Python Class / Function documentation is updated automatically by Github Actions and does not require any manual changes to be made.

Sphinx documentation uses reStructuredText to format each of the pages.

Pull Requests & Release

Now that you have made the changes required for your enhancement, a pull request is required for the core team to review the changes, request amendments or approve the work that you have completed.

Pull Requests

  • Each feature / bugfix should have its own PR. This makes code review more efficient

    and allows for a clean changelog generation

  • All CI tests must be passing

  • If a Pull Request contains multiple changes, our core team may reject it

  • All information in the Pull Request template should be completed, when people look

    at what was done with this Pull Request it should be easy to tell from this template

  • It must state if the change is a Breaking Change, and what would break by implementing

Release Changes

To release a new version of the module or documentation updates, the core team

will take the following steps:

  1. Reviewing and testing the PR that has been submitted to ensure all requirements have been met.

  2. Tag the release in git: git tag $NEW_VERSION.

  3. Push the tag to GitHub: git push --tags origin.

  4. If all tests complete the package will be automatically released to PyPI

  5. Github Action will re-create the documentation with Sphinx

If the only change is to documentation, the workflow Sphinx Documentation Update will be run to update the documentation.

Documentation updates don’t require the version to be updated in pyproject.toml and also don’t require tagging.