Development Setup

Development Setup Guide

This guide provides detailed instructions for setting up your development environment for contributing to githubauthlib.

Prerequisites

Required Software

1. Python 3.6 or higher
2. Git
3. pip (Python package installer)
4. Platform-specific requirements:
   • Linux: libsecret-tools
   • macOS: Xcode Command Line Tools
   • Windows: Visual Studio Build Tools

Python Environment

Verify Python installation:

python --version  # Should be 3.6 or higher
pip --version

Setting Up the Development Environment

1. Clone the Repository

# Fork the repository on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/githubauthlib.git
cd githubauthlib

2. Create a Virtual Environment

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Linux/macOS
source venv/bin/activate
# Windows
venv\Scripts\activate

3. Install Dependencies

# Install development dependencies
pip install -r requirements.txt

# Install the package in editable mode
pip install -e .

Development Tools

Code Formatting

We use black and isort for code formatting:

# Format code
black githubauthlib tests
isort githubauthlib tests

Configure VS Code settings:

{
    "python.formatting.provider": "black",
    "editor.formatOnSave": true,
    "python.sortImports.args": ["--profile", "black"]
}

Type Checking

We use mypy for static type checking:

# Run type checking
mypy githubauthlib

Configure mypy settings in setup.cfg:

[mypy]
python_version = 3.6
warn_return_any = True
warn_unused_configs = True
disallow_untyped_defs = True

Testing

We use pytest for testing:

# Run tests
pytest

# Run tests with coverage
pytest --cov=githubauthlib

# Run specific test file
pytest tests/test_github_auth.py

# Run tests matching pattern
pytest -k "test_token"

Documentation

We use Sphinx for documentation:

# Generate documentation
cd docs
make html

Preview documentation:

# Python 3
python -m http.server -d _build/html

IDE Setup

VS Code

1. Install extensions:

   • Python
   • Pylance
   • Python Test Explorer
   • Python Docstring Generator

2. Configure settings.json:

{
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": true,
    "python.testing.pytestEnabled": true,
    "python.formatting.provider": "black",
    "editor.formatOnSave": true,
    "python.analysis.typeCheckingMode": "basic"
}

PyCharm

1. Open project

2. Configure interpreter:

   • Settings > Project > Python Interpreter
   • Add > Virtual Environment > Existing
   • Select venv/bin/python

3. Configure testing:

   • Settings > Tools > Python Integrated Tools
   • Default test runner: pytest

Git Workflow

1. Create a Branch

# Update main branch
git checkout main
git pull origin main

# Create feature branch
git checkout -b feature/your-feature-name

2. Development Cycle

# Make changes
# Run tests
pytest

# Format code
black .
isort .

# Type check
mypy githubauthlib

# Commit changes
git add .
git commit -m "feat: Add new feature"

3. Push Changes

# Push to your fork
git push origin feature/your-feature-name

4. Create Pull Request

1. Go to GitHub
2. Create Pull Request
3. Fill in template
4. Request review

Environment Variables

Development-specific environment variables:

# Linux/macOS
export PYTHONPATH="${PYTHONPATH}:$(pwd)"
export GITHUB_TOKEN="your_test_token"

# Windows PowerShell
$env:PYTHONPATH += ";$(pwd)"
$env:GITHUB_TOKEN = "your_test_token"

Pre-commit Hooks

Install pre-commit hooks:

# Install pre-commit
pip install pre-commit

# Install hooks
pre-commit install

Configure .pre-commit-config.yaml:

repos:
-   repo: https://github.com/psf/black
    rev: 23.3.0
    hooks:
    -   id: black
-   repo: https://github.com/pycqa/isort
    rev: 5.12.0
    hooks:
    -   id: isort
-   repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.3.0
    hooks:
    -   id: mypy

Debugging

VS Code Launch Configuration

Create .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "justMyCode": false
        },
        {
            "name": "Python: Debug Tests",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/venv/bin/pytest",
            "args": [
                "-v",
                "tests/"
            ],
            "console": "integratedTerminal"
        }
    ]
}

Using pdb

import pdb; pdb.set_trace()  # Python 3.6
breakpoint()  # Python 3.7+

Common Development Tasks

Running Tests

# All tests
pytest

# With coverage
pytest --cov=githubauthlib

# Generate coverage report
pytest --cov=githubauthlib --cov-report=html

Building Documentation

# Generate HTML docs
cd docs
make html

# Clean and rebuild
make clean
make html

Creating a Release

1. Update version:

   • githubauthlib/__init__.py
   • setup.py

2. Create changelog entry

3. Build distribution:

python setup.py sdist bdist_wheel

4. Upload to PyPI:

twine upload dist/*

Troubleshooting Development Issues

Common Issues

1. Import errors:

# Add project root to PYTHONPATH
export PYTHONPATH="${PYTHONPATH}:$(pwd)"

2. Test discovery issues:

# Check pytest configuration
pytest --collect-only

3. Documentation build errors:

# Clean build
cd docs
make clean
make html

Additional Resources

• Python Developer's Guide
• pytest Documentation
• mypy Documentation
• Sphinx Documentation
• Black Documentation