zpdatafetch 2.3.2__tar.gz → 2.4.1__tar.gz

{zpdatafetch-2.3.2/src/zpdatafetch.egg-info → zpdatafetch-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zpdatafetch
-Version: 2.3.2
+Version: 2.4.1
 Summary: A package for fetching data from Zwiftpower and Zwiftracing.app
 Author-email: Doug Morris <doug@mhost.com>
 License-Expression: MIT
@@ -58,7 +58,7 @@ This package provides four command-line tools:
 | Tool         | API          | Purpose                                    | Data Types                                                |
 | ------------ | ------------ | ------------------------------------------ | --------------------------------------------------------- |
 | **`zpdata`** | ZwiftPower   | Race rankings, signups, results            | Cyclist, Primes, Results, Signups, Sprints, Teams, League |
-| **`zrdata`** | Zwiftracing  | Rider ratings, race results, rosters       | Rider Ratings, Race Results, Team Rosters                 |
+| **`zrdata`** | Zwiftracing  | Rider ratings, race results, rosters       | Rider Ratings, Race Results, Team Rosters, Category Ranges |
 | **`zdata`**  | Zwift        | Profiles, followers, activities, worlds    | Profile, Followers, RideOns, Activity, Worlds, Riders     |
 | **`zsdata`** | Zwift Status | Service status, incidents, maintenance     | Summary, Components, Incidents, Maintenance               |
 
@@ -77,7 +77,7 @@ required).
 - **Primes** - Prime results for Fastest Through Segment (FTS) and First Across the Line (FAL)
 - **Sprints** - Sprint data including sprint details and positions
 - **Team data** - Team rosters and member information
-- **League data** - League standings and Zwift Racing Score (ZRS) information
+- **League data** - League standings, events, team standings, and league metadata (name, categories, contact)
 
 ### For zrdata (Zwiftracing)
 
@@ -312,7 +312,25 @@ available classes are as follows:
 - Signup: fetch signups for a particular event by event id
 - Sprints: fetch sprints from one or more races using event id
 - Team: fetch team data by team id
-- League: fetch league standings by league id
+- League: fetch league standings, events, team standings, team-event results and metadata by league id
+
+**League data example:**
+
+```python
+from zpdatafetch import ZPLeagueFetch
+
+lf = ZPLeagueFetch()
+league = lf.fetch(3379)[3379]
+
+league.info()                 # ZPLeagueInfo: name, contact, categories, ...
+league.events()               # list[ZPLeagueEvent]: event_id, title, start_datetime
+league.team_standings()       # list[ZPLeagueTeamStanding]
+league.team_event_results()   # list[ZPLeagueTeamEventResult]
+print(league.json())          # all collections as JSON (keys omitted when empty)
+```
+
+Each source is fetched independently: a league without a standings file (e.g.
+3388) still returns its events and metadata, and vice versa.
 
 ## Zwiftracing Data (zrdata)
 
