valopy 0.1.0

An async Python wrapper for the unofficial Valorant API

Valopy

An async Python wrapper for the unofficial Valorant API created by Henrik-3.

Documentation • PyPI • Issues • Discussions

Note: ValoPy is an unofficial wrapper. It is not affiliated with or endorsed by Riot Games. Use at your own risk and ensure compliance with the unofficial Valorant API's terms of service.

About

ValoPy provides a simple, type-safe, and async-first interface to interact with the unofficial Valorant API. It abstracts away the complexity of HTTP requests and JSON parsing, allowing you to focus on building your application.

Features

• ✅ Async/Await First: Built with asyncio for efficient asynchronous operations
• ✅ Full Type Hints: 100% typed for better IDE support and type checking with tools like Pylance
• ✅ Comprehensive Models: Well-structured data models for all API responses with proper validation
• ✅ Error Handling: Custom exception classes for different error scenarios
• ✅ Performance Optimized: Session pooling and lazy logging for efficient operations
• ✅ Easy to Use: Intuitive Pythonic interface following async best practices
• ✅ Well Documented: Comprehensive documentation with 15+ examples and guides
• ✅ Fully Tested: 45 integration tests covering all endpoints (100% passing)

Requirements

• Python 3.14+ (uses modern Python features including type hints and async/await)
• aiohttp 3.13+ for async HTTP requests

Installation

From PyPI (recommended)

pip install valopy

From Source

git clone https://github.com/Vinc0739/valopy.git
cd valopy
pip install -e .

Quick Start

1. Get an API Key

First, you'll need an API key for the unofficial Valorant API:

1. Join the HenrikDev Discord Server
2. Use the key generation commands to get a Basic or Advanced key
3. For more information, see the API Backend Documentation

2. Use ValoPy

import asyncio
from valopy import Client

async def main():
    async with Client(api_key="your-api-key") as client:
        # Get account information
        account = await client.get_account_v1("PlayerName", "TAG")
        print(f"Account Level: {account.account_level}")
        print(f"Region: {account.region}")
        
        # Get match history
        matches = await client.get_match_history_v2("player-uuid", "NA")
        print(f"Total Matches: {len(matches.history)}")

asyncio.run(main())

Documentation

Full documentation is available at: https://valopy.readthedocs.io

Local Documentation

To build and view documentation locally:

# Install documentation dependencies
pip install -e ".[docs]"

# Build documentation
cd docs
uv run make html

# Open in browser
open build/html/index.html  # macOS
# or
start build\html\index.html  # Windows
# or
xdg-open build/html/index.html  # Linux

Key Documentation Pages

• Getting Started
• API Reference
• Examples
• About the API Backend
• FAQ
• Troubleshooting

Examples

Basic Examples

• Account Information - Fetch basic account data
• Content Data - Get game content with localization
• Error Handling - Proper error handling patterns

Advanced Examples

• Batch Requests - Efficiently make multiple requests
• MMR History - Analyze rating progression
• Advanced Error Handling - Comprehensive error management

See the examples/ directory for all available examples.

Development

Setup

1. Clone the repository:

git clone https://github.com/Vinc0739/valopy.git
cd valopy

2. Install in development mode with all dependencies:

pip install -e ".[dev,docs]"

3. Activate the virtual environment (if using venv):

# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=valopy

# Run specific test file
pytest tests/unit/test_client.py

# Run with verbose output
pytest -v

Code Quality

# Format code with Black
black valopy/ tests/

# Check types with Pylance
# (configured in VS Code)

# Lint with Ruff
ruff check valopy/ tests/

# Fix linting issues automatically
ruff check --fix valopy/ tests/

Building Documentation

cd docs
uv run make clean html
open build/html/index.html

Contributing

We welcome contributions! Whether it's bug reports, feature requests, or code contributions, your help makes ValoPy better.

Before You Start

1. Check existing issues - Please search for existing issues/PRs before creating new ones
2. Read the guidelines - Review the contribution guidelines below
3. Follow the code style - Use Black, Ruff, and type hints (see Code Quality section)
4. Write tests - All new features must include tests

Getting Started with Contributions

