Contributing

We welcome contributions to Popcat.py! Here’s how you can help.

Development Setup

Prerequisites

Python 3.7 or higher
Git

Setting up the development environment

Fork and clone the repository:

git clone https://github.com/LandWarderer2772/pop-wrapper.git
cd pop-wrapper

Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install in development mode:
```
pip install -e .[dev]
```
Install pre-commit hooks (optional but recommended):
```
pre-commit install
```

Making Changes

Code Style

We use several tools to maintain code quality:

Black for code formatting
flake8 for linting
mypy for type checking
pytest for testing

Run these before submitting:

black popcat/ tests/
   flake8 popcat/ tests/
   pytest

Adding New Endpoints

When the Popcat API adds new endpoints, here’s how to add them:

Choose the appropriate module based on the endpoint’s purpose:
- image.py - Image manipulation
- meme.py - Meme generation
- data.py - Data/information APIs
- text.py - Text utilities
- random.py - Random content
- utilities.py - General utilities
Implement the function following the existing pattern:

def new_endpoint(parameter: str) -> str:
    """
    Description of what this endpoint does.
    
    Args:
        parameter (str): Description of parameter
        
    Returns:
        str: Description of return value
        
    Raises:
        ValueError: If parameter is invalid
        Exception: If API request fails
        
    Example:
        >>> result = new_endpoint("example")
        >>> print(result)
        Expected output
    """
    _validate_text(parameter)  # Use appropriate validation
    return _make_request("/new-endpoint", {"param": parameter})

Add the function to __all__ in the module
Add it to the main __init__.py imports
Write tests in the appropriate test file
Update documentation in the README

ONLY ADD ENPOINTS THAT ARE STABLE AND DOCUMENTED IN THE OFFICIAL POPCAT API DOCS

Writing Tests

All new functions should have tests. Use the existing test structure:

@responses.activate
def test_new_function(self):
    """Test new function with valid input."""
    responses.add(
        responses.GET,
        "https://api.popcat.xyz/new-endpoint",
        json={"result": "expected"},
        status=200
    )
    
    result = module.new_function("test_input")
    assert isinstance(result, dict)
    assert "result" in result

def test_new_function_invalid_input(self):
    """Test new function with invalid input."""
    with pytest.raises(ValueError, match="Input must be valid"):
        module.new_function("")

Documentation

When adding new features:

Add comprehensive docstrings with examples
Update the README with new functions
Add to the docs if needed
Include usage examples

Testing

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/test_image.py

# Run with coverage
pytest --cov=popcat

# Run integration tests (requires internet)
pytest tests/integration/ -m integration

Test Categories

Unit tests: Test individual functions with mocked responses
Integration tests: Test actual API calls (run manually)
Error handling tests: Test validation and error cases

Writing Integration Tests

For integration tests (that make real API calls):

import pytest

@pytest.mark.integration
def test_weather_integration():
    """Integration test - makes real API call."""
    result = popcat.weather("London")
    assert isinstance(result, dict)
    assert "temperature" in result

Run integration tests with: pytest -m integration

Submitting Changes

Pull Request Process

Create a feature branch:

git checkout -b feature/add-new-endpoint

Make your changes following the guidelines above

Test your changes:

pytest tests/
black popcat/ tests/
flake8 popcat/ tests/

Commit with clear messages:

git add .
git commit -m "Add support for new endpoint"

Push and create a pull request:

git push origin feature/add-new-endpoint

Pull Request Guidelines

Clear title and description
Reference any related issues
Include tests for new functionality
Update documentation as needed
Ensure all checks pass

Commit Message Format

Use clear, descriptive commit messages:

Add weather endpoint support

- Implement weather() function in data.py
- Add comprehensive error handling
- Include tests and documentation
- Update README with usage examples

Fixes #123

Reporting Issues

Bug Reports

When reporting bugs, please include:

Python version
Package version
Minimal code to reproduce
Expected vs actual behavior
Error messages/tracebacks

Feature Requests

For new features:

Describe the use case
Explain the expected behavior
Provide examples if possible
Consider backwards compatibility

Release Process

For maintainers:

Update version in pyproject.toml and __init__.py
Update CHANGELOG.md
Create a release tag
Build and upload to PyPI:
```
python -m build
twine upload dist/*
```

Getting Help

Open an issue: For bugs or feature requests on GitHub
Discord: Contact land_lmao
Email: mh3as81gb@mozmail.com

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Recognition

Contributors will be:

Listed in CONTRIBUTORS.md
Mentioned in release notes
Given credit in documentation

Thank you for contributing to pop-wrapper! 🎉