# PyMercury - Mercury.co.nz Python Library
A comprehensive Python library for interacting with Mercury.co.nz services, including OAuth authentication and selfservice API integration.
## Features
- **OAuth 2.0 PKCE Authentication** - Secure authentication with Mercury.co.nz
- **Selfservice API Integration** - Access customer, account, and service data
- **Clean Architecture** - Modular design with separate OAuth and API clients
- **Type Safety** - Full type hints for better IDE support
- **Comprehensive Error Handling** - Detailed exceptions for different error scenarios
- **Flexible Configuration** - Environment variable support with sensible defaults
## Installation
```bash
pip install pymercury
```
## Quick Start
### Simple Authentication
```python
from pymercury import authenticate
# Get OAuth tokens
tokens = authenticate("your-email@example.com", "your-password")
print(f"Customer ID: {tokens.customer_id}")
print(f"Access Token: {tokens.access_token}")
```
### Complete Account Data
```python
from pymercury import get_complete_data
# Get everything in one call
data = get_complete_data("your-email@example.com", "your-password")
print(f"Customer ID: {data.customer_id}")
print(f"Account IDs: {data.account_ids}")
print(f"Electricity Services: {data.service_ids.electricity}")
print(f"Gas Services: {data.service_ids.gas}")
print(f"Broadband Services: {data.service_ids.broadband}")
```
### Main Client (Recommended)
```python
from pymercury import MercuryClient
# Create client and login
client = MercuryClient("your-email@example.com", "your-password")
client.login()
# Easy access to information
customer_id = client.customer_id
account_ids = client.account_ids
service_ids = client.service_ids
# Get complete data
complete_data = client.get_complete_account_data()
```
## Advanced Usage
### Separate OAuth and API Clients
```python
from pymercury.oauth import MercuryOAuthClient
from pymercury.api import MercuryAPIClient
# OAuth authentication only
oauth_client = MercuryOAuthClient("email@example.com", "password")
tokens = oauth_client.authenticate()
# API calls with existing tokens
api_client = MercuryAPIClient(tokens.access_token)
customer_info = api_client.get_customer_info(tokens.customer_id)
accounts = api_client.get_accounts(tokens.customer_id)
```
### Electricity Usage and Billing
```python
from pymercury.api import MercuryAPIClient
# Initialize API client with access token
api_client = MercuryAPIClient(access_token)
# Get electricity meter information
meter_info = api_client.get_electricity_meter_info(customer_id, account_id)
if meter_info:
print(f"Meter Number: {meter_info.meter_number}")
print(f"Meter Type: {meter_info.meter_type}")
# Get bill summary
bill_summary = api_client.get_bill_summary(customer_id, account_id)
if bill_summary:
print(f"Current Balance: ${bill_summary.current_balance}")
print(f"Due Date: {bill_summary.due_date}")
# Get electricity usage (defaults to last 14 days)
electricity_usage = api_client.get_electricity_usage(customer_id, account_id, service_id)
if electricity_usage:
print(f"Total Usage: {electricity_usage.total_usage} kWh")
print(f"Average Daily Usage: {electricity_usage.average_daily_usage} kWh")
print(f"Average Temperature: {electricity_usage.average_temperature}°C")
```
## Configuration
### Environment Variables
Create a `.env` file or set environment variables:
```bash
# OAuth Configuration
MERCURY_CLIENT_ID=4c8c2c47-24cd-485d-aad9-12f3d95b3ceb
MERCURY_REDIRECT_URI=https://myaccount.mercury.co.nz
MERCURY_BASE_URL=https://login.mercury.co.nz/fc07dca7-cd6a-4578-952b-de7a7afaebdc
MERCURY_TIMEOUT=20
# API Configuration
MERCURY_API_BASE_URL=https://apis.mercury.co.nz/selfservice/v1
MERCURY_API_SUBSCRIPTION_KEY=f62040b20cf9401fb081880cb71c7dec
```
### Programmatic Configuration
```python
from pymercury import MercuryConfig, MercuryClient
config = MercuryConfig(
client_id="your-client-id",
api_subscription_key="your-api-key",
timeout=30
)
client = MercuryClient("email@example.com", "password", config=config)
```
## Error Handling
```python
from pymercury import (
MercuryClient,
MercuryAuthenticationError,
MercuryAPIError,
MercuryError
)
try:
client = MercuryClient("email@example.com", "password")
client.login()
data = client.get_complete_account_data()
except MercuryAuthenticationError:
print("Invalid credentials")
except MercuryAPIError as e:
print(f"API error: {e}")
except MercuryError as e:
print(f"Mercury.co.nz error: {e}")
```
## API Methods
The library provides access to all Mercury.co.nz selfservice APIs:
- `get_customer_info()` - Customer information
- `get_accounts()` - Account details
- `get_services()` - Service information
- `get_electricity_meter_info()` - Meter details
- `get_bill_summary()` - Billing information
- `get_electricity_usage()` - Usage data with temperature
- `get_electricity_usage_hourly()` - Hourly usage data
- `get_electricity_usage_monthly()` - Monthly usage data
- `get_electricity_plans()` - Available plans and pricing
- `get_electricity_meter_reads()` - Meter reading history
## Requirements
- Python 3.7+
- `requests>=2.25.0`
## Development
For development, install with optional dependencies:
```bash
pip install pymercury[dev]
```
## Testing
Run the comprehensive test suite:
```bash
python test_mercury_library.py
```
## License
MIT License - see LICENSE file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Support
For support, please open an issue on the GitHub repository.
Raw data
{
"_id": null,
"home_page": null,
"name": "mercury-co-nz-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "mercury, energy, api, oauth, new-zealand, electricity, utilities",
"author": null,
"author_email": "Bertrand Kintanar <bertrand.kintanar@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/02/45/247f50047d2732bc3ce10d20a2b6315875ff758467f81bd2a1ff85937369/mercury_co_nz_api-1.0.2.tar.gz",
"platform": null,
"description": "# PyMercury - Mercury.co.nz Python Library\n\nA comprehensive Python library for interacting with Mercury.co.nz services, including OAuth authentication and selfservice API integration.\n\n## Features\n\n- **OAuth 2.0 PKCE Authentication** - Secure authentication with Mercury.co.nz\n- **Selfservice API Integration** - Access customer, account, and service data\n- **Clean Architecture** - Modular design with separate OAuth and API clients\n- **Type Safety** - Full type hints for better IDE support\n- **Comprehensive Error Handling** - Detailed exceptions for different error scenarios\n- **Flexible Configuration** - Environment variable support with sensible defaults\n\n## Installation\n\n```bash\npip install pymercury\n```\n\n## Quick Start\n\n### Simple Authentication\n\n```python\nfrom pymercury import authenticate\n\n# Get OAuth tokens\ntokens = authenticate(\"your-email@example.com\", \"your-password\")\nprint(f\"Customer ID: {tokens.customer_id}\")\nprint(f\"Access Token: {tokens.access_token}\")\n```\n\n### Complete Account Data\n\n```python\nfrom pymercury import get_complete_data\n\n# Get everything in one call\ndata = get_complete_data(\"your-email@example.com\", \"your-password\")\n\nprint(f\"Customer ID: {data.customer_id}\")\nprint(f\"Account IDs: {data.account_ids}\")\nprint(f\"Electricity Services: {data.service_ids.electricity}\")\nprint(f\"Gas Services: {data.service_ids.gas}\")\nprint(f\"Broadband Services: {data.service_ids.broadband}\")\n```\n\n### Main Client (Recommended)\n\n```python\nfrom pymercury import MercuryClient\n\n# Create client and login\nclient = MercuryClient(\"your-email@example.com\", \"your-password\")\nclient.login()\n\n# Easy access to information\ncustomer_id = client.customer_id\naccount_ids = client.account_ids\nservice_ids = client.service_ids\n\n# Get complete data\ncomplete_data = client.get_complete_account_data()\n```\n\n## Advanced Usage\n\n### Separate OAuth and API Clients\n\n```python\nfrom pymercury.oauth import MercuryOAuthClient\nfrom pymercury.api import MercuryAPIClient\n\n# OAuth authentication only\noauth_client = MercuryOAuthClient(\"email@example.com\", \"password\")\ntokens = oauth_client.authenticate()\n\n# API calls with existing tokens\napi_client = MercuryAPIClient(tokens.access_token)\ncustomer_info = api_client.get_customer_info(tokens.customer_id)\naccounts = api_client.get_accounts(tokens.customer_id)\n```\n\n### Electricity Usage and Billing\n\n```python\nfrom pymercury.api import MercuryAPIClient\n\n# Initialize API client with access token\napi_client = MercuryAPIClient(access_token)\n\n# Get electricity meter information\nmeter_info = api_client.get_electricity_meter_info(customer_id, account_id)\nif meter_info:\n print(f\"Meter Number: {meter_info.meter_number}\")\n print(f\"Meter Type: {meter_info.meter_type}\")\n\n# Get bill summary\nbill_summary = api_client.get_bill_summary(customer_id, account_id)\nif bill_summary:\n print(f\"Current Balance: ${bill_summary.current_balance}\")\n print(f\"Due Date: {bill_summary.due_date}\")\n\n# Get electricity usage (defaults to last 14 days)\nelectricity_usage = api_client.get_electricity_usage(customer_id, account_id, service_id)\nif electricity_usage:\n print(f\"Total Usage: {electricity_usage.total_usage} kWh\")\n print(f\"Average Daily Usage: {electricity_usage.average_daily_usage} kWh\")\n print(f\"Average Temperature: {electricity_usage.average_temperature}\u00b0C\")\n```\n\n## Configuration\n\n### Environment Variables\n\nCreate a `.env` file or set environment variables:\n\n```bash\n# OAuth Configuration\nMERCURY_CLIENT_ID=4c8c2c47-24cd-485d-aad9-12f3d95b3ceb\nMERCURY_REDIRECT_URI=https://myaccount.mercury.co.nz\nMERCURY_BASE_URL=https://login.mercury.co.nz/fc07dca7-cd6a-4578-952b-de7a7afaebdc\nMERCURY_TIMEOUT=20\n\n# API Configuration\nMERCURY_API_BASE_URL=https://apis.mercury.co.nz/selfservice/v1\nMERCURY_API_SUBSCRIPTION_KEY=f62040b20cf9401fb081880cb71c7dec\n```\n\n### Programmatic Configuration\n\n```python\nfrom pymercury import MercuryConfig, MercuryClient\n\nconfig = MercuryConfig(\n client_id=\"your-client-id\",\n api_subscription_key=\"your-api-key\",\n timeout=30\n)\n\nclient = MercuryClient(\"email@example.com\", \"password\", config=config)\n```\n\n## Error Handling\n\n```python\nfrom pymercury import (\n MercuryClient,\n MercuryAuthenticationError,\n MercuryAPIError,\n MercuryError\n)\n\ntry:\n client = MercuryClient(\"email@example.com\", \"password\")\n client.login()\n data = client.get_complete_account_data()\n\nexcept MercuryAuthenticationError:\n print(\"Invalid credentials\")\nexcept MercuryAPIError as e:\n print(f\"API error: {e}\")\nexcept MercuryError as e:\n print(f\"Mercury.co.nz error: {e}\")\n```\n\n## API Methods\n\nThe library provides access to all Mercury.co.nz selfservice APIs:\n\n- `get_customer_info()` - Customer information\n- `get_accounts()` - Account details\n- `get_services()` - Service information\n- `get_electricity_meter_info()` - Meter details\n- `get_bill_summary()` - Billing information\n- `get_electricity_usage()` - Usage data with temperature\n- `get_electricity_usage_hourly()` - Hourly usage data\n- `get_electricity_usage_monthly()` - Monthly usage data\n- `get_electricity_plans()` - Available plans and pricing\n- `get_electricity_meter_reads()` - Meter reading history\n\n## Requirements\n\n- Python 3.7+\n- `requests>=2.25.0`\n\n## Development\n\nFor development, install with optional dependencies:\n\n```bash\npip install pymercury[dev]\n```\n\n## Testing\n\nRun the comprehensive test suite:\n\n```bash\npython test_mercury_library.py\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Support\n\nFor support, please open an issue on the GitHub repository.\n",
"bugtrack_url": null,
"license": null,
"summary": "Python library for Mercury.co.nz OAuth and API integration",
"version": "1.0.2",
"project_urls": {
"Documentation": "https://github.com/bkintanar/pymercury#readme",
"Homepage": "https://github.com/bkintanar/pymercury",
"Issues": "https://github.com/bkintanar/pymercury/issues",
"Repository": "https://github.com/bkintanar/pymercury.git"
},
"split_keywords": [
"mercury",
" energy",
" api",
" oauth",
" new-zealand",
" electricity",
" utilities"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cf3174c7d0de22d53ce0e7422f8869503bf6889f72d6d82c0dde4e83061a1255",
"md5": "4005a494dd8f4aa1a09fd194e41e413f",
"sha256": "c145bdda8396f1cf84417da131456d8025b90ded645fa469289434280624efa0"
},
"downloads": -1,
"filename": "mercury_co_nz_api-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4005a494dd8f4aa1a09fd194e41e413f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 27856,
"upload_time": "2025-07-31T05:09:42",
"upload_time_iso_8601": "2025-07-31T05:09:42.204018Z",
"url": "https://files.pythonhosted.org/packages/cf/31/74c7d0de22d53ce0e7422f8869503bf6889f72d6d82c0dde4e83061a1255/mercury_co_nz_api-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0245247f50047d2732bc3ce10d20a2b6315875ff758467f81bd2a1ff85937369",
"md5": "9a32ed5217f0a05862dd42e3b9005b6f",
"sha256": "8ed754c60cf99ffeb9d3b3a92516bc78194f2504b5d973fa00bdb64a49dd9675"
},
"downloads": -1,
"filename": "mercury_co_nz_api-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "9a32ed5217f0a05862dd42e3b9005b6f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 36443,
"upload_time": "2025-07-31T05:09:43",
"upload_time_iso_8601": "2025-07-31T05:09:43.823353Z",
"url": "https://files.pythonhosted.org/packages/02/45/247f50047d2732bc3ce10d20a2b6315875ff758467f81bd2a1ff85937369/mercury_co_nz_api-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 05:09:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bkintanar",
"github_project": "pymercury#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
}
],
"lcname": "mercury-co-nz-api"
}
JSON
