# Development Guide for Contributing to Stravalib ```{note} * Please make sure that you've read our [contributing guide](how-to-contribute.md) before reading this guide. * If you are looking for information on our package build structure and release workflow, please see our build and [release guide](build-release-guide) ``` The steps to get started with contributing to stravalib are below. To begin, fork and clone the [stravalib GitHub repository](https://github.com/stravalib/stravalib). ## Fork and clone the stravalib repository ### 1. Fork the repository on GitHub To create your own copy of the stravalib repository on GitHub, navigate to the [stravalib/stravalib](https://github.com/stravalib/stravalib) repository and click the **Fork** button in the top-right corner of the page. ### 2. Clone your fork locally Next, use `git clone` to create a local copy of your stravalib forked repository on your local filesystem: ```bash $ git clone git@github.com:your_name_here/stravalib.git $ cd stravalib/ ``` Once you have cloned your forked repository locally, you are ready to create a development environment. ## Setup a local development environment We suggest you create a virtual environment on your computer to work on `stravalib`. ::::{tab-set} ::: {tab-item} venv Follow these instructions if you prefer using `venv` to create virtual environments. To begin, create a new virtual environment in the project directory. This will create a local environment directory called `stravalib_env`: ```bash $ python -m venv stravalib_env ``` Next, activate the environment. On macOS and Linux: ```bash $ source stravalib_dev_env/bin/activate ``` On Windows: ```bash $ .\stravalib_dev_env\Scripts\activate ``` ::: ::: {tab-item} Conda If you prefer Conda for environment management, use the instructions below. Anaconda and Miniconda are two commonly-used conda Python distributions. If you are unsure of which distribution to use, [we suggest miniconda](https://docs.conda.io/en/latest/miniconda.html) as it is a lighter-weight installation. To begin, create a new `conda` environment called `stravalib_dev`. ```bash $ conda env create -f environment.yml ``` Next, activate the environment. ``` $ conda activate stravalib_dev ``` ::: :::: Once you have a virtual environment created, you are ready to install stravalib's package dependencies and the `stravalib` package in editable mode (`-e`). Editable mode allows you to update the package and test those updates in real-time. ```bash # Install the package in editable model and all requirements $ pip install -e ".[build, tests, docs]" ``` :::{note} If you only want to install dependencies for building and testing the package (and exclude the docs requirements), you can run: `pip install -e ".[build, tests]"` Quotes around `".[build, tests]"` are required for some shells such as `zsh` but not for all shells. ::: (ci_api_updates)= ## Architecture Overview ![Stravalib Architecture](../images/stravalib_architecture.png) Stravalib contains the following main components: At the core, a (pydantic) domain model is generated and updated by a bot via pull requests. This model reflects the officially published API specification by Strava and is stored in the module `strava_model.py`. This file should never be edited manually. Instead, the stravalib bot will suggest changes to the model through pull requests that can then be merged by stravalib maintainers. The module `model.py` contains classes that inherit from the official Strava domain model in `strava_model.py`. This module supports custom typing, unit conversion, (de-)serialization behavior, and support for undocumented Strava features. The module `protocol.py` manages the sending of HTTP requests to Strava and handling the received responses (including rate limiting). It is used by methods in `client.py` to de-serialize raw response data into the domain entities in `model.py`. ## Python support We loosely follow the [Numpy guidelines defined in NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html) for Python version support. However, in some cases, we may decide to support older versions of Python, following community demand. ## Code style, linting & typing We use several tools to maintain consistent code formatting and adhere to the [Python Enhancement Protocol (PEP) 8](https://peps.python.org/pep-0008/) standards, which outline best practices for Python code readability and structure. Below are the primary tools configured for this project: - [black](https://black.readthedocs.io/en/stable/): An auto-formatter that enforces consistent code style. Although Black’s default line length is 88 characters, we configure it to 79 characters to better align with [PEP 8 line width guidelines](https://peps.python.org/pep-0008/#maximum-line-length). - [ruff](https://github.com/charliermarsh/ruff): A fast, all-in-one Python linter that covers many functions formerly provided by separate tools like `flake8` and `isort`. Ruff performs both linting and import sorting, identifying unused imports, variables, and other PEP 8 inconsistencies. - [codespell](https://github.com/codespell-project/codespell): A spelling checker for code comments and documentation, helping to catch typos in Python, Markdown, and RST files. - [blacken-docs](https://github.com/adamchainz/blacken-docs): A tool for applying Black’s formatting to Python code blocks, ensuring consistent code style in documentation. ### Pre-commit Hook Setup For local development, we use [`pre-commit`](https://pre-commit.com/), which automatically runs each code format and linting tool configured in the `pre-commit-config.yaml` file. Once installed, `pre-commit` will execute each tool in the configuration file every time you make a commit. With pre-commit hooks setup, here’s what happens when you make a new commit to our codebase: 1. **black**: Automatically formats code to meet style guidelines. If the formatting is incorrect, `black` will reformat it for you. 2. **ruff**: Runs linting checks and fixes minor issues automatically, including sorting imports. 3. **codespell**: Identifies typos in code comments and documentation. You will need to fix these manually. 4. **blacken-docs**: Blacken docs will format any code snippets provided in our documentation to match Black's guidelines above If issues are found that cannot be automatically corrected, you’ll see a list of errors that need to be addressed before proceeding with your commit. ### Setup and run the pre-commit hooks The configuration for all of the pre-commit hooks is found in the **.pre-commit-config.yaml** file. To set up our pre-commit hooks locally: 1. First, make sure that pre-commit is installed. You can install pre-commit using `pip` or `pipx`. ```bash $ pip install pre-commit ``` Next, install all of the hooks into your stravalib development environment. ```bash $ pre-commit install ``` :::{tip} You can run all pre-commit hooks locally without a commit by using: ```bash $ pre-commit run --all-files ``` You can also run a single hook using the following: ``` # Only run ruff # pre-commit run ruff ``` ::: ### Pre-commit.ci bot We use the `https://pre-commit.ci` bot, in addition to pre-commit in our local build to manage pull requests. The configuration for this bot can be found in the ci: section of the `pre-commit-config.yaml` file. This bot can run all of the code format hooks on every pull request if it's set to do so. Currently, we have the bot set to run only when it's asked to run on a PR. To call the bot on a pull request, add the text: `pre-commit.ci run` as a single-line comment in the pull request. The bot will automatically run all of the hooks that it is configured to run. ```{tip} If you have an open Pull Request but you need to make some changes locally, and the bot has already run on your pull request and added a commit, you can force push to the pull request to avoid multiple bot commits. To do this: * Do not pull down any changes from the pull request, * Commit your changes locally, When you are ready to push your local changes use: `git push origin branch-name-here --force` If you have not yet pulled down pre-commit bot's changes, this will force the branch to be in the same commit state as your local branch. ``` ### Typing using mypy We use [mypy](https://mypy.readthedocs.io/) to ensure proper typing throughout our library. To run `mypy` across Python versions, use: `nox -s mypy` Similar to running tests, if you are missing a version of Python, `nox` will skip that run and continue to the next version. ```bash ❯ nox -s mypy nox > Running session mypy-3.10 nox > Missing interpreters will error by default on CI systems. nox > Session mypy-3.10 skipped: Python interpreter 3.10 not found. nox > Running session mypy-3.11 ``` ## Code format and syntax If you are contributing code to `stravalib`, please be sure to follow PEP 8 syntax best practices. ### Docstrings **All docstrings** should follow the [numpy style guide](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard). All functions/classes/methods should have docstrings with a full description of all arguments and return values. ```{warning} This also will be updated once we implement a code styler While the maximum line length for code is automatically set by *Black*, docstrings must be formatted manually. To play nicely with Jupyter and IPython, **limit docstrings to 79 characters** per line. ``` ## About the stravalib test suite Stravalib has a set of unit and integration tests that can be run locally and that also run in our CI infrastructure using GitHub Actions. To avoid direct API calls which require authentication, when running our test suite, we have a mock fixture and and infrastructure setup. ### Unit and integration test suite We have set up the test suite to run on the stravalib package as installed. Thus, when running your tests, it is critical that you have a stravalib development environment setup and activated with the stravalib package installed from your fork using pip `pip install .` You can run the tests using make as specified below. Note that when you run the tests this way, they will run in a temporary environment to ensure that they are running against the installed version of the package that you are working on. To run the test suite across all Python versions that we support use: ``` nox -s tests ``` `nox -s tests` does a few things: 1. It creates a temporary directory called `tmp-test-dir-stravalib` in which your tests are run. We create this test directory to ensure that tests are being run against the installed version of stravalib (with the most recent local development changes as installed) rather than the flat files located in the GitHub repository. 2. It runs the tests and provides output (see below) 3. Finally it removes the temporary directory To run tests for a specific Python version use: `nox -s tests-python-version-here`. For example, the command below runs our tests on Python 3.10 only. ```bash nox -s tests-3.10 ``` ### Test code coverage We use [pytest-cov](https://pytest-cov.readthedocs.io/en/latest/) to calculate test coverage. When you run `nox -s tests` pytest-cov will provide you with coverage outputs locally. You can ignore the returned values for any files in the `test` directory. Example output from `nox -s test`: ```bash pytest --cov stravalib stravalib/tests/unit stravalib/tests/integration =================================================== test session starts =================================================== platform darwin -- Python 3.8.13, pytest-7.2.0, pluggy-1.0.0 rootdir: .../stravalib plugins: cov-4.0.0 collected 105 items stravalib/tests/unit/test_attributes.py ............... [ 14%] stravalib/tests/unit/test_client_utils.py ....... [ 20%] stravalib/tests/unit/test_limiter.py ............. [ 33%] stravalib/tests/unit/test_model.py ....... [ 40%] stravalib/tests/integration/test_client.py ............................................................... [100%] ---------- coverage: platform darwin, python 3.8.13-final-0 ---------- Name Stmts Miss Cover ---------------------------------------------------------------------------- stravalib/__init__.py 2 0 100% stravalib/_version.py 2 0 100% stravalib/_version_generated.py 2 0 100% stravalib/attributes.py 170 19 89% stravalib/client.py 439 180 59% stravalib/exc.py 34 3 91% stravalib/model.py 709 126 82% stravalib/protocol.py 130 39 70% stravalib/unit_helper.py 16 1 94% stravalib/util/__init__.py 0 0 100% stravalib/util/limiter.py 122 27 78% ---------------------------------------------------------------------------- TOTAL ``` ### Code coverage reporting on pull requests with codecov We use an integration with [codecov.io](https://about.codecov.io) to report test coverage changes on every pull request. This report will appear in your pull request once all of the GitHub action checks have run. ```{note} The actual code coverage report is uploaded on the GitHub action run on `ubuntu` and `Python 3.11`. When that step in the actions completes, the report will be processed and returned to the pull request. ``` ## Tests & the stravalib mock fixture To run integration tests that ensure stravalib is interacting with API data correctly, Stravalib uses a mock object accessed through a `pytest` fixture `stravalib.tests.integration.strava_api_stub.StravaAPIMock` that is based on `responses.RequestsMock`. This fixture adds a mock that prevents requests from being made to the Strava API. Instead, it creates responses using the endpoint provided and the `swagger.json` file that is found both online and within the `stravalib/src/stravalib/tests/resources/` directory that are based on examples from the published Strava API documentation. :::{tip} Example usages of this fixture can be found in the {py:mod}`stravalib.tests.integration.test_client` module. ::: :::{mermaid} flowchart TD A["fab:fa-strava Stravalib Test Suite"] --> C["**mock_strava_api fixture**
(defined in conftest)"] C -- Creates instance of --> D["**StravaAPIMock**
strava_api_stub.py module
Inherits from responses.RequestsMock"] D -- Returns fake response data using: --> G["**swagger.json**
(local or online)"] style C color:#FFFFFF, stroke:#00C853, fill:#AA00FF style G color:#FFFFFF, fill:#d35400, stroke:#AA00FF style A color:#FFFFFF, fill:#d35400, stroke:#AA00FF ::: ### How the mock fixture works The `stravalib` test suite is supported by the {py:class}`stravalib.tests.integration.strava_api_stub.StravaAPIMock` mock API object, which is used in most client GET method tests through a `pytest` fixture. The Strava API mock object: 1. **Matches Endpoints**: Attempts to match the endpoint being tested with a corresponding path in `swagger.json`, using either an online or local copy. This mock expects a relative URL that aligns with a path in the `swagger.json` file (e.g., `/activities/{Id}`) and includes the appropriate HTTP method and status code. 2. **Provides Example Responses**: Retrieves the example JSON response associated with the matched endpoint in `swagger.json` and uses it as the mock response body. The example response can be customized by using the `response_update` parameter, which accepts a dictionary of values to override fields in the default response. If the response is a JSON array, the `n_results` argument can specify how many objects to return. If the object can find an endpoint match, it then returns the example JSON response (or the updated response if you use the update parameter) to use in the test. :::{tip} The `swagger.json` file is an API specification document describing the available endpoints in the Strava API, including methods, parameters, and expected responses for each endpoint. It defines the API structure in JSON format and includes example responses for testing. This file is used in `stravalib`'s tests to mock API interactions and validate the expected structure and content of responses. The mock API object checks if `swagger.json` is accessible online; if not, it uses a local version located in the `tests/resources` directory within `stravalib`. ::: ### Mock fixture features To call the mock fixture in a test, you 1. Create a new test and add the `mock_strava_api` fixture as an input to the test function. The test below will try to access the `/athlete/activities` Strava endpoint which returns an athlete's activities. Here, the fixture will bypass trying to access the real online API. And instead, will find the `/athlete/activities` endpoint in the Strava online or local `swagger.json` file. When you call {py:func}`stravalib.client.Client.get_activities()`, the mocked endpoint will return the sample data provided in the `swagger.json` file. ```python def test_example(mock_strava_api, client): """An example test""" mock_strava_api.get("/athlete/activities") activity_list = list(client.get_activities()) assert len(activity_list) == 4 ``` The mock fixture object provides parameters that allow you to modify a test. Sometimes you may want to update the default example return data in the swagger.json file. This might happen if you want to intentionally "break" a test to ensure that the client call responds appropriately. To modify the returned sample data use the `response_update` parameter. Below you update the response id key to be another value. ```python def test_example_test(mock_strava_api, client): """An example test""" mock_strava_api.get( "/athlete/activities", response_update={"id": 12345}, ) activity_list = list(client.get_activities()) ``` You can also specify the number of results that you'd like to see in the mock output using the `n_results` parameters. ```python def test_example_test(mock_strava_api, client): """An example test""" mock_strava_api.get( "/athlete/activities", response_update={"id": 12345}, n_results=4, ) activity_list = list(client.get_activities()) ``` :::{tip} Stravalib uses lazily loaded entities when returning results from endpoint such as activities that may include multiple response objects in the return. As such, a mocked call to {py:func}`stravalib.client.Client.get_activities` will not actually initiate a get response until you try to access the first object returned in the {py:class}`stravalib.client.BatchedResultsIterator` object. ::: ## Documentation `Stravalib` documentation is created using `sphinx` and the [`pydata_sphinx_theme`](https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html) theme. `Stravalib` documentation is hosted on [ReadtheDocs](https://readthedocs.org). The final online build that you see on readthedocs happens on the readthedocs website. Our continuous integration GitHub action only tests that the documentation builds correctly. It also tests for broken links. The readthedocs build is configured using the `.readthedocs.yml` file rather than from within the readthedocs interface as recommended by the readthedocs website. The badge below (also on our `README.md` file) tells you whether the readthedocs build is passing or failing. [![Documentation Status](https://readthedocs.org/projects/stravalib/badge/?version=latest)](https://stravalib.readthedocs.io/en/latest/?badge=latest) Currently [@hozn](https://www.github.com/hozn), [@lwasser](https://www.github.com/lwasser) and [@jsamoocha](https://www.github.com/jsamoocha) have access to the readthedocs `stravalib` documentation build Online documentation will be updated on all merges to the main branch of `stravalib`. ### Build documentation locally To build the documentation, first activate your stravalib development environment which has all of the packages required to build the documentation. Then, use the command: ```bash $ nox -s docs ``` This command: - Builds documentation - Builds `stravalib` API reference documentation using docstrings within the package - Checks for broken links After running `nox -s docs` you can view the built documentation in a web browser locally by opening the following file on your computer: ``` /your-path-to-stravalib-dir/stravalib/docs/_build/html/index.html ``` You can also view any broken links in the output.txt file located here: `/your-path-to-stravalib-dir/stravalib/docs/_build/linkcheck/output.txt` ### Build locally with a live server We use `sphinx-autobuild` to build the documentation in a live web server. This allows you to see your edits automatically as you are working on the text files of the documentation. To run the live server use: ```bash $ nox -s docs-live ``` ```{note} There is a quirk with autobuild where included files such as the CHANGELOG will not update live in your local rendered build until you update content on a file without included content. ``` ### Stravalib API Documentation The API reference can be found [here](reference). The *autodoc* sphinx extension will automatically create pages for each function/class/module listed there. You can reference classes, functions, and modules from anywhere (including docstrings) using * {py:func}\`package.module.function\`, * {py:func}\`package.module.Class.method\`, * {py:class}\`package.module.class\`, or * {py:mod}\`package.module\`. Sphinx will create a link to the automatically generated page for that function/class/module. ### About the documentation CI build Once you create a pull request, GitHub actions will build the docs and check for any syntax or url errors. Once the PR is approved and merged into the main branch of the `stravalib/stravalib` repository, the docs will build and be [available at the readthedocs website](https://stravalib.readthedocs.io/en/latest/). ### Cleanup of documentation and package build files To clean up all documentation build folders and files, run the following command from the root of the `stravalib` directory: ```bash $ nox -s clean-docs ``` To clean up build files such as the package **.whl**, and other temporary files created when building `stravalib` distributions and running tests, run: ```bash $ nox -s clean_build ```