Contributing to APIFromAnything

Thank you for your interest in contributing to APIFromAnything! This document provides guidelines and instructions for contributing to the project.

Code of Conduct

Please read and follow our Code of Conduct to ensure a positive and inclusive environment for everyone.

Getting Started

Prerequisites

Python 3.7 or higher
Git
A GitHub account

Setting Up the Development Environment

Fork the repository:

Go to the APIFromAnything repository and click the “Fork” button in the top-right corner.

Clone your fork:

git clone https://github.com/YOUR_USERNAME/apifrom.git
cd apifrom

Create a virtual environment:

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

Install development dependencies:
```
pip install -e ".[dev]"
```
Set up pre-commit hooks:
```
pre-commit install
```

Development Workflow

Creating a Branch

Create a new branch for your changes:

git checkout -b feature/your-feature-name

Use a descriptive name for your branch that reflects the changes you’re making.

Making Changes

Make your changes to the codebase.
Write tests for your changes.
Run the tests to make sure they pass:
```
pytest
```
Run the linters to ensure code quality:
```
black .
flake8
mypy .
```

Committing Changes

Stage your changes:
```
git add .
```
Commit your changes with a descriptive message:
```
git commit -m "Add feature: your feature description"
```
Follow the Conventional Commits specification for your commit messages:
- feat: A new feature
- fix: A bug fix
- docs: Documentation changes
- style: Changes that do not affect the meaning of the code (formatting, etc.)
- refactor: Code changes that neither fix a bug nor add a feature
- perf: Code changes that improve performance
- test: Adding or modifying tests
- chore: Changes to the build process or auxiliary tools

Push your changes to your fork:

git push origin feature/your-feature-name

Creating a Pull Request

Go to the APIFromAnything repository and click the “New pull request” button.
Click “compare across forks” and select your fork and branch.
Fill out the pull request template with a description of your changes.
Submit the pull request.

Pull Request Guidelines

Keep pull requests focused on a single feature or bug fix.
Make sure all tests pass.
Make sure the code passes all linters.
Update documentation if necessary.
Add tests for new features or bug fixes.
Follow the code style of the project.
Be responsive to feedback and questions.

Code Style

APIFromAnything follows the Black code style. We also use Flake8 for linting and MyPy for type checking.

Imports

Organize imports in the following order:

Standard library imports
Related third-party imports
Local application/library specific imports

Within each group, imports should be sorted alphabetically.

# Standard library imports
import asyncio
import json
import os
from typing import Dict, List, Optional

# Third-party imports
import jwt
import pydantic
import requests

# Local imports
from apifrom.core import app
from apifrom.middleware import Middleware

Docstrings

Use Google-style docstrings:

def function_with_types_in_docstring(param1, param2):
    """Example function with types documented in the docstring.

    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.

    Returns:
        bool: The return value. True for success, False otherwise.

    Raises:
        ValueError: If param1 is negative.
    """
    if param1 < 0:
        raise ValueError("param1 must be positive")
    return param1 > len(param2)

Type Hints

Use type hints for function parameters and return values:

def greeting(name: str) -> str:
    return f"Hello, {name}!"

Testing

APIFromAnything uses pytest for testing. All new features and bug fixes should include tests.

Running Tests

# Run all tests
pytest

# Run tests with coverage
pytest --cov=apifrom

# Run a specific test file
pytest tests/test_file.py

# Run a specific test
pytest tests/test_file.py::test_function

Writing Tests

Test files should be named test_*.py.
Test functions should be named test_*.
Use descriptive names for test functions.
Use fixtures for common setup and teardown.
Use parameterized tests for testing multiple inputs.
Use mocking for external dependencies.

Example:

import pytest
from apifrom import API, api
from apifrom.testing import TestClient

@pytest.fixture
def app():
    app = API()
    
    @api(route="/hello/{name}", method="GET")
    def hello(name: str):
        return {"message": f"Hello, {name}!"}
    
    return app

@pytest.fixture
def client(app):
    return TestClient(app)

def test_hello(client):
    response = client.get("/hello/World")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello, World!"}

Documentation

APIFromAnything uses Sphinx for documentation. All new features should include documentation.

Building Documentation

cd docs
make html

The documentation will be built in the docs/_build/html directory.

Writing Documentation

Use Markdown for documentation files.
Use code blocks for code examples.
Use admonitions for notes, warnings, and tips.
Use cross-references for linking to other parts of the documentation.
Use tables for structured data.

Reporting Bugs

If you find a bug, please report it by creating an issue on the GitHub repository.

When reporting a bug, please include:

A clear and descriptive title
Steps to reproduce the bug
Expected behavior
Actual behavior
Screenshots or code snippets if applicable
Environment information (OS, Python version, APIFromAnything version)

Requesting Features

If you have an idea for a new feature, please create an issue on the GitHub repository.

When requesting a feature, please include:

A clear and descriptive title
A detailed description of the feature
Why the feature would be useful
Examples of how the feature would be used
Any relevant references or resources

Release Process

APIFromAnything follows Semantic Versioning. The release process is as follows:

Update the version number in pyproject.toml and __init__.py.
Update the changelog with the new version and changes.
Create a new release on GitHub with the version number as the tag.
Publish the new version to PyPI.

Community

Join our community to get help, share ideas, and contribute to the project:

License

By contributing to APIFromAnything, you agree that your contributions will be licensed under the MIT License.