Skip to content

Latest commit

 

History

History
176 lines (118 loc) · 5.77 KB

CONTRIBUTING.md

File metadata and controls

176 lines (118 loc) · 5.77 KB

Development

Here you'll find a contributing guide to get started with development.

Environment

For local development, it is required to have Python 3.11 (or a later version) installed.

We use uv for project management. Install it and set up your IDE accordingly.

We use Poe the Poet as a task runner, similar to npm scripts in package.json. All tasks are defined in pyproject.toml under [tool.poe.tasks] and can be run with uv run poe <task>.

Available tasks

Task Description
install-dev Install development dependencies
check-code Run lint, type-check, unit-tests, and docstring check
lint Run linter
format Fix lint issues and format code
type-check Run type checker
unit-tests Run unit tests
unit-tests-cov Run unit tests with coverage
integration-tests Run integration tests
integration-tests-cov Run integration tests with coverage
check-async-docstrings Check async client docstrings
fix-async-docstrings Fix async client docstrings
build-docs Build documentation website
run-docs Run documentation website locally
build Build package
clean Remove build artifacts and clean caches

Dependencies

To install this package and its development dependencies, run:

uv run poe install-dev

Code checking

To execute all code checking tools together, run:

uv run poe check-code

Linting

We utilize ruff for linting, which analyzes code for potential issues and enforces consistent style. Refer to pyproject.toml for configuration details.

To run linting:

uv run poe lint

Formatting

Our automated code formatting also leverages ruff, ensuring uniform style and addressing fixable linting issues. Configuration specifics are outlined in pyproject.toml.

To run formatting:

uv run poe format

Type checking

Type checking is handled by ty, verifying code against type annotations. Configuration settings can be found in pyproject.toml.

To run type checking:

uv run poe type-check

Unit tests

We use pytest as a testing framework with many plugins. Check pyproject.toml for configuration details and installed plugins.

To run unit tests:

uv run poe unit-tests

To run unit tests with XML coverage report:

uv run poe unit-tests-cov

Integration tests

We have integration tests which interact with the Apify platform.

Prerequisites:

  • Set APIFY_TEST_USER_API_TOKEN to your Apify API token
  • Set APIFY_TEST_USER_2_API_TOKEN for storage access tests (requires two accounts)
  • Optionally set APIFY_INTEGRATION_TESTS_API_URL to use a different Apify API environment

To run integration tests:

uv run poe integration-tests

Documentation

We adhere to the Google docstring format for documenting our codebase. Every user-facing class or method is documented. Documentation standards are enforced using Ruff.

Our API documentation is generated from these docstrings using pydoc-markdown with additional post-processing. Markdown files in the docs/ folder complement the autogenerated content. Final documentation is rendered using Docusaurus and published to GitHub Pages.

To run the documentation locally (requires Node.js):

uv run poe run-docs

Commits

We use Conventional Commits format for commit messages. This convention is used to automatically determine version bumps during the release process.

Available commit types

Type Description
feat A new feature
fix A bug fix
docs Documentation only changes
style Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
refactor A code change that neither fixes a bug nor adds a feature
perf A code change that improves performance
test Adding missing tests or correcting existing tests
build Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
ci Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
chore Other changes that don't modify src or test files
revert Reverts a previous commit

Release process

Publishing new versions to PyPI is automated through GitHub Actions.

  • Beta releases: On each commit to the master branch, a new beta release is automatically published. The version number is determined based on the latest release and conventional commits. The beta version suffix is incremented by 1 from the last beta release on PyPI.
  • Stable releases: A stable version release may be created by triggering the release GitHub Actions workflow. The version number is determined based on the latest release and conventional commits (auto release type), or it may be overridden using the custom release type.

Publishing to PyPI manually

  1. Do not do this unless absolutely necessary. In all conceivable scenarios, you should use the release workflow instead.

  2. Make sure you know what you're doing.

  3. Update the version number:

  • Modify the version field under project in pyproject.toml.
[project]
name = "apify_client"
version = "x.z.y"
  1. Build the package:
uv run poe build
  1. Upload to PyPI:
uv publish --token YOUR_API_TOKEN