Contributing to OilPriceAPI Python SDK

September 29, 2025 · View on GitHub

Thank you for your interest in contributing! We welcome contributions from the community.

🚀 Quick Start

# 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

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Add tests for new functionality
Update documentation
Run tests and linting
Commit with clear messages
Push and create a Pull Request

🧪 Development Workflow

Running Tests

# 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

# 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

# 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 with these specifics:

Line length: 100 characters
Formatter: Black
Linter: Ruff
Type hints: Required for all public APIs
Docstrings: Google style

Example

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