Metadata-Version: 2.4
Name: marvelpy
Version: 0.2.0
Summary: A fully-typed Python client for the Marvel Comics API.
Author-email: Jeff Granof <jlgranof@icloud.com>
Maintainer-email: Jeff Granof <jlgranof@icloud.com>
License: MIT
Project-URL: Homepage, https://github.com/jlgranof/marvelpy
Project-URL: Documentation, https://jlgranof.github.io/marvelpy/
Project-URL: Issue Tracker, https://github.com/jlgranof/marvelpy/issues
Keywords: marvel,api,comics,client,async,typed
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.23.0
Requires-Dist: pydantic>=1.10.0
Requires-Dist: typing-extensions>=4.9.0
Requires-Dist: click>=8.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: respx>=0.20.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: mkdocs-material>=9.0.0; extra == "dev"
Requires-Dist: mkdocs-gen-files>=0.5.0; extra == "dev"
Requires-Dist: mkdocs-literate-nav>=0.6.0; extra == "dev"
Requires-Dist: mkdocs-section-index>=0.3.0; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.20.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: httpx>=0.23.0; extra == "dev"
Requires-Dist: pydantic>=1.10.0; extra == "dev"
Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.10.0; extra == "test"
Requires-Dist: respx>=0.20.0; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
Requires-Dist: mkdocs-gen-files>=0.5.0; extra == "docs"
Requires-Dist: mkdocs-literate-nav>=0.6.0; extra == "docs"
Requires-Dist: mkdocs-section-index>=0.3.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.20.0; extra == "docs"
Requires-Dist: mike>=1.1.0; extra == "docs"

# Marvelpyelleng
ell

[![PyPI version](https://badge.fury.io/py/marvelpy.svg)](https://badge.fury.io/py/marvelpy)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://jlgranof.github.io/marvelpy/)

A fully-typed Python client for the Marvel Comics API.

## Features

- 🚀 **Async-first design** - Built with modern async/await patterns
- 🔒 **Fully typed** - Complete type hints for better IDE support
- 📚 **Comprehensive** - Full coverage of the Marvel Comics API
- 🛡️ **Enterprise-ready** - Production-grade error handling and retry logic
- 📖 **Well documented** - Extensive documentation and examples

## Quick Start

### Installation

```bash
pip install marvelpy
```

### Basic Usage

```python
import asyncio
from marvelpy import MarvelClient

async def main():
    async with MarvelClient("your_public_key", "your_private_key") as client:
        # Get characters
        characters = await client.get_characters(params={"limit": 5})
        print(f"Found {characters['data']['count']} characters")
        
        # Search for specific characters
        iron_man = await client.get_characters(params={"name": "iron man"})
        print(f"Iron Man: {iron_man['data']['results'][0]['name']}")

asyncio.run(main())
```

## What's Available

Currently, Marvelpy v0.2.0 includes:

- **MarvelClient** - Full-featured async client for Marvel API
- **Authentication** - Automatic Marvel API authentication
- **Character Access** - Search and retrieve character information
- **Error Handling** - Robust retry logic and error management
- **Type Safety** - Complete type hints throughout
- **Test Suite** - Comprehensive tests with 85% coverage
- **Documentation** - Full API documentation with examples

## Coming Soon

Future versions will include:

- **Comics** - Access comic book data and metadata
- **Events** - Marvel universe events and storylines
- **Series** - Comic series information
- **Stories** - Individual story details
- **Creators** - Creator and artist information
- **Advanced Search** - More sophisticated filtering options
- **Caching** - Built-in response caching
- **Rate Limiting** - Automatic rate limit management

## Current Usage Examples

```python
import asyncio
from marvelpy import MarvelClient

async def main():
    async with MarvelClient("your_public_key", "your_private_key") as client:
        # Get all characters (with pagination)
        characters = await client.get_characters(params={"limit": 10})
        
        # Search for specific characters
        heroes = await client.get_characters(params={"name": "iron man"})
        
        # Get character by ID
        character = await client.get("characters/1009368")
        
        # Health check
        status = await client.health_check()

asyncio.run(main())
```

## Requirements

- Python 3.8 or higher
- httpx>=0.23.0
- pydantic>=1.10.0
- typing-extensions>=4.9.0
- click>=8.1.0

## Development

### Setup

```bash
git clone https://github.com/jlgranof/marvelpy.git
cd marvelpy
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
```

### Testing

```bash
pytest
pytest --cov=marvelpy --cov-report=html
```

### Documentation

```bash
mkdocs serve  # Serve docs locally
mkdocs build  # Build docs
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](https://jlgranof.github.io/marvelpy/contributing/) for details.

## Documentation

- 📖 [Full Documentation](https://jlgranof.github.io/marvelpy/)
- 🚀 [Quick Start Guide](https://jlgranof.github.io/marvelpy/quickstart/)
- 📚 [API Reference](https://jlgranof.github.io/marvelpy/api/hello/)
- 🔧 [Installation Guide](https://jlgranof.github.io/marvelpy/installation/)

## License

This project is licensed under the MIT License.

## Links

- **PyPI**: https://pypi.org/project/marvelpy/
- **GitHub**: https://github.com/jlgranof/marvelpy
- **Documentation**: https://jlgranof.github.io/marvelpy/
- **Issues**: https://github.com/jlgranof/marvelpy/issues

---

**Note**: This package is actively developed. Version 0.2.0 includes a fully functional MarvelClient with character access, authentication, and comprehensive error handling. More endpoints and features are coming in future versions!
