ukfuelfinder 1.0.0__py3-none-any.whl

ukfuelfinder-1.0.0.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: ukfuelfinder
+Version: 1.0.0
+Summary: Python library for accessing the UK Government Fuel Finder API
+Home-page: https://github.com/mretallack/ukfuelfinder
+Author: Mark Retallack
+Author-email: Mark Retallack <mark@retallack.org.uk>
+License: MIT
+Project-URL: Homepage, https://github.com/mretallack/ukfuelfinder
+Project-URL: Documentation, https://github.com/mretallack/ukfuelfinder/blob/main/README.md
+Project-URL: Repository, https://github.com/mretallack/ukfuelfinder
+Project-URL: Issues, https://github.com/mretallack/ukfuelfinder/issues
+Keywords: fuel,prices,uk,government,api,petrol,diesel
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: python-dateutil>=2.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Requires-Dist: vcrpy>=4.2.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# UK Fuel Finder Python Library
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+Python library for accessing the UK Government Fuel Finder API.
+
+## Features
+
+- **OAuth 2.0 Authentication** - Automatic token management with refresh support
+- **Comprehensive Data Access** - Fuel prices and forecourt information
+- **Built-in Caching** - Reduces API calls with configurable TTL
+- **Rate Limiting** - Automatic retry with exponential backoff
+- **Type Hints** - Full type annotations for better IDE support
+- **Extensive Error Handling** - Clear exceptions for all error cases
+- **Batch Pagination** - Automatic handling of 500-record batches
+- **Incremental Updates** - Fetch only changed data since a specific date
+
+## Installation
+
+```bash
+pip install ukfuelfinder
+```
+
+## Quick Start
+
+```python
+from ukfuelfinder import FuelFinderClient
+
+# Initialize client
+client = FuelFinderClient(
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+    environment="production"  # or "test"
+)
+
+# Get all fuel prices
+prices = client.get_all_pfs_prices()
+
+# Search for stations near a location (returns list of (distance, PFSInfo) tuples)
+nearby = client.search_by_location(latitude=51.5074, longitude=-0.1278, radius_km=5.0)
+for distance, station in nearby:
+    print(f"{distance:.2f}km - {station.trading_name}")
+
+# Get prices for specific fuel type
+unleaded_prices = client.get_prices_by_fuel_type("unleaded")
+
+# Get forecourt information
+forecourts = client.get_all_pfs_info()
+
+# Get incremental updates since yesterday
+from datetime import datetime, timedelta
+yesterday = (datetime.now() - timedelta(days=1)).strftime("%Y-%m-%d")
+updated_prices = client.get_incremental_price_updates(yesterday)
+```
+
+## Environment Variables
+
+Set credentials via environment variables:
+
+```bash
+export FUEL_FINDER_CLIENT_ID="your_client_id"
+export FUEL_FINDER_CLIENT_SECRET="your_client_secret"
+export FUEL_FINDER_ENVIRONMENT="production"
+```
+
+Then initialize without parameters:
+
+```python
+client = FuelFinderClient()
+```
+
+## Documentation
+
+- [Quick Start Guide](docs/quickstart.md)
+- [API Reference](docs/api_reference.md)
+- [Authentication](docs/authentication.md)
+- [Caching Guide](docs/caching.md)
+- [Rate Limiting](docs/rate_limiting.md)
+- [Error Handling](docs/error_handling.md)
+
+## Requirements
+
+- Python 3.8+
+- Valid Fuel Finder API credentials from [developer.fuel-finder.service.gov.uk](https://www.developer.fuel-finder.service.gov.uk)
+
+## API Coverage
+
+This library provides access to all Information Recipient API endpoints:
+
+- **Authentication**
+  - Generate OAuth access token
+  - Refresh access token
+  
+- **Fuel Prices**
+  - Fetch all PFS fuel prices (full or incremental)
+  
+- **Forecourt Information**
+  - Fetch all PFS information (500 per batch)
+  - Fetch incremental PFS information updates
+
+## Examples
+
+See the [examples/](examples/) directory for complete working examples:
+
+- `basic_usage.py` - Simple getting started example
+- `error_handling.py` - Comprehensive error handling
+- `fetch_fuel_prices.py` - Fetch all fuel prices and save to JSON
+- `fetch_all_sites.py` - Fetch all forecourt sites and save to JSON
+- `location_search.py` - Search for stations near a location
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/mretallack/ukfuelfinder.git
+cd ukfuelfinder
+pip install -e .[dev]
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Code Quality
+
+```bash
+black ukfuelfinder tests
+mypy ukfuelfinder
+flake8 ukfuelfinder
+```
+
+## Future Enhancements
+
+Potential features for future development:
+
+### Smart Fuel Recommendations
+- **Cost-optimized routing** - Calculate total fuel cost including detour distance based on vehicle consumption
+- **Cheapest fuel finder** - Find the most economical option considering current location, fuel prices, and distance
+- **Route integration** - Suggest fuel stops along planned routes with minimal detour
+
+### Price Intelligence
+- **Price alerts** - Notify users when prices drop below a threshold in their area
+- **Price forecasting** - Predict price trends based on historical data
+- **Price comparison** - Compare prices across brands, regions, and fuel types
+
+### Advanced Filtering
+- **Multi-criteria search** - Filter by amenities (car wash, shop, 24-hour, EV charging)
+- **Brand preferences** - Filter by preferred fuel brands or loyalty programs
+- **Fuel type availability** - Find stations with specific fuel types (HVO, E10, premium diesel)
+
+### Journey Planning
+- **Fuel range calculator** - Estimate remaining range and suggest refuel points
+- **Multi-stop optimization** - Plan optimal fuel stops for long journeys
+- **Emergency fuel finder** - Quick search for nearest station when running low
+
+### Data Analytics
+- **Spending tracking** - Monitor fuel expenses over time
+- **Savings calculator** - Calculate savings from using cheapest stations
+- **Regional price analysis** - Compare average prices across different areas
+
+### Integration Features
+- **Navigation app integration** - Direct routing to selected stations
+- **Calendar integration** - Schedule reminders for regular refueling
+- **Vehicle integration** - Sync with vehicle telematics for automatic consumption data
+
+Contributions implementing these features are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Data provided by the UK Government Fuel Finder service
+- API documentation: [developer.fuel-finder.service.gov.uk](https://www.developer.fuel-finder.service.gov.uk)
+- Content available under [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/)
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/mretallack/ukfuelfinder/issues)
+- **API Support**: [Contact Fuel Finder Team](https://www.developer.fuel-finder.service.gov.uk/contact-us)
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.

ukfuelfinder-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+ukfuelfinder/__init__.py,sha256=4mBkb1BS8xueCspJnmWZxZm01Wa3bLLSz2uTS41fr2U,934
+ukfuelfinder/auth.py,sha256=6AmtMYx-pVCn8mPYLK6Yoe5VvqEXXh8glLNbwuol51M,3898
+ukfuelfinder/cache.py,sha256=1ykMcoeN7IpF06rzckO2vwpJ--KhUQBj5H4ZB9vrSV4,2137
+ukfuelfinder/client.py,sha256=nM_w6SRCnFBU5tkzrJsifhpuqLoLts7axcpi04KNStc,8371
+ukfuelfinder/config.py,sha256=yMGhA_QdrLr7jHJUlSaC4YrQCvh54Ar8egwsQXWn7FQ,1957
+ukfuelfinder/exceptions.py,sha256=WQiGGmTmKmAiDETmB4lpz2Z_DpaibsBOeu9pc8sbYwA,1498
+ukfuelfinder/http_client.py,sha256=SHolFT_jK9chW6V5_6OzxxvP3rmhQKnH_u89_qcL2jg,3985
+ukfuelfinder/models.py,sha256=YWmoLjL3KtLJPLI0JirZe6y_3L5eKPCVrjknHfqSIPo,4999
+ukfuelfinder/rate_limiter.py,sha256=NYzmBg-nROBfGlmn8VjTKnQVstvEmTql8QlLKS3CCFE,2444
+ukfuelfinder/services/__init__.py,sha256=ujoAV7UmaaNJ_QkjbDZLUxsZzf8h57vr__p_HipVECc,39
+ukfuelfinder/services/forecourt_service.py,sha256=7BuCtq9qn09Ag8-vO10S506RWjCQ-rQYQBOxfmVHrl0,3440
+ukfuelfinder/services/price_service.py,sha256=bu8XVEBONC6nRAjBQy9Ap96O79QekJDz947LIs51xik,2523
+ukfuelfinder-1.0.0.dist-info/licenses/LICENSE,sha256=aQgSJtjyyzMWO0tnA-Knf0cTfXueFg3slv94MUzPG5M,1071
+ukfuelfinder-1.0.0.dist-info/METADATA,sha256=lBMaKm3zV49WQTo_TkwHuusSrSOdoYNB0wzvS2Ipwj8,7899
+ukfuelfinder-1.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+ukfuelfinder-1.0.0.dist-info/top_level.txt,sha256=ht_7huZLUphB5LbYIUu-Fax1YSmalproqtvOwnHkdXs,13
+ukfuelfinder-1.0.0.dist-info/RECORD,,

ukfuelfinder-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ukfuelfinder-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Retallack
+
+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.

ukfuelfinder-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ukfuelfinder