oilpriceapi 1.0.0__tar.gz

oilpriceapi-1.0.0/.env.example

@@ -0,0 +1,11 @@
+# OilPriceAPI Configuration
+# Copy this file to .env and add your actual values
+
+# Your OilPriceAPI key (required)
+# Get your free API key at: https://oilpriceapi.com
+OILPRICEAPI_KEY=your_api_key_here
+
+# API Base URL (optional)
+# Default: https://api.oilpriceapi.com
+# For local development: http://localhost:5000
+OILPRICEAPI_BASE_URL=https://api.oilpriceapi.com

oilpriceapi-1.0.0/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+All notable changes to the OilPriceAPI Python SDK 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).
+
+## [1.0.0] - 2025-09-29
+
+### Added
+- 🎉 Initial release of OilPriceAPI Python SDK
+- ✅ Synchronous client (`OilPriceAPI`)
+- ✅ Asynchronous client (`AsyncOilPriceAPI`)
+- ✅ Type-safe models with Pydantic
+- ✅ Current price operations (`client.prices.get()`)
+- ✅ Historical data operations (`client.historical.get()`)
+- ✅ Pandas DataFrame integration (`to_dataframe()`)
+- ✅ Visualization module with Tufte-style charts
+- ✅ Automatic retry logic with exponential backoff
+- ✅ Rate limit handling
+- ✅ Comprehensive error handling
+- ✅ Context manager support (`with` statements)
+- ✅ Environment variable configuration
+- ✅ Full type hints for IDE autocomplete
+- ✅ Documentation and examples
+
+### Features
+- **Current Prices**: Get latest commodity prices
+- **Historical Data**: Fetch past prices with flexible date ranges
+- **Multi-commodity**: Support for Brent, WTI, Natural Gas, and more
+- **Pagination**: Automatic handling of large datasets
+- **Data Export**: Convert to pandas DataFrames for analysis
+- **Async Support**: High-performance async/await operations
+- **Visualization**: Built-in charting with matplotlib
+- **Type Safety**: Full Pydantic validation
+
+### Security
+- Environment variable-based API key management
+- No hardcoded credentials
+- HTTPS-only communication
+- Safe error messages that don't leak secrets
+
+### Documentation
+- Comprehensive README with examples
+- API reference documentation
+- Security policy (SECURITY.md)
+- Contributing guidelines (CONTRIBUTING.md)
+- Example scripts and notebooks
+
+### Supported Python Versions
+- Python 3.8+
+- Python 3.9
+- Python 3.10
+- Python 3.11
+- Python 3.12
+
+---
+
+## [Unreleased]
+
+### Planned
+- CLI tool (`oilprice` command)
+- WebSocket support for real-time prices
+- Advanced caching with Redis
+- Technical indicators (RSI, MACD, Bollinger Bands)
+- More visualization styles
+- Jupyter notebook widgets
+
+---
+
+## Release Notes
+
+### How to Upgrade
+
+```bash
+# From PyPI
+pip install --upgrade oilpriceapi
+
+# From source
+pip install -e ".[dev]"
+```
+
+### Breaking Changes
+None - this is the initial release.
+
+### Deprecations
+None.
+
+### Migration Guide
+N/A for initial release.
+
+---
+
+## Links
+- [PyPI Package](https://pypi.org/project/oilpriceapi/)
+- [GitHub Repository](https://github.com/oilpriceapi/python-sdk)
+- [Documentation](https://docs.oilpriceapi.com/sdk/python)
+- [API Documentation](https://docs.oilpriceapi.com)
+- [Website](https://oilpriceapi.com)

oilpriceapi-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,255 @@
+# Contributing to OilPriceAPI Python SDK
+
+Thank you for your interest in contributing! We welcome contributions from the community.
+
+## 🚀 Quick Start
+
+```bash
+# Clone the repository
+git clone https://github.com/oilpriceapi/python-sdk
+cd python-sdk
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install in development mode with all dependencies
+pip install -e ".[dev]"
+
+# Set up your API key
+cp .env.example .env
+# Edit .env and add your OILPRICEAPI_KEY
+
+# Run tests
+pytest
+
+# Format code
+black .
+
+# Type checking
+mypy oilpriceapi
+```
+
+## 📋 Ways to Contribute
+
+### 1. Report Bugs
+
+Found a bug? Please create an issue with:
+- Clear title and description
+- Steps to reproduce
+- Expected vs actual behavior
+- Python version and OS
+- Code sample if applicable
+
+### 2. Suggest Features
+
+Have an idea? Open an issue tagged with `enhancement`:
+- Describe the use case
+- Explain why it's useful
+- Provide examples if possible
+
+### 3. Submit Pull Requests
+
+1. **Fork the repository**
+2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
+3. **Make your changes**
+4. **Add tests** for new functionality
+5. **Update documentation**
+6. **Run tests and linting**
+7. **Commit with clear messages**
+8. **Push and create a Pull Request**
+
+## 🧪 Development Workflow
+
+### Running Tests
+
+```bash
+# All tests
+pytest
+
+# With coverage
+pytest --cov=oilpriceapi --cov-report=html
+
+# Specific test file
+pytest tests/test_client.py
+
+# Specific test
+pytest tests/test_client.py::test_get_price
+```
+
+### Code Quality
+
+```bash
+# Format code
+black oilpriceapi tests
+
+# Lint
+ruff check oilpriceapi tests
+
+# Type check
+mypy oilpriceapi
+
+# Run all checks
+pre-commit run --all-files
+```
+
+### Testing with Local API
+
+```bash
+# Set environment variables
+export OILPRICEAPI_KEY="your_test_key"
+export OILPRICEAPI_BASE_URL="http://localhost:5000"
+
+# Run live tests
+python test_sdk_live.py
+```
+
+## 📐 Code Style
+
+### Python Style Guide
+
+We follow [PEP 8](https://pep8.org/) with these specifics:
+- **Line length**: 100 characters
+- **Formatter**: Black
+- **Linter**: Ruff
+- **Type hints**: Required for all public APIs
+- **Docstrings**: Google style
+
+### Example
+
+```python
+from typing import Optional
+
+def get_price(commodity: str, date: Optional[str] = None) -> float:
+    """Get commodity price.
+
+    Args:
+        commodity: Commodity code (e.g., "BRENT_CRUDE_USD")
+        date: Optional date in YYYY-MM-DD format
+
+    Returns:
+        Price as float
+
+    Raises:
+        DataNotFoundError: If commodity not found
+
+    Example:
+        >>> price = get_price("BRENT_CRUDE_USD")
+        >>> print(f"Oil: ${price:.2f}")
+    """
+    # Implementation
+    pass
+```
+
+## 🔒 Security Guidelines
+
+### Never Commit Secrets
+
+- ❌ API keys in code
+- ❌ Passwords or tokens
+- ❌ Environment files (`.env`)
+- ✅ Use environment variables
+- ✅ Use `.env.example` templates
+
+### Security Checklist
+
+Before committing:
+- [ ] No hardcoded credentials
+- [ ] Added `.env` to `.gitignore`
+- [ ] Sensitive data in environment variables
+- [ ] Error messages don't leak secrets
+- [ ] Input validation added
+
+## 📝 Documentation
+
+### Docstrings Required For:
+- All public classes
+- All public methods/functions
+- Complex private functions
+
+### Update Documentation When:
+- Adding new features
+- Changing APIs
+- Fixing bugs that affect usage
+- Adding examples
+
+## 🧩 Pull Request Process
+
+### PR Checklist
+
+- [ ] Tests pass locally
+- [ ] New tests added for new features
+- [ ] Code formatted with Black
+- [ ] Type hints added
+- [ ] Docstrings updated
+- [ ] CHANGELOG.md updated
+- [ ] No merge conflicts
+- [ ] PR description explains changes
+
+### PR Title Format
+
+Use conventional commits:
+- `feat: add WebSocket support`
+- `fix: handle rate limit headers correctly`
+- `docs: update installation instructions`
+- `test: add integration tests for historical data`
+- `refactor: simplify error handling`
+- `chore: update dependencies`
+
+### Review Process
+
+1. Automated tests run on GitHub Actions
+2. Code review by maintainers
+3. Address feedback
+4. Approval and merge
+
+## 🎯 Development Priorities
+
+### High Priority
+- Bug fixes
+- Security improvements
+- Documentation improvements
+- Test coverage
+
+### Medium Priority
+- New features (with issue discussion)
+- Performance optimizations
+- Examples and tutorials
+
+### Low Priority
+- Code style refactoring
+- Minor optimizations
+
+## 🤝 Community Guidelines
+
+### Be Respectful
+- Assume good intentions
+- Be constructive in feedback
+- Help newcomers
+- Focus on the code, not the person
+
+### Be Collaborative
+- Share knowledge
+- Ask questions
+- Document solutions
+- Give credit
+
+## 📞 Getting Help
+
+- **Questions**: Open a GitHub Discussion
+- **Bugs**: Create an issue
+- **Security**: Email security@oilpriceapi.com
+- **General**: support@oilpriceapi.com
+
+## 📜 License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+## 🎉 Recognition
+
+Contributors will be:
+- Listed in CHANGELOG.md
+- Mentioned in release notes
+- Added to GitHub contributors
+
+Thank you for contributing to OilPriceAPI! 🙏

oilpriceapi-1.0.0/LICENSE

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

oilpriceapi-1.0.0/MANIFEST.in

@@ -0,0 +1,28 @@
+# Include documentation
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+include SECURITY.md
+
+# Include configuration
+include pyproject.toml
+include .env.example
+
+# Include type information
+recursive-include oilpriceapi py.typed
+
+# Exclude unnecessary files
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude __pycache__
+global-exclude .DS_Store
+global-exclude *.so
+
+# Exclude test and development files
+exclude test_sdk_live.py
+exclude generate_*.py
+exclude data_validation_comparison.py
+prune tests
+prune docs/_build
+prune htmlcov

oilpriceapi-1.0.0/PKG-INFO

@@ -0,0 +1,295 @@
+Metadata-Version: 2.4
+Name: oilpriceapi
+Version: 1.0.0
+Summary: Official Python SDK for OilPriceAPI - Real-time and historical oil prices
+Author-email: OilPriceAPI <support@oilpriceapi.com>
+Maintainer-email: OilPriceAPI Team <support@oilpriceapi.com>
+License: MIT License
+        
+        Copyright (c) 2025 OilPriceAPI
+        
+        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.
+Project-URL: Homepage, https://oilpriceapi.com
+Project-URL: Documentation, https://docs.oilpriceapi.com/sdk/python
+Project-URL: Repository, https://github.com/oilpriceapi/python-sdk
+Project-URL: Issues, https://github.com/oilpriceapi/python-sdk/issues
+Project-URL: Changelog, https://github.com/oilpriceapi/python-sdk/blob/main/CHANGELOG.md
+Keywords: oil,prices,api,commodities,energy,brent,wti,natural gas,trading,finance
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+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
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dateutil>=2.8.0
+Requires-Dist: typing-extensions>=4.5.0; python_version < "3.10"
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5.0; extra == "pandas"
+Requires-Dist: numpy>=1.20.0; extra == "pandas"
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.8.0; extra == "async"
+Provides-Extra: cache
+Requires-Dist: redis>=4.5.0; extra == "cache"
+Requires-Dist: cachetools>=5.3.0; extra == "cache"
+Provides-Extra: cli
+Requires-Dist: click>=8.0.0; extra == "cli"
+Requires-Dist: rich>=13.0.0; extra == "cli"
+Provides-Extra: all
+Requires-Dist: oilpriceapi[async,cache,cli,pandas]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.0.261; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Dynamic: license-file
+
+# OilPriceAPI Python SDK
+
+[![PyPI version](https://badge.fury.io/py/oilpriceapi.svg)](https://badge.fury.io/py/oilpriceapi)
+[![Python](https://img.shields.io/pypi/pyversions/oilpriceapi.svg)](https://pypi.org/project/oilpriceapi/)
+[![Tests](https://github.com/oilpriceapi/python-sdk/actions/workflows/test.yml/badge.svg)](https://github.com/oilpriceapi/python-sdk/actions/workflows/test.yml)
+[![Coverage](https://codecov.io/gh/oilpriceapi/python-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/oilpriceapi/python-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+The official Python SDK for [OilPriceAPI](https://oilpriceapi.com) - Real-time and historical oil prices for Brent Crude, WTI, Natural Gas, and more.
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install oilpriceapi
+```
+
+### Basic Usage
+
+```python
+from oilpriceapi import OilPriceAPI
+
+# Initialize client (uses OILPRICEAPI_KEY env var by default)
+client = OilPriceAPI()
+
+# Get latest Brent Crude price
+brent = client.prices.get("BRENT_CRUDE_USD")
+print(f"Brent Crude: ${brent.value:.2f}")
+# Output: Brent Crude: $71.45
+
+# Get multiple prices
+prices = client.prices.get_multiple(["BRENT_CRUDE_USD", "WTI_USD", "NATURAL_GAS_USD"])
+for price in prices:
+    print(f"{price.commodity}: ${price.value:.2f}")
+```
+
+### Historical Data with Pandas
+
+```python
+# Get historical data as DataFrame
+df = client.prices.to_dataframe(
+    commodity="BRENT_CRUDE_USD",
+    start="2024-01-01",
+    end="2024-12-31",
+    interval="daily"
+)
+
+# Add technical indicators
+df = client.analysis.with_indicators(
+    df,
+    indicators=["sma_20", "sma_50", "rsi", "bollinger_bands"]
+)
+
+# Calculate spread between Brent and WTI
+spread = client.analysis.spread("BRENT_CRUDE_USD", "WTI_USD", start="2024-01-01")
+```
+
+## 📊 Features
+
+- ✅ **Simple API** - Intuitive methods for all endpoints
+- ✅ **Type Safe** - Full type hints for IDE autocomplete
+- ✅ **Pandas Integration** - First-class DataFrame support
+- ✅ **Async Support** - High-performance async client
+- ✅ **Smart Caching** - Reduce API calls automatically
+- ✅ **Rate Limit Handling** - Automatic retries with backoff
+- ✅ **Technical Indicators** - Built-in SMA, RSI, MACD, etc.
+- ✅ **CLI Tool** - Command-line interface included
+
+## 📚 Documentation
+
+### Authentication
+
+```python
+# Method 1: Environment variable (recommended)
+export OILPRICEAPI_KEY="your_api_key"
+client = OilPriceAPI()
+
+# Method 2: Direct initialization
+client = OilPriceAPI(api_key="your_api_key")
+
+# Method 3: With configuration
+client = OilPriceAPI(
+    api_key="your_api_key",
+    timeout=30,
+    max_retries=3,
+    cache="memory",
+    cache_ttl=300
+)
+```
+
+### Available Commodities
+
+- `BRENT_CRUDE_USD` - Brent Crude Oil
+- `WTI_USD` - West Texas Intermediate
+- `NATURAL_GAS_USD` - Natural Gas
+- `DIESEL_USD` - Diesel
+- `GASOLINE_USD` - Gasoline
+- `HEATING_OIL_USD` - Heating Oil
+- [View all commodities](https://docs.oilpriceapi.com/commodities)
+
+### Error Handling
+
+```python
+from oilpriceapi.exceptions import OilPriceAPIError, RateLimitError, DataNotFoundError
+
+try:
+    price = client.prices.get("INVALID_CODE")
+except DataNotFoundError as e:
+    print(f"Commodity not found: {e}")
+except RateLimitError as e:
+    print(f"Rate limited. Resets in {e.seconds_until_reset}s")
+except OilPriceAPIError as e:
+    print(f"API error: {e}")
+```
+
+## ⚡ Async Support
+
+```python
+import asyncio
+from oilpriceapi import AsyncOilPriceAPI
+
+async def get_prices():
+    async with AsyncOilPriceAPI() as client:
+        prices = await asyncio.gather(
+            client.prices.get("BRENT_CRUDE_USD"),
+            client.prices.get("WTI_USD"),
+            client.prices.get("NATURAL_GAS_USD")
+        )
+        return prices
+
+# Run async function
+prices = asyncio.run(get_prices())
+```
+
+## 🛠️ CLI Tool
+
+```bash
+# Get current price
+oilprice get BRENT_CRUDE_USD
+
+# Export historical data
+oilprice export WTI_USD --start 2024-01-01 --format csv -o wti_2024.csv
+
+# Watch prices in real-time
+oilprice watch BRENT_CRUDE_USD --interval 60
+```
+
+## 🧪 Testing
+
+The SDK includes utilities for testing your applications:
+
+```python
+from oilpriceapi.testing import MockClient
+
+def test_my_strategy():
+    client = MockClient()
+    client.set_price("BRENT_CRUDE_USD", 75.50)
+
+    result = my_trading_strategy(client)
+    assert result.action == "BUY"
+```
+
+## 📈 Examples
+
+Check out the [examples/](examples/) directory for:
+- [Quickstart Notebook](examples/quickstart.ipynb)
+- [Data Analysis](examples/data_analysis.ipynb)
+- [Trading Signals](examples/trading_signals.ipynb)
+- [Async Operations](examples/async_example.py)
+
+## 🔧 Development
+
+```bash
+# Clone repository
+git clone https://github.com/oilpriceapi/python-sdk
+cd python-sdk
+
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Format code
+black .
+
+# Type checking
+mypy oilpriceapi
+```
+
+## 📝 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## 💬 Support
+
+- 📧 Email: support@oilpriceapi.com
+- 🐛 Issues: [GitHub Issues](https://github.com/oilpriceapi/python-sdk/issues)
+- 📖 Docs: [Documentation](https://docs.oilpriceapi.com/sdk/python)
+
+## 🔗 Links
+
+- [OilPriceAPI Website](https://oilpriceapi.com)
+- [API Documentation](https://docs.oilpriceapi.com)
+- [Pricing](https://oilpriceapi.com/pricing)
+- [Status Page](https://status.oilpriceapi.com)
+
+---
+
+Made with ❤️ by the OilPriceAPI Team