pydropcountr 0.1.2__tar.gz

pydropcountr-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+
+    - name: Set up Python ${{ matrix.python-version }}
+      run: uv python install ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        uv sync --dev
+
+    - name: Run ruff linting
+      run: uv run ruff check --output-format=github .
+
+    - name: Run ruff formatting check
+      run: uv run ruff format --check .
+
+    - name: Run mypy type checking
+      run: uv run mypy pydropcountr/ --ignore-missing-imports
+
+    - name: Run tests
+      run: uv run python test_login.py
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+
+    - name: Set up Python
+      run: uv python install 3.12
+
+    - name: Install dependencies
+      run: uv sync --dev
+
+    - name: Run bandit security linter
+      run: |
+        uv add --dev bandit
+        uv run bandit -r pydropcountr/ -f json -o bandit-report.json || true
+
+    - name: Upload bandit results
+      uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: bandit-results
+        path: bandit-report.json

pydropcountr-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,101 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'  # Trigger on version tags like v1.0.0, v0.1.0, etc.
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.12', '3.13']
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+    
+    - name: Install dependencies
+      run: |
+        uv sync --dev
+    
+    - name: Run linting
+      run: |
+        uv run ruff check
+    
+    - name: Run type checking
+      run: |
+        uv run mypy pydropcountr/ --ignore-missing-imports
+    
+    - name: Run tests
+      run: |
+        uv run python test_login.py
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+    
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+    
+    - name: Install build dependencies
+      run: |
+        uv add --dev build
+    
+    - name: Build package
+      run: |
+        uv run python -m build
+    
+    - name: Check distribution
+      run: |
+        uv add --dev twine
+        uv run twine check dist/*
+    
+    - name: Upload build artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+  publish:
+    needs: [test, build]
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # Required for trusted publishing
+    
+    steps:
+    - name: Download build artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: dist
+        path: dist/
+    
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        # Use trusted publishing - no need for API tokens
+        # Configure this in PyPI project settings
+        verify-metadata: true

pydropcountr-0.1.2/.gitignore

@@ -0,0 +1,159 @@
+# Environment files
+.envrc
+.env
+.env.local
+
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff
+instance/
+.webassets-cache
+
+# Scrapy stuff
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# VS Code
+.vscode/
+
+# macOS
+.DS_Store
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Temporary files
+*.tmp
+*.temp
+*.swp
+*.swo
+*~

pydropcountr-0.1.2/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+All notable changes to PyDropCountr will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.2] - 2025-01-03
+
+### Fixed
+- All MyPy type checking errors for improved code quality and IDE support
+- Missing return type annotations throughout library and CLI
+- Type compatibility issues in ServiceConnection instantiation
+- Return type consistency across all public methods
+
+## [0.1.1] - 2025-01-03
+
+### Added
+- GitHub Actions workflow for automated PyPI publishing with trusted publishing
+- Debug logging support with `--debug` flag for CLI troubleshooting
+- Comprehensive logging throughout library and CLI for better error tracking
+- PUBLISHING.md guide for PyPI deployment and trusted publishing setup
+- Support for multiple premises - now discovers all service connections across user's properties
+- Complete address information (street, city, state, zip) in services and usage commands
+- Service type information (Multi Family, Single Family) in services list
+- Enhanced CLI with address display for better property identification
+
+### Fixed
+- API response format handling for `/api/me` endpoint (supports both old and new formats)
+- Multiple premises support - fixed bug where only first premise's service connections were found
+- Service connections discovery now works correctly across all user premises
+- Email None handling in debug logging to prevent crashes with missing credentials
+- Linting issues and code formatting for clean CI/CD runs
+
+### Changed
+- Restructured project as proper Python package with `pydropcountr/` directory
+- Updated build system to use Hatchling with comprehensive PyPI metadata
+- Improved error messages and debugging capabilities throughout
+- Enhanced address display format with complete location information
+- Updated CI workflow to work with new package structure and latest tooling
+
+## [0.3.0] - 2025-06-12
+
+### Added
+- Comprehensive CLI interface using Fire library
+- Default behavior showing yesterday + last 7 days usage
+- Support for all CLI flags (email, password, service_id, dates, period)
+- Environment variable support for credentials (DROPCOUNTR_EMAIL, DROPCOUNTR_PASSWORD)
+- CLI entry point in pyproject.toml as `dropcountr` command
+
+### Changed
+- CLI now automatically selects first available service connection as default
+
+## [0.2.0] - 2025-06-12
+
+### Added
+- Pydantic data models for type safety and validation
+- Comprehensive README.md with usage examples
+- GitHub Actions CI/CD pipeline with linting and testing
+- Support for modern Python type hints (X | Y union syntax)
+- Service connection management APIs (`list_service_connections`, `get_service_connection`)
+- Support for Python datetime objects in `get_usage()` method (alongside ISO strings)
+- Data validation constraints (e.g., gallons >= 0)
+
+### Changed
+- Migrated from dataclasses to Pydantic BaseModel for all data structures
+- Updated to modern Python syntax throughout codebase
+- Enhanced type hints and validation
+
+### Fixed
+- Date parameter handling now supports both datetime objects and ISO strings
+- Improved error handling and validation
+
+## [0.1.0] - 2025-05-25
+
+### Added
+- Initial PyDropCountr library implementation
+- User authentication with login/logout functionality
+- Session management with rack.session cookies
+- Water usage data fetching with date ranges
+- Structured data objects (ServiceConnection, UsageData, UsageResponse)
+- Date parsing and validation utilities
+- Support for uv dependency management
+- Basic test suite
+
+### Features
+- Login to dropcountr.com with email/password
+- Fetch usage data for service connections with flexible date ranges
+- Parse usage data into clean Python objects
+- Handle authentication state and session management
+- Support for different time periods (day, hour)
+- Irrigation and leak detection data parsing
+
+---
+
+## Release Guidelines
+
+### Version Numbers
+- **Major (X.y.z)**: Breaking changes to public API
+- **Minor (x.Y.z)**: New features, backward compatible
+- **Patch (x.y.Z)**: Bug fixes, backward compatible
+
+### Change Categories
+- **Added**: New features
+- **Changed**: Changes in existing functionality
+- **Deprecated**: Soon-to-be removed features
+- **Removed**: Removed features
+- **Fixed**: Bug fixes
+- **Security**: Security improvements
+
+### Release Process
+1. Update CHANGELOG.md with new version section
+2. Move items from [Unreleased] to new version section
+3. Update version in pyproject.toml
+4. Create git tag with version number
+5. Create GitHub release with changelog notes

pydropcountr-0.1.2/CLAUDE.md

@@ -0,0 +1,138 @@
+# PyDropCountr - Python Library for DropCountr.com
+
+## Project Overview
+This is a Python library for interacting with dropcountr.com, providing easy access to water usage data through clean Python objects.
+
+## Features
+- User authentication with login/logout
+- Service connection management (list and get details)
+- Water usage data fetching with date ranges
+- Structured data objects (ServiceConnection, UsageData, UsageResponse)
+- Date parsing and validation
+- Session management with rack.session cookies
+
+## Development Setup
+- This project uses `uv` for dependency management
+- Python 3.12+ required
+- Dependencies: requests>=2.31.0
+- Run tests with: `uv run python test_login.py`
+- Run linting with: `uv run ruff check` (when configured)
+
+## Usage Examples
+
+### Basic Login
+```python
+from pydropcountr import DropCountrClient
+
+client = DropCountrClient()
+success = client.login('your@email.com', 'yourpassword')
+if success:
+    print("Logged in successfully!")
+```
+
+### List Service Connections
+```python
+# Get all service connections for the authenticated user
+services = client.list_service_connections()
+if services:
+    print(f"Found {len(services)} service connections:")
+    for service in services:
+        print(f"  {service.id}: {service.name} at {service.address}")
+```
+
+### Get Service Connection Details
+```python
+# Get details for a specific service connection
+service = client.get_service_connection(1064520)
+if service:
+    print(f"Service: {service.name}")
+    print(f"Address: {service.address}")
+    print(f"Account: {service.account_number}")
+    print(f"Status: {service.status}")
+```
+
+### Fetch Usage Data
+```python
+from datetime import datetime
+
+# Get daily usage data for June 2025 using Python datetime objects
+usage = client.get_usage(
+    service_connection_id=1258809,
+    start_date=datetime(2025, 6, 1),           # Python datetime object
+    end_date=datetime(2025, 6, 30, 23, 59, 59), # Python datetime object
+    period='day'  # Can be 'day', 'hour', etc.
+)
+
+if usage:
+    print(f"Total records: {usage.total_items}")
+    for record in usage.usage_data[:3]:
+        print(f"{record.start_date.date()}: {record.total_gallons} gallons")
+
+# Alternative: You can still use ISO datetime strings
+usage = client.get_usage(
+    service_connection_id=1258809,
+    start_date='2025-06-01T00:00:00.000Z',
+    end_date='2025-06-30T23:59:59.000Z',
+    period='day'
+)
+```
+
+## API Information
+- Login URL: https://dropcountr.com/login
+- Login method: POST with email and password parameters
+- Service connections list: https://dropcountr.com/api/service_connections
+- Service connection details: https://dropcountr.com/api/service_connections/{id}
+- Usage API: https://dropcountr.com/api/service_connections/{id}/usage
+- Authentication: rack.session cookie must be maintained for subsequent requests
+- API version: application/vnd.dropcountr.api+json;version=2
+
+## Data Classes
+- `ServiceConnection`: Service connection details including ID, name, address, account info
+- `UsageData`: Individual usage record with gallons, irrigation data, leak detection
+- `UsageResponse`: Full API response with usage data array and metadata
+- All classes include proper type hints and parsing utilities
+
+## Development Notes
+- Keep authentication session state for API calls
+- Implement proper error handling for login failures and API errors
+- Return data as clean Python objects with type safety
+- **Service Discovery**: Use `list_service_connections()` to discover available service connection IDs
+- **Date Parameters**: The library accepts both Python `datetime` objects (recommended) and ISO 8601 datetime strings
+- When using datetime objects, the library automatically converts them to the required API format
+- Timezone handling: datetime objects are converted to UTC with 'Z' suffix for API compatibility
+
+## Changelog Management
+
+### Using CHANGELOG.md
+This project maintains a comprehensive CHANGELOG.md file following [Keep a Changelog](https://keepachangelog.com/) format:
+
+**When to update the changelog:**
+- Every significant change to the library or CLI
+- New features, bug fixes, API changes, or breaking changes
+- Before each release to move items from [Unreleased] to a version section
+
+**How to update the changelog:**
+1. Add new changes under the `[Unreleased]` section
+2. Use appropriate categories: Added, Changed, Deprecated, Removed, Fixed, Security
+3. Write clear, user-focused descriptions of changes
+4. Include relevant details like new CLI flags, API changes, or breaking changes
+
+**Release process:**
+1. Update CHANGELOG.md with new version section
+2. Move items from [Unreleased] to the new version section with date
+3. Update version number in pyproject.toml
+4. Create git tag with version number: `git tag v0.x.x`
+5. Create GitHub release with changelog notes
+
+**Example changelog entry:**
+```markdown
+## [Unreleased]
+
+### Added
+- New CLI flag `--format` for output formatting
+- Support for JSON output in CLI
+
+### Fixed
+- Authentication timeout handling
+- Memory leak in session management
+```

pydropcountr-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matthew Colyer
+
+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.