Development Guide¶

This guide covers setting up the development environment, code quality standards, and contribution workflow for the ReZEN Python client.

🚀 Quick Start¶

Prerequisites¶

Python 3.8+ (recommended: Python 3.12)
pip or poetry for dependency management
Git

Development Setup¶

Clone the repository:

git clone https://github.com/theperrygroup/rezen.git
cd rezen

Set up virtual environment:

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

Install development dependencies:
```
pip install -r requirements-dev.txt
```

Install pre-commit hooks (recommended):

pip install pre-commit
pre-commit install

Set up environment variables:

echo "REZEN_API_KEY=your_api_key_here" > .env

🔧 Code Quality Standards¶

Formatting and Linting¶

This project enforces strict code quality standards:

Black: Code formatting (line length: 88)
isort: Import sorting (compatible with Black)
flake8: Linting and style checking
mypy: Static type checking
pytest: Testing framework

Running Quality Checks¶

# Format code
black rezen tests
isort rezen tests

# Lint code
flake8 rezen tests

# Type checking
mypy rezen

# Run tests with coverage
pytest --cov=rezen --cov-report=html

Pre-commit Hooks¶

Pre-commit hooks automatically run on every commit:

# Install pre-commit
pip install pre-commit
pre-commit install

# Run manually on all files
pre-commit run --all-files

📝 Documentation Standards¶

Docstring Requirements¶

All public functions, methods, and classes must have Google-style docstrings:

def search_active_agents(
    self,
    page_number: int = 0,
    page_size: int = 50,
    name: Optional[str] = None,
) -> Dict[str, Any]:
    """Search for active agents with filtering options.

    Args:
        page_number: Zero-based page number for pagination
        page_size: Number of results per page (max 100)
        name: Filter by agent name (partial match)

    Returns:
        Dictionary containing search results and pagination info

    Raises:
        ValidationError: If parameters are invalid
        AuthenticationError: If API key is invalid

    Example:
        >>> client = AgentsClient(api_key="your_key")
        >>> results = client.search_active_agents(
        ...     page_size=10,
        ...     name="Smith"
        ... )
        >>> print(f"Found {results['totalCount']} agents")
    """

Type Hints¶

All function parameters must have type hints
All return values must have type hints
Use Optional[T] for nullable parameters
Use Union[T, U] sparingly; prefer overloads
Import types from typing module as needed

Documentation Updates¶

When making code changes, always update:

Function docstrings - Keep examples current
API reference - Update docs/api/index.md
Examples - Update docs/guides/examples.md
Changelog - Add entry to docs/changelog.md

🧪 Testing Guidelines¶

Test Structure¶

tests/
├── test_agents.py          # Agent API tests
├── test_client.py          # Main client tests
├── test_directory.py       # Directory API tests
├── test_exceptions.py      # Exception handling tests
├── test_teams.py          # Teams API tests
└── test_transactions.py   # Transaction API tests

Test Requirements¶

100% test coverage for all new code
Descriptive test names explaining what is tested
Mock external API calls using responses library
Test error conditions not just happy paths

Writing Tests¶

@responses.activate
def test_search_agents_with_filters(self, client: AgentsClient) -> None:
    """Test agent search with multiple filter parameters."""
    # Arrange
    mock_response = {
        "agents": [{"id": "agent-123", "name": "John Smith"}],
        "totalCount": 1
    }
    responses.add(
        responses.GET,
        "https://yenta.therealbrokerage.com/api/v1/agents/search/active",
        json=mock_response,
        status=200,
    )

    # Act
    result = client.search_active_agents(
        name="Smith",
        page_size=10
    )

    # Assert
    assert result == mock_response
    assert len(responses.calls) == 1

    # Verify request parameters
    request_url = responses.calls[0].request.url
    assert "name=Smith" in request_url
    assert "pageSize=10" in request_url

Running Tests¶

# Run all tests
pytest

# Run specific test file
pytest tests/test_agents.py

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

# Run tests in parallel
pytest -n auto

# Run tests with verbose output
pytest -v

🔄 Development Workflow¶

Branch Strategy¶

main - Production-ready code
develop - Integration branch for features
feature/feature-name - Individual features
bugfix/issue-description - Bug fixes
hotfix/critical-fix - Emergency fixes

Contribution Process¶

Create feature branch:
```
git checkout -b feature/new-endpoint
```
Make changes following code quality standards

Run quality checks:

pre-commit run --all-files
pytest --cov=rezen

Update documentation as needed

Commit with descriptive message:

git commit -m "feat: add search_transactions endpoint

- Add new endpoint for transaction search
- Include pagination and filtering options
- Add comprehensive tests with 100% coverage
- Update API reference documentation"

Push and create pull request:
```
git push origin feature/new-endpoint
```

Commit Message Format¶

Follow conventional commits:

feat: - New features
fix: - Bug fixes
docs: - Documentation updates
style: - Code style changes
refactor: - Code refactoring
test: - Test additions/updates
chore: - Maintenance tasks

🐛 Debugging¶

Common Issues¶

Import errors: Ensure you're in the virtual environment
API errors: Check your API key in .env
Test failures: Run pytest -v for detailed output
Type errors: Run mypy rezen to identify issues

Debugging Tools¶

# Debug specific test
pytest tests/test_agents.py::TestAgentsClient::test_search_agents -v -s

# Debug with pdb
pytest --pdb tests/test_agents.py

# Generate coverage report
pytest --cov=rezen --cov-report=html
open htmlcov/index.html

📦 Release Process¶

Version Management¶

Update version in rezen/__init__.py
Update version in pyproject.toml
Update docs/changelog.md
Create git tag: git tag v1.2.0

Publishing¶

# Build package
python -m build

# Upload to PyPI (maintainers only)
twine upload dist/*

🔗 Resources¶

🆘 Getting Help¶

Documentation: Check the full documentation site
Issues: Open a GitHub issue for bugs or questions
Discussions: Use GitHub Discussions for general questions
Email: Contact the maintainers at dev@theperrygroup.com