pettracer-client 0.1.0__tar.gz

pettracer_client-0.1.0/.env.example

@@ -0,0 +1,5 @@
+# PetTracer API Credentials
+# Copy this file to .env and fill in your credentials
+
+PETTRACER_USERNAME=your_username_here
+PETTRACER_PASSWORD=your_password_here

pettracer_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Giles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pettracer_client-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include LICENSE
+include requirements-dev.txt
+include .env.example
+recursive-include examples *.py
+recursive-include tests *.py
+global-exclude __pycache__
+global-exclude *.py[co]

pettracer_client-0.1.0/PKG-INFO

@@ -0,0 +1,364 @@
+Metadata-Version: 2.4
+Name: pettracer-client
+Version: 0.1.0
+Summary: Python client library for the PetTracer GPS pet collar portal
+Author-email: Richard Giles <git@egilius.net>
+License: MIT
+Project-URL: Homepage, https://github.com/AmbientArchitect/petTracer-API
+Project-URL: Documentation, https://github.com/AmbientArchitect/petTracer-API#readme
+Project-URL: Repository, https://github.com/AmbientArchitect/petTracer-API
+Project-URL: Issues, https://github.com/AmbientArchitect/petTracer-API/issues
+Keywords: pettracer,gps,pet,tracker,collar,api,client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Dynamic: license-file
+
+# PetTracer API Client
+
+[![PyPI version](https://badge.fury.io/py/pettracer-client.svg)](https://badge.fury.io/py/pettracer-client)
+[![Python](https://img.shields.io/pypi/pyversions/pettracer-client.svg)](https://pypi.org/project/pettracer-client/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Status](https://img.shields.io/pypi/status/pettracer-client.svg)](https://pypi.org/project/pettracer-client/)
+
+Python client library for the [PetTracer](https://www.pettracer.com) GPS pet collar portal. Provides a clean, object-oriented interface for managing devices, tracking positions, and accessing user information.
+
+**Note:** This is an unofficial API derived from the petTracer web site. Use with caution and respect for their service. You need to own a pet collar, have an account and paid subscription for this client to be useful.
+
+## Features
+
+- 🎯 **Object-oriented design** - Clean class hierarchy for intuitive API usage
+- 🔐 **Automatic authentication** - Login once, use everywhere
+- 📍 **Position tracking** - Fetch device locations with time-range filtering
+- 👤 **User management** - Access profile and subscription information
+- 🐾 **Device management** - Control and monitor multiple pet collars
+- 📊 **Typed data models** - Full dataclass support for all responses
+- ✅ **Well tested** - Comprehensive test suite included
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install pettracer-client
+```
+
+Or install the required dependencies for development:
+
+```bash
+pip install requests
+```
+
+For development:
+
+```bash
+pip install -r requirements-dev.txt
+```
+
+## Quick Start
+
+```python
+from pettracer import PetTracerClient
+
+# Create client and authenticate
+client = PetTracerClient()
+client.login("your_username", "your_password")
+
+# Access user information (cached from login)
+print(f"Welcome, {client.user_name}!")
+print(f"You have {client.device_count} device(s)")
+print(f"Subscription expires: {client.subscription_expires}")
+
+# Get all devices
+devices = client.get_all_devices()
+for device in devices:
+    print(f"{device.details.name}: Battery {device.bat}mV")
+
+# Work with a specific device
+pet_device = client.get_device(devices[0].id)
+positions = pet_device.get_positions(
+    filter_time=1767152926491,  # Unix timestamp in milliseconds
+    to_time=1767174526491
+)
+```
+
+For a complete working example, see [examples/class_based_example.py](examples/class_based_example.py).
+
+## Architecture
+
+The library uses a two-tier class architecture:
+
+### Client Hierarchy
+
+```
+PetTracerClient (user-level operations)
+    ├── Authentication & session management
+    ├── User profile & subscription info
+    └── Device discovery
+         └── PetTracerDevice (device-specific operations)
+              ├── Device information
+              └── Position history
+```
+
+### Key Classes
+
+#### `PetTracerClient`
+
+The main entry point for all API operations. Manages authentication and provides access to user-level functionality.
+
+**Initialization:**
+```python
+# Standard login
+client = PetTracerClient()
+client.login(username, password)
+
+# Auto-login on creation
+client = PetTracerClient(username, password)
+```
+
+**Core Methods:**
+- `login(username, password)` - Authenticate and store credentials
+- `get_all_devices()` - Retrieve all devices owned by the user
+- `get_device(device_id)` - Get a device-specific client
+- `get_user_profile()` - Fetch detailed user profile (updates cached data)
+
+**Authentication:**
+- `is_authenticated` - Check if logged in
+- `token` - Current bearer token
+- `token_expires` - Token expiration datetime
+- `session` - Requests session object
+
+**User Information (available after login):**
+- `user_id`, `user_name`, `email`
+- `partner_id`, `language`
+- `country`, `country_id`
+- `device_count` - Number of devices
+
+**Subscription:**
+- `subscription_id` - Subscription identifier
+- `subscription_expires` - Expiration date
+- `subscription_info` - Full `SubscriptionInfo` object
+
+**Raw Data:**
+- `login_info` - Complete `LoginInfo` dataclass with all login response data
+
+#### `PetTracerDevice`
+
+Represents a single pet tracker device. Created via `client.get_device(device_id)`.
+
+**Methods:**
+- `get_info()` - Fetch current device information
+- `get_positions(filter_time, to_time)` - Get position history within time range
+
+**Properties:**
+- `device_id` - The device identifier
+
+**Time Parameters:**
+Position history methods use Unix timestamps in milliseconds:
+```python
+from datetime import datetime, timedelta
+
+now = datetime.now()
+yesterday = now - timedelta(days=1)
+
+positions = device.get_positions(
+    filter_time=int(yesterday.timestamp() * 1000),
+    to_time=int(now.timestamp() * 1000)
+)
+```
+
+## Data Models
+
+All API responses are parsed into typed dataclasses for easy access and IDE autocomplete support.
+
+### Core Types
+
+**`Device`** - Complete device information:
+- `id`, `bat` (battery), `status`, `mode`
+- `details` - `Details` object with name, image, birth date
+- `lastPos` - `LastPos` object with most recent position
+- `masterHs` - Master home station information
+- `lastContact`, `homeSince` - Timestamps
+- Many more fields for device state
+
+**`LastPos`** - Position data:
+- `posLat`, `posLong` - Coordinates
+- `timeMeasure`, `timeDb` - Timestamps
+- `sat` - Satellite count
+- `rssi` - Signal strength
+- `fixS`, `fixP`, `horiPrec` - GPS quality metrics
+- `acc` - Accuracy
+- `flags` - Status flags
+
+**`Details`** - Device/pet details:
+- `name` - Pet name
+- `birth` - Birth date
+- `image`, `img` - Image references
+- `color` - Color code
+
+**`UserProfile`** - User account information:
+- `id`, `email`, `name`
+- `street`, `street2`, `zip`, `city`
+- `mobile`, `lang`, `country_id`
+- Additional profile fields
+
+**`LoginInfo`** - Complete login response data:
+- User identification and account details
+- Authentication tokens and expiration
+- Subscription information via `abo` field
+- Settings and preferences
+
+**`SubscriptionInfo`** - Subscription details:
+- `id`, `userId`, `odooId`
+- `dateExpires` - Expiration date
+- `paypalSubscriptionId`
+- Raw subscription dict
+
+### Working with Data
+
+```python
+# Device information
+device = devices[0]
+print(f"Pet: {device.details.name}")
+print(f"Battery: {device.bat}mV")
+print(f"Last seen: {device.lastContact}")
+
+if device.lastPos:
+    print(f"Location: {device.lastPos.posLat}, {device.lastPos.posLong}")
+    print(f"Satellites: {device.lastPos.sat}")
+    print(f"Time: {device.lastPos.timeMeasure}")
+
+# Position history
+for pos in positions:
+    print(f"{pos.timeMeasure}: ({pos.posLat}, {pos.posLong})")
+    print(f"  Accuracy: {pos.acc}m, Satellites: {pos.sat}")
+
+# User profile
+profile = client.get_user_profile()
+print(f"{profile.name} - {profile.email}")
+print(f"{profile.city}, {profile.zip}")
+```
+
+## Example Application
+
+See [examples/class_based_example.py](examples/class_based_example.py) for a complete working example that demonstrates:
+
+- Client initialization and login
+- Accessing user information and subscription details
+- Fetching and displaying all devices
+- Working with device-specific clients
+- Retrieving position history with time ranges
+- Error handling and data validation
+
+Run the example:
+```bash
+export PETTRACER_USERNAME="your_username"
+export PETTRACER_PASSWORD="your_password"
+python examples/class_based_example.py
+```
+
+## Security
+
+⚠️ **Important:** Authentication tokens are secrets. Always:
+
+- Store credentials in environment variables or secure vaults
+- Never commit tokens or passwords to version control
+- Use `.env` files (which are gitignored) for local development
+- Rotate tokens regularly
+
+The client supports token storage via environment variable:
+```python
+import os
+os.environ['PETTRACER_TOKEN'] = 'your_token_here'
+```
+
+## Testing
+
+Run the comprehensive test suite:
+
+```bash
+# Install test dependencies
+pip install -r requirements-dev.txt
+
+# Run all tests
+pytest -v
+
+# Run specific test file
+pytest tests/test_client.py -v
+
+# Run with coverage
+pytest --cov=pettracer tests/
+```
+
+The test suite uses `pytest` with `monkeypatch` to mock HTTP responses, ensuring tests run without actual API calls.
+
+## VS Code Setup
+
+This workspace is pre-configured for VS Code development. See [VSCODE_GUIDE.md](VSCODE_GUIDE.md) for detailed instructions.
+
+### Quick Start in VS Code
+
+1. Copy `.env.example` to `.env` and add your credentials
+2. Open `examples/class_based_example.py`
+3. Press `F5` to run with debugging
+4. Choose **"Python: Run with .env"**
+
+The workspace includes:
+- Launch configurations for debugging
+- Automatic PYTHONPATH setup in terminals
+- pytest test discovery and debugging
+- Python interpreter configuration
+
+## Development
+
+### Project Structure
+
+```
+pettracer/
+├── __init__.py           # Package exports
+├── client.py             # PetTracerClient and PetTracerDevice classes
+└── types.py              # Dataclass definitions
+
+examples/
+└── class_based_example.py  # Complete usage example
+
+tests/
+└── test_client.py        # Test suite
+
+.vscode/
+├── settings.json         # VS Code configuration
+└── launch.json          # Debug configurations
+```
+
+### Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit a pull request
+
+Issues and feature requests can be submitted via GitHub Issues.
+
+## License
+
+See repository for license information.
+
+---
+
+**Note:** This is an unofficial client library. PetTracer® is a trademark of its respective owner.