zpdatafetch 2.1.0__tar.gz → 2.1.2__tar.gz

{zpdatafetch-2.1.0/src/zpdatafetch.egg-info → zpdatafetch-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zpdatafetch
-Version: 2.1.0
+Version: 2.1.2
 Summary: A package for fetching data from Zwiftpower and Zwiftracing.app
 Author-email: Doug Morris <doug@mhost.com>
 License-Expression: MIT
@@ -13,7 +13,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: anyio>=4.4.0
 Requires-Dist: beautifulsoup4>=4.12.3
-Requires-Dist: cryptography>=44.0.0
+Requires-Dist: cryptography>=46.0.5
 Requires-Dist: httpx>=0.28.0
 Requires-Dist: keyring>=25.2.0
 Requires-Dist: keyrings-alt
@@ -295,7 +295,7 @@ including rider ratings, race results, and team rosters.
 
 ```sh
 usage: zrdata [-h] [-v] [-vv] [--log-file PATH] [-r] [--v1fetch] [--noaction] [--sync]
-              [--batch] [--batch-file FILE] [--premium]
+              [--batch] [--batch-file FILE] [--premium] [--at DATETIME]
               [{config,rider,result,team}] [id ...]
 
 Module for fetching Zwiftracing data using the Zwiftracing API
@@ -317,6 +317,7 @@ options:
   --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)
 ```
 
 **Note:** All objects support both synchronous (`fetch()`) and asynchronous (`afetch()`) methods. See the Async API section below for details.
@@ -349,6 +350,28 @@ zrdata config
 zrdata config  # Will prompt for authorization header
 ```
 
+### Historical Ratings
+
+Use `--at` to fetch rider ratings at a specific point in time. Accepts ISO 8601
+date/time strings, interpreted as UTC:
+
+```sh
+# Fetch ratings as of a specific date
+zrdata rider --at 2024-06-15 12345
+
+# Fetch ratings at a specific date and time
+zrdata rider --at "2024-06-15 14:30" 12345
+
+# ISO 8601 with T separator
+zrdata rider --at 2024-06-15T14:30:00 12345
+
+# Combine with batch
+zrdata rider --batch --at 2024-06-15 12345 67890 11111
+
+# Preview what would be fetched
+zrdata rider --noaction --at 2024-06-15 12345
+```
+
 ### Advanced Options
 
 ```sh
@@ -735,10 +758,11 @@ async def main():
         for zwift_id, rider in riders.items():
             print(f"{rider.name}: {rider.current_rating}")
 
-        # Batch fetch with historical data
+        # Batch fetch with historical data (epoch is a Unix timestamp)
+        from shared.validation import parse_datetime_to_epoch
         historical = await ZRRider.afetch_batch(
             12345, 67890,
-            epoch=1704067200,  # Unix timestamp
+            epoch=parse_datetime_to_epoch('2024-01-01'),
             zr=zr
         )
 

{zpdatafetch-2.1.0 → zpdatafetch-2.1.2}/README.md

@@ -269,7 +269,7 @@ including rider ratings, race results, and team rosters.
 
 ```sh
 usage: zrdata [-h] [-v] [-vv] [--log-file PATH] [-r] [--v1fetch] [--noaction] [--sync]
-              [--batch] [--batch-file FILE] [--premium]
+              [--batch] [--batch-file FILE] [--premium] [--at DATETIME]
               [{config,rider,result,team}] [id ...]
 
 Module for fetching Zwiftracing data using the Zwiftracing API
@@ -291,6 +291,7 @@ options:
   --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)
 ```
 
 **Note:** All objects support both synchronous (`fetch()`) and asynchronous (`afetch()`) methods. See the Async API section below for details.
@@ -323,6 +324,28 @@ zrdata config
 zrdata config  # Will prompt for authorization header
 ```
 
+### Historical Ratings
+
+Use `--at` to fetch rider ratings at a specific point in time. Accepts ISO 8601
+date/time strings, interpreted as UTC:
+
+```sh
+# Fetch ratings as of a specific date
+zrdata rider --at 2024-06-15 12345
+
+# Fetch ratings at a specific date and time
+zrdata rider --at "2024-06-15 14:30" 12345
+
+# ISO 8601 with T separator
+zrdata rider --at 2024-06-15T14:30:00 12345
+
+# Combine with batch
+zrdata rider --batch --at 2024-06-15 12345 67890 11111
+
+# Preview what would be fetched
+zrdata rider --noaction --at 2024-06-15 12345
+```
+
 ### Advanced Options
 
 ```sh
@@ -709,10 +732,11 @@ async def main():
         for zwift_id, rider in riders.items():
             print(f"{rider.name}: {rider.current_rating}")
 
-        # Batch fetch with historical data
+        # Batch fetch with historical data (epoch is a Unix timestamp)
+        from shared.validation import parse_datetime_to_epoch
         historical = await ZRRider.afetch_batch(
             12345, 67890,
-            epoch=1704067200,  # Unix timestamp
+            epoch=parse_datetime_to_epoch('2024-01-01'),
             zr=zr
         )
 

{zpdatafetch-2.1.0 → zpdatafetch-2.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "zpdatafetch"
-version = "2.1.0"
+version = "2.1.2"
 description = "A package for fetching data from Zwiftpower and Zwiftracing.app"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -19,7 +19,7 @@ dependencies = [
   # Async support (anyio provides backend-agnostic async utilities)
   "anyio>=4.4.0",
   "beautifulsoup4>=4.12.3",
-  "cryptography>=44.0.0",
+  "cryptography>=46.0.5",
   # Note: httpx 0.28.0 depends on httpcore 1.1.x which has a compatibility
   # issue with Python 3.14's typing.Union. This causes test failures on 3.14.
   # Workaround: test_shared_client_connection_pooling is marked as xfail on 3.14.
@@ -124,10 +124,6 @@ select = [
   "UP",  # pyupgrade
   "ANN",  # flake8-annotations (type hints)
 ]
-ignore = [
-  "ANN101",  # Missing type annotation for self
-  "ANN102",  # Missing type annotation for cls
-]
 
 # Per-file ignores for justified Any usage
 [tool.ruff.lint.per-file-ignores]

{zpdatafetch-2.1.0 → zpdatafetch-2.1.2}/src/shared/cli.py

@@ -5,6 +5,7 @@ functionality for both zpdatafetch and zrdatafetch CLIs.
 """
 
 import logging
+import sys
 from argparse import ArgumentParser, Namespace
 from collections.abc import Callable
 from importlib.metadata import PackageNotFoundError, version
@@ -216,7 +217,7 @@ def validate_command_name(
     True if valid, False if invalid.
   """
   if cmd not in valid_commands:
-    print(f'Error: Unknown command "{cmd}"')
+    print(f'Error: Unknown command "{cmd}"', file=sys.stderr)
     return False
   return True
 
@@ -235,7 +236,7 @@ def validate_ids_provided(
     True if IDs provided, False otherwise.
   """
   if not ids:
-    print(f'Error: {cmd} command requires one or more IDs')
+    print(f'Error: {cmd} command requires one or more IDs', file=sys.stderr)
     return False
   return True
 
@@ -271,5 +272,5 @@ def read_ids_from_file(filepath: str) -> list[str] | None:
     with open(filepath) as f:
       return [line.strip() for line in f if line.strip()]
   except OSError as e:
-    print(f'Error reading batch file: {e}')
+    print(f'Error reading batch file: {e}', file=sys.stderr)
     return None

{zpdatafetch-2.1.0 → zpdatafetch-2.1.2}/src/shared/validation.py

@@ -15,7 +15,9 @@ These ranges are based on Python's native integer limits and observed
 API behavior.
 """
 
+import calendar
 import sys
+from datetime import datetime, timezone
 from typing import Literal
 
 # ID Range Constants
@@ -178,6 +180,44 @@ def validate_epoch(value: int) -> int:
   return value
 
 
+def parse_datetime_to_epoch(value: str) -> int:
+  """Parse a date/time string to a validated Unix epoch timestamp (UTC).
+
+  Accepts ISO 8601 formats:
+    - '2024-06-15'              (date only, midnight UTC)
+    - '2024-06-15 14:30'        (date and time, UTC)
+    - '2024-06-15T14:30:00'     (ISO 8601, UTC)
+    - '2024-06-15T14:30:00Z'    (ISO 8601 with Z suffix)
+    - '2024-06-15T14:30:00+00:00' (ISO 8601 with timezone)
+
+  Args:
+      value: Date/time string to parse
+
+  Returns:
+      Unix epoch timestamp (int, UTC)
+
+  Raises:
+      ValidationError: If the string cannot be parsed or the resulting
+          epoch is out of range
+  """
+  try:
+    # Replace trailing 'Z' with '+00:00' for Python 3.10 compatibility
+    normalized = value.replace('Z', '+00:00') if value.endswith('Z') else value
+    dt = datetime.fromisoformat(normalized)
+  except ValueError as e:
+    raise ValidationError(
+      f"Invalid date/time '{value}': use ISO 8601 format "
+      f"(e.g. '2024-06-15' or '2024-06-15T14:30:00')",
+    ) from e
+
+  # Assume UTC if no timezone specified
+  if dt.tzinfo is None:
+    dt = dt.replace(tzinfo=timezone.utc)
+
+  epoch = calendar.timegm(dt.utctimetuple())
+  return validate_epoch(epoch)
+
+
 def validate_batch_size(count: int, max_size: int = MAX_BATCH_SIZE) -> None:
   """Validate batch request size.
 

{zpdatafetch-2.1.0 → zpdatafetch-2.1.2}/src/zpdatafetch/cli.py

@@ -7,7 +7,8 @@ team rosters, and prime data.
 
 import json
 import sys
-from typing import Any
+from collections.abc import Iterable
+from typing import Any, cast
 
 from shared.cli import (
   configure_logging_from_args,
@@ -267,7 +268,7 @@ Module for fetching zwiftpower data using the Zwifpower API
     case 'team':
       x = ZPTeamFetch()
     case _:
-      print(f'Unknown command: {args.cmd}')
+      print(f'Unknown command: {args.cmd}', file=sys.stderr)
       return 1
 
   x.fetch(*args.id)
@@ -308,7 +309,7 @@ Module for fetching zwiftpower data using the Zwifpower API
         # Check for excluded in each item if it's a collection
         if hasattr(value, '__iter__') and not isinstance(value, str):
           try:
-            for item in value:  # type: ignore[iteration-not-supported]
+            for item in cast(Iterable[Any], value):
               if hasattr(item, 'excluded'):
                 item_excluded = item.excluded()
                 if item_excluded:
@@ -330,7 +331,7 @@ Module for fetching zwiftpower data using the Zwifpower API
         # Check for extras in each item if it's a collection
         if hasattr(value, '__iter__') and not isinstance(value, str):
           try:
-            for item in value:  # type: ignore[iteration-not-supported]
+            for item in cast(Iterable[Any], value):
               if hasattr(item, 'extras'):
                 item_extras = item.extras()
                 if item_extras:
@@ -381,7 +382,7 @@ Module for fetching zwiftpower data using the Zwifpower API
       ):
         print()  # Newline after key for collections
         try:
-          for item in value:  # type: ignore[iteration-not-supported]
+          for item in cast(Iterable[Any], value):
             print_collection(item, indent=1)
         except (TypeError, AttributeError):
           pass

{zpdatafetch-2.1.0 → zpdatafetch-2.1.2}/src/zpdatafetch/zp.py

@@ -489,7 +489,6 @@ def main() -> None:
   Core module for accessing Zwiftpower API endpoints
   """
   zp = ZP()
-  zp.verbose = True  # type: ignore[attr-defined]
   zp.login()
   if zp.login_response:
     print(zp.login_response.status_code)

{zpdatafetch-2.1.0 → zpdatafetch-2.1.2}/src/zpdatafetch/zpcyclistfetch.py

@@ -20,7 +20,7 @@ else:
     )
   except ImportError:
     # Fallback - catch the anyio exception type
-    BaseExceptionGroup = Exception
+    BaseExceptionGroup: type[BaseException] = Exception
 
 from shared.json_helpers import parse_json_safe
 from shared.validation import ValidationError, validate_id_list

{zpdatafetch-2.1.0 → zpdatafetch-2.1.2}/src/zpdatafetch/zpprimesfetch.py

@@ -136,11 +136,10 @@ class ZPPrimesFetch(ZP_obj):
       await async_zp.init_client()
 
       # Copy authentication state from sync to async client
-      if self._zp_sync._client and async_zp._client:
-        # Share the cookies - this preserves the login session
-        assert async_zp._client is not None
       assert self._zp_sync._client is not None
-      async_zp._client.cookies = self._zp_sync._client.cookies  # type: ignore[assignment]
+      assert async_zp._client is not None
+      # Share the cookies - this preserves the login session
+      async_zp._client.cookies = self._zp_sync._client.cookies
       logger.debug('Copied authentication cookies from sync to async session')
 
       # Don't store this - create fresh each time to avoid lifecycle issues

{zpdatafetch-2.1.0 → zpdatafetch-2.1.2}/src/zpdatafetch/zpraceresult.py

@@ -3,7 +3,7 @@
 import json
 from collections.abc import Iterator, Sequence
 from dataclasses import asdict, dataclass, field
-from typing import Any
+from typing import Any, overload
 
 from zpdatafetch.zp_utils import (
   convert_gender,
@@ -511,14 +511,19 @@ class ZPRaceResult(Sequence):
     """
     return len(self._riders)
 
-  def __getitem__(self, index: int) -> ZPRiderFinish:  # type: ignore[override]
-    """Access rider finish by index.
+  @overload
+  def __getitem__(self, index: int) -> ZPRiderFinish: ...
+  @overload
+  def __getitem__(self, index: slice) -> Sequence[ZPRiderFinish]: ...
+
+  def __getitem__(self, index: int | slice) -> ZPRiderFinish | Sequence[ZPRiderFinish]:
+    """Access rider finish by index or slice.
 
     Args:
-      index: Integer index
+      index: Integer index or slice
 
     Returns:
-      Single rider
+      Single rider or sequence of riders
 
     Raises:
       IndexError: If index out of range

{zpdatafetch-2.1.0 → zpdatafetch-2.1.2/src/zpdatafetch.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zpdatafetch
-Version: 2.1.0
+Version: 2.1.2
 Summary: A package for fetching data from Zwiftpower and Zwiftracing.app
 Author-email: Doug Morris <doug@mhost.com>
 License-Expression: MIT
@@ -13,7 +13,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: anyio>=4.4.0
 Requires-Dist: beautifulsoup4>=4.12.3
-Requires-Dist: cryptography>=44.0.0
+Requires-Dist: cryptography>=46.0.5
 Requires-Dist: httpx>=0.28.0
 Requires-Dist: keyring>=25.2.0
 Requires-Dist: keyrings-alt
@@ -295,7 +295,7 @@ including rider ratings, race results, and team rosters.
 
 ```sh
 usage: zrdata [-h] [-v] [-vv] [--log-file PATH] [-r] [--v1fetch] [--noaction] [--sync]
-              [--batch] [--batch-file FILE] [--premium]
+              [--batch] [--batch-file FILE] [--premium] [--at DATETIME]
               [{config,rider,result,team}] [id ...]
 
 Module for fetching Zwiftracing data using the Zwiftracing API
@@ -317,6 +317,7 @@ options:
   --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)
 ```
 
 **Note:** All objects support both synchronous (`fetch()`) and asynchronous (`afetch()`) methods. See the Async API section below for details.
@@ -349,6 +350,28 @@ zrdata config
 zrdata config  # Will prompt for authorization header
 ```
 
+### Historical Ratings
+
+Use `--at` to fetch rider ratings at a specific point in time. Accepts ISO 8601
+date/time strings, interpreted as UTC:
+
+```sh
+# Fetch ratings as of a specific date
+zrdata rider --at 2024-06-15 12345
+
+# Fetch ratings at a specific date and time
+zrdata rider --at "2024-06-15 14:30" 12345
+
+# ISO 8601 with T separator
+zrdata rider --at 2024-06-15T14:30:00 12345
+
+# Combine with batch
+zrdata rider --batch --at 2024-06-15 12345 67890 11111
+
+# Preview what would be fetched
+zrdata rider --noaction --at 2024-06-15 12345
+```
+
 ### Advanced Options
 
 ```sh
@@ -735,10 +758,11 @@ async def main():
         for zwift_id, rider in riders.items():
             print(f"{rider.name}: {rider.current_rating}")
 
-        # Batch fetch with historical data
+        # Batch fetch with historical data (epoch is a Unix timestamp)
+        from shared.validation import parse_datetime_to_epoch
         historical = await ZRRider.afetch_batch(
             12345, 67890,
-            epoch=1704067200,  # Unix timestamp
+            epoch=parse_datetime_to_epoch('2024-01-01'),
             zr=zr
         )
 

{zpdatafetch-2.1.0 → zpdatafetch-2.1.2}/src/zpdatafetch.egg-info/requires.txt

@@ -1,6 +1,6 @@
 anyio>=4.4.0
 beautifulsoup4>=4.12.3
-cryptography>=44.0.0
+cryptography>=46.0.5
 httpx>=0.28.0
 keyring>=25.2.0
 keyrings-alt

{zpdatafetch-2.1.0 → zpdatafetch-2.1.2}/src/zrdatafetch/cli.py

@@ -23,6 +23,7 @@ from shared.cli import (
   validate_command_provided,
   validate_ids_provided,
 )
+from shared.validation import ValidationError, parse_datetime_to_epoch
 from zrdatafetch import (
   Config,
   ZRResultFetch,
@@ -74,6 +75,15 @@ Module for fetching Zwiftracing data using the Zwiftracing API
     action='store_true',
     help='use premium tier rate limits (higher request quotas)',
   )
+  p.add_argument(
+    '--at',
+    type=str,
+    metavar='DATETIME',
+    help=(
+      'fetch historical ratings at a given date/time (UTC), '
+      "e.g. '2024-06-15' or '2024-06-15T14:30:00' (rider command only)"
+    ),
+  )
 
   # Use parse_intermixed_args to handle flags after positional arguments
   # This allows: zrdata rider --noaction 12345 67890
@@ -117,11 +127,25 @@ Module for fetching Zwiftracing data using the Zwiftracing API
       if not validate_ids_provided(args.id, 'rider'):
         return 1
 
+      # Parse --at to epoch
+      epoch: int | None = None
+      if args.at:
+        try:
+          epoch = parse_datetime_to_epoch(args.at)
+        except ValidationError as e:
+          print(f'Error: {e}', file=sys.stderr)
+          return 1
+
       if args.noaction:
         if args.batch or args.batch_file:
-          print(f'Would fetch {len(args.id)} riders using batch POST')
+          msg = f'Would fetch {len(args.id)} riders using batch POST'
         else:
-          format_noaction_output('rider', args.id, args.raw)
+          msg = f"Would fetch rider data for: {', '.join(args.id)}"
+          if args.raw:
+            msg += ' (raw output format)'
+        if epoch is not None:
+          msg += f' at {args.at} (epoch {epoch})'
+        print(msg)
         return None
 
       try:
@@ -130,20 +154,20 @@ Module for fetching Zwiftracing data using the Zwiftracing API
 
         # Handle batch request
         if args.batch or args.batch_file:
-          riders = ZRRiderFetch.fetch_batch(*rider_ids)
+          riders = ZRRiderFetch.fetch_batch(*rider_ids, epoch=epoch)
           fetcher = None  # Batch doesn't use fetcher instance
         else:
           fetcher = ZRRiderFetch()
-          riders = fetcher.fetch(*rider_ids)
+          riders = fetcher.fetch(*rider_ids, epoch=epoch)
 
         # Output results
         _output_results(args, riders, fetcher)
 
       except ValueError as e:
-        print(f'Error: Invalid Zwift ID: {e}')
+        print(f'Error: Invalid Zwift ID: {e}', file=sys.stderr)
         return 1
       except Exception as e:
-        print(f'Error fetching rider: {e}')
+        print(f'Error fetching rider: {e}', file=sys.stderr)
         return 1
 
     case 'result':
@@ -164,10 +188,10 @@ Module for fetching Zwiftracing data using the Zwiftracing API
         _output_results(args, results, fetcher)
 
       except ValueError as e:
-        print(f'Error: Invalid race ID: {e}')
+        print(f'Error: Invalid race ID: {e}', file=sys.stderr)
         return 1
       except Exception as e:
-        print(f'Error fetching result: {e}')
+        print(f'Error fetching result: {e}', file=sys.stderr)
         return 1
 
     case 'team':
@@ -188,10 +212,10 @@ Module for fetching Zwiftracing data using the Zwiftracing API
         _output_results(args, teams, fetcher)
 
       except ValueError as e:
-        print(f'Error: Invalid team ID: {e}')
+        print(f'Error: Invalid team ID: {e}', file=sys.stderr)
         return 1
       except Exception as e:
-        print(f'Error fetching team: {e}')
+        print(f'Error fetching team: {e}', file=sys.stderr)
         return 1
 
     case _:

{zpdatafetch-2.1.0 → zpdatafetch-2.1.2}/src/zrdatafetch/zrraceresult.py

@@ -6,7 +6,7 @@ any fetch logic. Fetching is handled by ZRResultFetch.
 
 from collections.abc import Iterator, Sequence
 from dataclasses import asdict, dataclass, field
-from typing import Any
+from typing import Any, overload
 
 from zrdatafetch.logging_config import get_logger
 from zrdatafetch.zr_utils import safe_float, safe_int, safe_str
@@ -236,14 +236,21 @@ class ZRRaceResult(Sequence):
     """
     return len(self._results)
 
-  def __getitem__(self, index: int) -> ZRRiderResult:  # type: ignore[override]
-    """Access rider result by index.
+  @overload
+  def __getitem__(self, index: int) -> ZRRiderResult: ...
+  @overload
+  def __getitem__(self, index: slice) -> Sequence[ZRRiderResult]: ...
+
+  def __getitem__(
+    self, index: int | slice,
+  ) -> ZRRiderResult | Sequence[ZRRiderResult]:
+    """Access rider result by index or slice.
 
     Args:
-      index: Integer index
+      index: Integer index or slice
 
     Returns:
-      ZRRiderResult object
+      ZRRiderResult object or sequence of results
 
     Raises:
       IndexError: If index out of range

{zpdatafetch-2.1.0 → zpdatafetch-2.1.2}/src/zrdatafetch/zrteamroster.py

@@ -6,7 +6,7 @@ any fetch logic. Fetching is handled by ZRTeamFetch.
 
 from collections.abc import Iterator, Sequence
 from dataclasses import asdict, dataclass, field
-from typing import Any
+from typing import Any, overload
 
 from zrdatafetch.logging_config import get_logger
 from zrdatafetch.zr_utils import (
@@ -358,14 +358,21 @@ class ZRTeamRoster(Sequence):
     """
     return len(self._members)
 
-  def __getitem__(self, index: int) -> ZRTeamMember:  # type: ignore[override]
-    """Access team member by index.
+  @overload
+  def __getitem__(self, index: int) -> ZRTeamMember: ...
+  @overload
+  def __getitem__(self, index: slice) -> Sequence[ZRTeamMember]: ...
+
+  def __getitem__(
+    self, index: int | slice,
+  ) -> ZRTeamMember | Sequence[ZRTeamMember]:
+    """Access team member by index or slice.
 
     Args:
-      index: Integer index
+      index: Integer index or slice
 
     Returns:
-      ZRTeamMember object
+      ZRTeamMember object or sequence of members
 
     Raises:
       IndexError: If index out of range