@@ -322,30 +340,39 @@ including rider ratings, race results, and team rosters.
 ### Command-line usage
 
 ```sh
-usage: zrdata [-h] [-v] [-vv] [--log-file PATH] [-r] [--v1fetch] [--noaction] [--sync]
+usage: zrdata [-h] [--version] [-v] [-vv] [--log-file PATH] [-r] [--json]
+              [--noaction] [--sync] [--extras] [--excluded] [--v1fetch]
               [--batch] [--batch-file FILE] [--premium] [--at DATETIME]
-              [{config,rider,result,team}] [id ...]
+              [CMD] [id ...]
 
 Module for fetching Zwiftracing data using the Zwiftracing API
 
 positional arguments:
-  {config,rider,result,team}
-                        which command to run
-  id                    the id to search for
+  CMD                command to execute: {config,rider,result,team,categories}
+  id                 ID(s) for the command
 
 options:
-  -h, --help            show this help message and exit
-  -v, --verbose         enable INFO level logging to console
-  -vv, --debug          enable DEBUG level logging to console
-  --log-file PATH       path to log file (enables file logging)
-  -r, --raw             print the raw response text from the server
-  --v1fetch             output fetched data in v1.8 format (backward compatibility)
-  --noaction            report what would be done without actually fetching data
-  --sync                use synchronous (non-parallel) requests for debugging
-  --batch               use batch POST endpoint for multiple IDs (rider command only)
-  --batch-file FILE     read IDs from file (one per line) for batch request (rider command only)
-  --premium             use premium tier rate limits (higher request quotas)
-  --at DATETIME         fetch historical ratings at a date/time in UTC (rider command only)
+  -h, --help         show this help message and exit
+  --version          show program's version number and exit
+  -v, --verbose      enable verbose output (INFO level logging)
+  -vv, --debug       enable debug output (DEBUG level logging)
+  --log-file PATH    write logging output to file
+  -r, --raw          print raw result data as received from the server
+  --json             output fetched data as JSON (default: object repr)
+  --noaction         show what would be done without actually fetching data
+  --sync             use synchronous (non-parallel) requests
+  --extras           report recently added fields not handled natively
+  --excluded         report recognized fields not yet explicitly handled
+  --v1fetch          output fetched data in v1.8 format (for backward
+                     compatibility)
+  --batch            use batch POST endpoint for multiple IDs (rider command
+                     only)
+  --batch-file FILE  read IDs from file (one per line) for batch request
+                     (rider command only)
+  --premium          use premium tier rate limits (higher request quotas)
+  --at DATETIME      fetch historical ratings at a given date/time (UTC), e.g.
+                     '2024-06-15' or '2024-06-15T14:30:00' (rider command
+                     only)
 ```
 
 **Note:** All objects support both synchronous (`fetch()`) and asynchronous (`afetch()`) methods. See the Async API section below for details.
@@ -371,6 +398,9 @@ zrdata result 3590800
 # Fetch team roster
 zrdata team 456
 
+# Fetch vELO2 category ranges
+zrdata categories
+
 # View current configuration
 zrdata config
 
@@ -378,6 +408,50 @@ zrdata config
 zrdata config  # Will prompt for authorization header
 ```
 
+### Category Ranges (vELO2)
+
+Fetch the vELO2 category ranges used to bucket riders by rating:
+
+```sh
+zrdata categories
+# Output: the full repr — every entry with number, name, and range:
+# ZRCategories(scale='1-1000', categories=[ZRvELOCategory(
+# number=1, name='Diamond', min=920, max=None), ZRvELOCategory(
+# number=2, name='Ruby', min=840, max=919), ...])
+```
+
+Use `--json` for the full mapping:
+
+```sh
+zrdata categories --json
+# Output:
+# {
+#   "scale": "1-1000",
+#   "categories": [
+#     {"number": 1, "name": "Diamond", "min": 920, "max": null},
+#     {"number": 2, "name": "Ruby", "min": 840, "max": 919},
+#     ...
+#     {"number": 10, "name": "Copper", "min": 0, "max": 359}
+#   ]
+# }
+```
+
+`--raw` prints the unmodified API response; `--noaction` previews the fetch.
+
+```python
+# Library usage
+from zrdatafetch import ZRCategoriesFetch
+
+categories = ZRCategoriesFetch().fetch()
+for entry in categories:            # iterate in API order (0 = Diamond)
+    print(f"{entry.number}: {entry.name} {entry.min}-{entry.max}")
+
+silver = categories['Silver']       # lookup by exact name
+diamond = categories[0]             # positional access
+'Silver' in categories              # membership -> True
+len(categories)                     # 10
+```
+
 ### Historical Ratings
 
 Use `--at` to fetch rider ratings at a specific point in time. Accepts ISO 8601
@@ -1237,7 +1311,7 @@ profile = ZwiftProfile()
 profile.fetch(550564)
 print(profile.json())
 
-# Fetch followers
+# Fetch followers (all pages; the API paginates at 200 entries per page)
 followers = ZwiftFollowers()
 followers.fetch(550564)
 print(f"Followers: {followers.follower_count()}")
@@ -1251,7 +1325,15 @@ worlds = ZwiftWorlds()
 worlds.fetch()
 
 # Give a RideOn
+# rider_id = activity owner; your own id is resolved automatically
+# via GET /api/profiles/me and sent as {"profileId": <your id>}
 ZwiftRideOns.give_rideon(550564, 12345678)
+
+# Check who gave RideOns on an activity
+rideons = ZwiftRideOns()
+rideons.fetch(550564, 12345678)
+print(rideons.rideon_ids())             # rider IDs of RideOn givers
+print(rideons.has_rideon_from(766087))  # did this rider give a RideOn?
 ```
 
 ## Zwift Status Data (zsdata)