1. Fork the repository on GitHub
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Install development dependencies: pip install -e ".[dev,docs]"
4. Make your changes following our code style
5. Add tests for your changes
6. Run the test suite: pytest
7. Commit with clear messages: git commit -m "Add feature: description"
8. Push to your fork: git push origin feature/your-feature-name
9. Open a Pull Request with a clear description

Code Style

• Python Version: 3.14+
• Formatter: Black with 120 character line length
• Linter: Ruff
• Type Hints: 100% coverage required - use Pylance
• Docstrings: NumPy style with type hints

Code Style Example

def example_function(param1: str, param2: int) -> dict[str, int]:
    """
    Brief description of the function.

    Parameters
    ----------
    param1 : str
        Description of param1
    param2 : int
        Description of param2

    Returns
    -------
    dict[str, int]
        Description of return value

    Raises
    ------
    ValueError
        When param2 is negative
    """
    if param2 < 0:
        raise ValueError("param2 must be non-negative")
    
    return {param1: param2}

Pull Request Guidelines

1. Clear Title: [Feature/Fix/Docs] Brief description
2. Descriptive Description: Explain what and why, not just what changed
3. Reference Issues: Use Closes #123 if fixing an issue
4. Test Coverage: Include tests for new functionality
5. Documentation: Update docstrings and docs if needed
6. Changelog: Mention breaking changes clearly

Example PR Description

## Description
Fixes #123 - Add support for fetching competitive rank data

## Changes
- Added `get_competitive_rank()` method to Client
- Added `CompetitiveRank` model with proper type hints
- Updated documentation with new endpoint

## Testing
- Added 3 new tests in `test_rank.py`
- All 45 existing tests still pass

## Breaking Changes
None

## Checklist
- [x] Tests pass
- [x] Code follows style guide
- [x] Documentation updated
- [x] No new warnings

Reporting Bugs

When reporting bugs, please include:

1. Python version: python --version
2. ValoPy version: pip show valopy
3. Reproduction steps: Clear steps to reproduce the issue
4. Expected behavior: What should happen
5. Actual behavior: What actually happened
6. Error message: Full traceback if applicable
7. System info: OS, environment details

Feature Requests

For feature requests, please describe:

1. Use case: Why is this feature needed?
2. Proposed solution: How should it work?
3. Alternatives: Any alternative approaches you considered?

Testing

ValoPy includes a comprehensive test suite with 45 integration tests covering all API endpoints.

# Run tests
pytest

# Run with coverage report
pytest --cov=valopy --cov-report=html

# Run specific test
pytest tests/unit/test_client.py::test_get_account_v1

Test files are organized by endpoint:

• tests/unit/test_account.py - Account endpoints
• tests/unit/test_content.py - Content endpoints
• tests/unit/test_match.py - Match endpoints
• And more...

Performance

ValoPy is optimized for performance:

• Session Pooling: Reuses HTTP connections for better performance
• Lazy Logging: Minimal overhead when not logging
• Connection Management: Automatic lifecycle management via context managers
• Type Hints: No runtime type checking overhead

Benchmarks show 20-40% improvement over naive implementations.

API Limitations

The unofficial Valorant API has rate limits:

• Basic Key: 30 requests/minute
• Advanced Key: 90 requests/minute
• Custom Keys: Available for larger projects (see API Backend Docs)

License

MIT License - See LICENSE file for details

Copyright © 2025 Vinc0739

Credits

Acknowledgments

• Henrik-3 - Creator and maintainer of the unofficial Valorant API
• Contributors: Thanks to all who have contributed to this project
• Community: Thanks to the Valorant development community

Related Projects

• Unofficial Valorant API - The underlying API
• Valorant API Documentation - API endpoint documentation
• ValorantAPI.py - Another Python wrapper

Support

Getting Help

• 📚 Documentation: https://valopy.readthedocs.io
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 🤖 API Support: HenrikDev Discord

Status & Updates

• API Status: https://status.henrikdev.xyz
• Check the Changelog for updates

Legal

ValoPy and its creator are not affiliated with, endorsed by, or connected to Riot Games, Inc. or any of its subsidiaries or affiliates. Riot Games, and all associated properties are trademarks or registered trademarks of Riot Games, Inc.

This project is provided "as-is" without any guarantees. Use at your own risk and comply with all applicable terms of service.

Changelog

See CHANGELOG.md for version history and updates.

---

⬆ back to top

Made with ❤️ by Vinc0739

MIT