Danny Cunningham π π€ |
Hugo van Kemenade π» π |
Jerome Lelong π |
Jonatan Samoocha π» π π π§ |
Leah Wasser π» π π |
Robert Kosara π π¬ |
Yotam π |
Γmile Nadeau π» π π π§ |
{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
```
stravalib-2.3/docs/contributing/how-to-contribute.md 0000664 0000000 0000000 00000000044 14763424141 0022723 0 ustar 00root root 0000000 0000000
```{include} ../../CONTRIBUTING.md
stravalib-2.3/docs/contributing/inheritance.md 0000664 0000000 0000000 00000007433 14763424141 0021634 0 ustar 00root root 0000000 0000000 # Stravalib's Inheritance Patterns
Stravalib's API is built directly from Strava's `swagger.json` example response
data. We use the Pydantic `BaseModel` combined with `datacodegen` to build our
base model objects (found in `strava_model.py`), which we then enhance and
update to align with the data actually returned by the Strava API.
This page will help you understand Stravalib's inheritance patterns.
In our experience maintaining Stravalib, the Strava API online specification
and the `swagger.json` file don't always align perfectly with the data actually
returned by Strava. As a result, you will notice that we frequently overwrite
data types to match the actual data we see returned from the Strava API for
each endpoint. [More information on this process can be found here.](ci_api_updates)
Below, we present the inheritance schema for Stravalib.
## Inheritance overview
At a high level, there are two modules:
* {py:mod}`stravalib.model` and
* {py:mod}`stravalib.strava_model`.
`strava_model` is generated automatically using a CI build from the Strava API.
Stravalib uses the model.py module to do a few things:
1. It supports inheritance of the {py:class}`stravalib.model.BoundClientEntity`, which supports API calls for lazily loaded properties,
2. it allows us to override {py:mod}`stravalib.strava_model` attributes that have typed attributes that don't align with the actual API responses, and
3. allows us to add attributes that are found in the returned data but not documented or found in the swagger.json response.
The full inheritance pattern, which includes inheritance from both `strava_model` and `pydantic.BaseModel`, is below.
### Inheritance diagram showing the relationship between strava_model.py and model.py
:::{mermaid}
classDiagram
direction BT
%% Activities in model namespace
`model.MetaActivity` --|> `model.BoundClientEntity`
`model.SummaryActivity` --|> `model.MetaActivity`
`model.DetailedActivity` --|> `model.SummaryActivity`
%% Activities in strava_model namespace
`strava_model.SummaryActivity` --|> `strava_model.MetaActivity`
`strava_model.DetailedActivity` --|> `strava_model.SummaryActivity`
%% Define inheritance relationships between model and strava_model
`model.MetaActivity` --|> `strava_model.MetaActivity`
`model.SummaryActivity` --|> `strava_model.SummaryActivity`
`model.DetailedActivity` --|> `strava_model.DetailedActivity`
:::
## Model object inheritance patterns
The {py:mod}`stravalib.model` module contains core objects that inherit
from and modify objects in {py:mod}`strava_model.py`. The `strava_model.py`
file is generated directly from the Strava `swagger.json` API response.
Our main client class provides methods for making API `GET` and `PUT`
requests. To support these requests and enable lazily loaded operations, all
Strava model meta-level objects inherit from `BoundClientEntity`, which stores the token
credentials needed for authenticated API calls. This ensures that summary and detailed-level objects can also support lazily loaded operations.
### Inheritance diagram showing the relationship between Detailed, Summary and Meta classes and BoundClientEntity
:::{mermaid}
classDiagram
direction BT
%% Activities
MetaActivity --|> BoundClientEntity
SummaryActivity --|> MetaActivity
DetailedActivity --|> SummaryActivity
%% Athletes
MetaAthlete --|> BoundClientEntity
SummaryAthlete --|> MetaAthlete
DetailedAthlete --|> SummaryAthlete
%% Clubs
MetaClub --|> BoundClientEntity
SummaryClub --|> MetaClub
DetailedClub --|> SummaryClub
:::
stravalib-2.3/docs/contributing/intro.md 0000664 0000000 0000000 00000002343 14763424141 0020471 0 ustar 00root root 0000000 0000000 # Contribute to stravalib
We welcome contributions of all kinds to stravalib! Below are
some resources to help you get started.
::::{grid} 1 1 1 2
:class-container: text-center
:gutter: 3
:::{grid-item-card}
:link: how-to-contribute
:link-type: doc
β¨ **Contributing Guide** β¨
^^^
Contributing guidelines for stravalib.
:::
:::{grid-item-card}
:link: development-guide
:link-type: doc
β¨ **Development Guide** β¨
^^^
Learn about our development infrastructure and workflows.
:::
:::{grid-item-card}
:link: build-release-guide
:link-type: doc
β¨ **Build & Release Guide** β¨
^^^
Learn about our build and release workflow. We use version control based versioning.
:::
:::{grid-item-card}
:link: resources-for-new-contributors
:link-type: doc
β¨ **Contributor Resources** β¨
^^^
If you are new to contributing to open source software, these resources will help you get started.
:::
:::{toctree}
:hidden:
:caption: Contributing
:maxdepth: 2
Contributing Guide <../contributing/how-to-contribute>
Development Guide <../contributing/development-guide>
Inheritance <../contributing/inheritance>
Build & Release Guide <../contributing/build-release-guide>
New Contributor Resources <../contributing/resources-for-new-contributors>
:::
stravalib-2.3/docs/contributing/resources-for-new-contributors.md 0000664 0000000 0000000 00000002510 14763424141 0025452 0 ustar 00root root 0000000 0000000 # Contributor resources
## Contributing Code
**Is this your first contribution?**
Please take a look at these resources to learn about git and pull requests (don't
hesitate to ask questions:
* [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/).
* Aaron Meurer's [tutorial on the git workflow](https://www.asmeurer.com/git-workflow/)
* [How to Contribute to an Open Source Project on GitHub](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github)
If you're new to working with git, GitHub, and the Unix Shell, we recommend
starting with the [Software Carpentry](https://software-carpentry.org/) lessons,
which are available in English and Spanish:
* [Version Control with Git](https://swcarpentry.github.io/git-novice/) / spanish: [Control de
versiones con Git](https://swcarpentry.github.io/git-novice-es/)
* [The Unix Shell](https://swcarpentry.github.io/shell-novice/) / spanish:
[La Terminal de Unix](https://swcarpentry.github.io/shell-novice-es/)
## Additional contribution resources
For more information on contributing to open source projects, checkout:
* [GitHub's contribution guide](https://docs.github.com/en)
is a great starting point if you are new to version control.
* The [Zen of Scientific Software Maintenance](https://jrleeman.github.io/ScientificSoftwareMaintenance/)
stravalib-2.3/docs/get-started/ 0000775 0000000 0000000 00000000000 14763424141 0016526 5 ustar 00root root 0000000 0000000 stravalib-2.3/docs/get-started/activities.md 0000664 0000000 0000000 00000021031 14763424141 0021211 0 ustar 00root root 0000000 0000000 (activities)=
# Get Strava activity data
This page overviews working with your Strava activity data using the stravalib Python library.
## Retrieve an activity
To access data for a given activity, use the `client.get_activity` method and provide the `activity_id`.
The `client.get_activity` method returns a {py:class}`stravalib.model.DetailedActivity` object.
:::{note}
All of the commands below require you first to authenticate using a client object containing a token.
`from stravalib.client import Client`
:::
```{code-block} pycon
# This command assumes that you have already authenticated the client object.
>>> activity = client.get_activity(1234)
>>> type(activity)