{zpdatafetch-2.3.2 → zpdatafetch-2.4.1}/README.md

@@ -29,7 +29,7 @@ This package provides four command-line tools:
 | Tool         | API          | Purpose                                    | Data Types                                                |
 | ------------ | ------------ | ------------------------------------------ | --------------------------------------------------------- |
 | **`zpdata`** | ZwiftPower   | Race rankings, signups, results            | Cyclist, Primes, Results, Signups, Sprints, Teams, League |
-| **`zrdata`** | Zwiftracing  | Rider ratings, race results, rosters       | Rider Ratings, Race Results, Team Rosters                 |
+| **`zrdata`** | Zwiftracing  | Rider ratings, race results, rosters       | Rider Ratings, Race Results, Team Rosters, Category Ranges |
 | **`zdata`**  | Zwift        | Profiles, followers, activities, worlds    | Profile, Followers, RideOns, Activity, Worlds, Riders     |
 | **`zsdata`** | Zwift Status | Service status, incidents, maintenance     | Summary, Components, Incidents, Maintenance               |
 
@@ -48,7 +48,7 @@ required).
 - **Primes** - Prime results for Fastest Through Segment (FTS) and First Across the Line (FAL)
 - **Sprints** - Sprint data including sprint details and positions
 - **Team data** - Team rosters and member information
-- **League data** - League standings and Zwift Racing Score (ZRS) information
+- **League data** - League standings, events, team standings, and league metadata (name, categories, contact)
 
 ### For zrdata (Zwiftracing)
 
@@ -283,7 +283,25 @@ available classes are as follows:
 - Signup: fetch signups for a particular event by event id
 - Sprints: fetch sprints from one or more races using event id
 - Team: fetch team data by team id
-- League: fetch league standings by league id
+- League: fetch league standings, events, team standings, team-event results and metadata by league id
+
+**League data example:**
+
+```python
+from zpdatafetch import ZPLeagueFetch
+
+lf = ZPLeagueFetch()
+league = lf.fetch(3379)[3379]
+
+league.info()                 # ZPLeagueInfo: name, contact, categories, ...
+league.events()               # list[ZPLeagueEvent]: event_id, title, start_datetime
+league.team_standings()       # list[ZPLeagueTeamStanding]
+league.team_event_results()   # list[ZPLeagueTeamEventResult]
+print(league.json())          # all collections as JSON (keys omitted when empty)
+```
+
+Each source is fetched independently: a league without a standings file (e.g.
+3388) still returns its events and metadata, and vice versa.
 
 ## Zwiftracing Data (zrdata)
 
@@ -293,30 +311,39 @@ including rider ratings, race results, and team rosters.
 ### Command-line usage
 
 ```sh
-usage: zrdata [-h] [-v] [-vv] [--log-file PATH] [-r] [--v1fetch] [--noaction] [--sync]
+usage: zrdata [-h] [--version] [-v] [-vv] [--log-file PATH] [-r] [--json]
+              [--noaction] [--sync] [--extras] [--excluded] [--v1fetch]
               [--batch] [--batch-file FILE] [--premium] [--at DATETIME]
-              [{config,rider,result,team}] [id ...]
+              [CMD] [id ...]
 
 Module for fetching Zwiftracing data using the Zwiftracing API
 
 positional arguments:
-  {config,rider,result,team}
-                        which command to run
-  id                    the id to search for
+  CMD                command to execute: {config,rider,result,team,categories}
+  id                 ID(s) for the command
 
 options:
-  -h, --help            show this help message and exit
-  -v, --verbose         enable INFO level logging to console
-  -vv, --debug          enable DEBUG level logging to console
-  --log-file PATH       path to log file (enables file logging)
-  -r, --raw             print the raw response text from the server
-  --v1fetch             output fetched data in v1.8 format (backward compatibility)
-  --noaction            report what would be done without actually fetching data
-  --sync                use synchronous (non-parallel) requests for debugging
-  --batch               use batch POST endpoint for multiple IDs (rider command only)
-  --batch-file FILE     read IDs from file (one per line) for batch request (rider command only)
-  --premium             use premium tier rate limits (higher request quotas)
-  --at DATETIME         fetch historical ratings at a date/time in UTC (rider command only)
+  -h, --help         show this help message and exit
+  --version          show program's version number and exit
+  -v, --verbose      enable verbose output (INFO level logging)
+  -vv, --debug       enable debug output (DEBUG level logging)
+  --log-file PATH    write logging output to file
+  -r, --raw          print raw result data as received from the server
+  --json             output fetched data as JSON (default: object repr)
+  --noaction         show what would be done without actually fetching data
+  --sync             use synchronous (non-parallel) requests
+  --extras           report recently added fields not handled natively
+  --excluded         report recognized fields not yet explicitly handled
+  --v1fetch          output fetched data in v1.8 format (for backward
+                     compatibility)
+  --batch            use batch POST endpoint for multiple IDs (rider command
+                     only)
+  --batch-file FILE  read IDs from file (one per line) for batch request
+                     (rider command only)
+  --premium          use premium tier rate limits (higher request quotas)
+  --at DATETIME      fetch historical ratings at a given date/time (UTC), e.g.
+                     '2024-06-15' or '2024-06-15T14:30:00' (rider command
+                     only)
 ```
 
 **Note:** All objects support both synchronous (`fetch()`) and asynchronous (`afetch()`) methods. See the Async API section below for details.
@@ -342,6 +369,9 @@ zrdata result 3590800
 # Fetch team roster
 zrdata team 456
 
+# Fetch vELO2 category ranges
+zrdata categories
+
 # View current configuration
 zrdata config
 
@@ -349,6 +379,50 @@ zrdata config
 zrdata config  # Will prompt for authorization header
 ```
 
+### Category Ranges (vELO2)
+
+Fetch the vELO2 category ranges used to bucket riders by rating:
+
+```sh
+zrdata categories
+# Output: the full repr — every entry with number, name, and range:
+# ZRCategories(scale='1-1000', categories=[ZRvELOCategory(
+# number=1, name='Diamond', min=920, max=None), ZRvELOCategory(
+# number=2, name='Ruby', min=840, max=919), ...])
+```
+
+Use `--json` for the full mapping:
+
+```sh
+zrdata categories --json
+# Output:
+# {
+#   "scale": "1-1000",
+#   "categories": [
+#     {"number": 1, "name": "Diamond", "min": 920, "max": null},
+#     {"number": 2, "name": "Ruby", "min": 840, "max": 919},
+#     ...
+#     {"number": 10, "name": "Copper", "min": 0, "max": 359}
+#   ]
+# }
+```
+
+`--raw` prints the unmodified API response; `--noaction` previews the fetch.
+
+```python
+# Library usage
+from zrdatafetch import ZRCategoriesFetch
+
+categories = ZRCategoriesFetch().fetch()
+for entry in categories:            # iterate in API order (0 = Diamond)
+    print(f"{entry.number}: {entry.name} {entry.min}-{entry.max}")
+
+silver = categories['Silver']       # lookup by exact name
+diamond = categories[0]             # positional access
+'Silver' in categories              # membership -> True
+len(categories)                     # 10
+```
+
 ### Historical Ratings
 
 Use `--at` to fetch rider ratings at a specific point in time. Accepts ISO 8601
@@ -1208,7 +1282,7 @@ profile = ZwiftProfile()
 profile.fetch(550564)
 print(profile.json())
 
-# Fetch followers
+# Fetch followers (all pages; the API paginates at 200 entries per page)
 followers = ZwiftFollowers()
 followers.fetch(550564)
 print(f"Followers: {followers.follower_count()}")
@@ -1222,7 +1296,15 @@ worlds = ZwiftWorlds()
 worlds.fetch()
 
 # Give a RideOn
+# rider_id = activity owner; your own id is resolved automatically
+# via GET /api/profiles/me and sent as {"profileId": <your id>}
 ZwiftRideOns.give_rideon(550564, 12345678)
+
+# Check who gave RideOns on an activity
+rideons = ZwiftRideOns()
+rideons.fetch(550564, 12345678)
+print(rideons.rideon_ids())             # rider IDs of RideOn givers
+print(rideons.has_rideon_from(766087))  # did this rider give a RideOn?
 ```
 
 ## Zwift Status Data (zsdata)

{zpdatafetch-2.3.2 → zpdatafetch-2.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "zpdatafetch"
-version = "2.3.2"
+version = "2.4.1"
 description = "A package for fetching data from Zwiftpower and Zwiftracing.app"
 readme = "README.md"
 requires-python = ">=3.10"

{zpdatafetch-2.3.2 → zpdatafetch-2.4.1}/src/zdatafetch/followers.py

@@ -1,10 +1,13 @@
 """Zwift follower and followee data fetching and management.
 
 Provides access to follower/followee relationship data from Zwift's unofficial API.
+
+Both endpoints are server-paginated (200 entries per page); every page is
+collected so the complete follower/followee lists are returned.
 """
 
 import json
-from typing import Any
+from typing import Any, Literal
 
 import httpx2
 
@@ -16,6 +19,89 @@ from zdatafetch.logging_config import get_logger
 
 logger = get_logger(__name__)
 
+PAGE_SIZE = 200
+MAX_PAGES = 500
+
+
+def _fetch_paginated(
+  client: httpx2.Client,
+  url: str,
+  headers: dict[str, str],
+  rider_id: int,
+  kind: str,
+  mode: Literal['raise', 'partial'],
+) -> list[dict[str, Any]]:
+  """Fetch all pages of a followers/followees endpoint.
+
+  Zwift caps these endpoints at ``PAGE_SIZE`` entries per request. Each
+  request sends ``start``/``limit`` query parameters; pagination stops
+  when a page is empty or shorter than ``PAGE_SIZE``.
+
+  Args:
+      client: httpx2 client to request with
+      url: Endpoint URL (without start/limit parameters)
+      headers: Request headers
+      rider_id: Zwift rider ID (for logs and error messages)
+      kind: Endpoint label, 'followers' or 'followees'
+      mode: 'raise' raises NetworkError on a failed page; 'partial'
+          logs a warning and returns the pages collected so far
+
+  Returns:
+      Records merged across all fetched pages
+
+  Raises:
+      NetworkError: In 'raise' mode, if a page does not return 200
+  """
+  records: list[dict[str, Any]] = []
+  for page in range(MAX_PAGES):
+    start = page * PAGE_SIZE
+    response = client.get(
+      url,
+      headers=headers,
+      params={'start': start, 'limit': PAGE_SIZE},
+      timeout=30.0,
+    )
+
+    if response.status_code != 200:
+      if mode == 'raise':
+        if response.status_code == 404:
+          raise NetworkError(f'Rider {rider_id} not found')
+        raise NetworkError(
+          f'Failed to fetch {kind} for rider {rider_id}: '
+          f'HTTP {response.status_code} - {response.text}',
+        )
+      logger.warning(
+        f'Failed to fetch {kind} for rider {rider_id}: '
+        f'HTTP {response.status_code}',
+      )
+      break
+
+    page_records = parse_json_safe(response.text, context=kind)
+    if not isinstance(page_records, list):
+      logger.warning(
+        f'Unexpected payload for {kind} of rider {rider_id} '
+        f'at start={start}: expected list, '
+        f'got {type(page_records).__name__}',
+      )
+      break
+
+    records.extend(page_records)
+    logger.debug(
+      f'Fetched {kind} page for rider {rider_id} '
+      f'(start={start}): {len(page_records)} records',
+    )
+
+    if len(page_records) < PAGE_SIZE:
+      break
+  else:
+    logger.warning(
+      f'Pagination cap of {MAX_PAGES} pages reached for {kind} of '
+      f'rider {rider_id}: returning partial data '
+      f'({len(records)} records)',
+    )
+
+  return records
+
 
 class ZwiftFollowers:
   """Zwift follower and followee data.
@@ -27,6 +113,9 @@ class ZwiftFollowers:
       GET https://us-or-rly101.zwift.com/api/profiles/{riderId}/followers
       GET https://us-or-rly101.zwift.com/api/profiles/{riderId}/followees
 
+  Both endpoints are server-paginated (200 entries per page); fetch() and
+  fetch_multiple() collect every page so the complete lists are returned.
+
   Documentation: https://github.com/strukturunion-mmw/zwift-api-documentation
 
   Synchronous usage:
@@ -74,6 +163,9 @@ class ZwiftFollowers:
     Loads credentials from Config, authenticates, fetches data,
     and populates instance attributes.
 
+    Both lists are fetched in full; the API paginates at 200 entries per
+    page and all pages are collected.
+
     Args:
         rider_id: Zwift rider ID
         include_followers: Whether to fetch followers list
@@ -113,39 +205,23 @@ class ZwiftFollowers:
 
     try:
       with httpx2.Client() as client:
-        # Fetch followers
+        # Fetch followers (all pages; failures are fatal)
         if include_followers:
           url = f'{self.BASE_URL}/api/profiles/{rider_id}/followers'
-          response = client.get(url, headers=headers, timeout=30.0)
-
-          if response.status_code == 404:
-            raise NetworkError(f'Rider {rider_id} not found')
-          if response.status_code != 200:
-            raise NetworkError(
-              f'Failed to fetch followers for rider {rider_id}: '
-              f'HTTP {response.status_code} - {response.text}',
-            )
-
-          raw_data['followers'] = response.text
+          records = _fetch_paginated(
+            client, url, headers, rider_id, 'followers', mode='raise',
+          )
+          raw_data['followers'] = json.dumps(records)
           logger.debug(f'Successfully fetched followers for rider {rider_id}')
 
-        # Fetch followees
+        # Fetch followees (all pages; failures keep collected data)
         if include_followees:
           url = f'{self.BASE_URL}/api/profiles/{rider_id}/followees'
-          response = client.get(url, headers=headers, timeout=30.0)
-
-          if response.status_code == 404:
-            raise NetworkError(f'Rider {rider_id} not found')
-          if response.status_code != 200:
-            logger.warning(
-              f'Failed to fetch followees for rider {rider_id}: '
-              f'HTTP {response.status_code}',
-            )
-            # Continue with just followers data
-            raw_data['followees'] = '[]'
-          else:
-            raw_data['followees'] = response.text
-            logger.debug(f'Successfully fetched followees for rider {rider_id}')
+          records = _fetch_paginated(
+            client, url, headers, rider_id, 'followees', mode='partial',
+          )
+          raw_data['followees'] = json.dumps(records)
+          logger.debug(f'Successfully fetched followees for rider {rider_id}')
 
         # Parse and populate attributes
         self._parse_response(raw_data)
@@ -172,6 +248,9 @@ class ZwiftFollowers:
   ) -> dict[int, 'ZwiftFollowers']:
     """Fetch multiple riders' follower data, returning dict of objects.
 
+    Both lists are fetched in full; the API paginates at 200 entries per
+    page and all pages are collected.
+
     Args:
         *rider_ids: Zwift rider IDs to fetch
         include_followers: Whether to fetch followers lists
@@ -223,33 +302,22 @@ class ZwiftFollowers:
         try:
           raw_data = {}
 
-          # Fetch followers
+          # Fetch followers (all pages; failure skips the rider via
+          # the except below)
           if include_followers:
             url = f'{cls.BASE_URL}/api/profiles/{rider_id}/followers'
-            response = client.get(url, headers=headers, timeout=30.0)
-
-            if response.status_code == 200:
-              raw_data['followers'] = response.text
-            else:
-              logger.warning(
-                f'Failed to fetch followers for rider {rider_id}: '
-                f'HTTP {response.status_code}',
-              )
-              continue
-
-          # Fetch followees
+            records = _fetch_paginated(
+              client, url, headers, rider_id, 'followers', mode='raise',
+            )
+            raw_data['followers'] = json.dumps(records)
+
+          # Fetch followees (all pages; failures keep collected data)
           if include_followees:
             url = f'{cls.BASE_URL}/api/profiles/{rider_id}/followees'
-            response = client.get(url, headers=headers, timeout=30.0)
-
-            if response.status_code == 200:
-              raw_data['followees'] = response.text
-            else:
-              logger.warning(
-                f'Failed to fetch followees for rider {rider_id}: '
-                f'HTTP {response.status_code}',
-              )
-              raw_data['followees'] = '[]'
+            records = _fetch_paginated(
+              client, url, headers, rider_id, 'followees', mode='partial',
+            )
+            raw_data['followees'] = json.dumps(records)
 
           # Create object and populate
           followers_obj = cls()