Contributing to pycancensus

June 12, 2026 · View on GitHub

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

Getting Started

Development Installation

Fork the repository on GitHub

Clone your fork locally:

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

Install the package in development mode with all dependencies:
```
pip install -e .[dev,docs]
```

Setting up API Key

You'll need a CensusMapper API key for testing:

export CANCENSUS_API_KEY="your_api_key_here"

Get a free API key at: https://censusmapper.ca/users/sign_up

Development Workflow

Running Tests

Run the full test suite:

pytest

Run tests with coverage:

pytest --cov=pycancensus --cov-report=xml

Run specific test categories:

pytest tests/test_basic.py              # Basic tests
pytest tests/integration/               # Integration tests
pytest tests/performance/               # Performance tests

Code Style

pycancensus follows PEP 8 style guidelines and uses Black for code formatting.

Before submitting code, ensure it's properly formatted:

# Format code automatically
black pycancensus

# Check formatting without changing files
black --check pycancensus

Run linting checks:

# Check for critical errors
flake8 pycancensus --count --select=E9,F63,F7,F82 --show-source --statistics

# Full linting check
flake8 pycancensus --count --exit-zero --max-complexity=10 --max-line-length=88 --statistics

Building Documentation

Build the documentation locally to test your changes:

cd docs
make html

View the built documentation:

open _build/html/index.html  # macOS
# or
xdg-open _build/html/index.html  # Linux

Making Changes

Creating a Branch

Create a feature branch for your changes:

git checkout -b feature/your-feature-name

Use descriptive branch names:

feature/add-new-function for new features
fix/issue-123 for bug fixes
docs/update-tutorial for documentation changes

Commit Messages

Write clear, descriptive commit messages:

Add support for national-level census data

- Add 'C' to valid census levels in utils.py
- Create test suite for national-level functionality
- Update documentation with national-level examples

Guidelines:

Use the present tense ("Add feature" not "Added feature")
Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
First line should be 50 characters or less
Reference issues and pull requests after the first line

Code Guidelines

General Principles:

R compatibility is the north star: function names, signatures, and behavior mirror the R cancensus package; check the R implementation before changing ported behavior, and cross-validate results against it where feasible
All HTTP goes through get_session() from resilience.py — never raw requests
Identifier columns (region IDs, UIDs) are strings, never numeric
When adding a public function: export it in __init__.py's __all__, add it to docs/api/index.rst, and commit the autosummary stub
Write clear, readable code
Add docstrings to all public functions and classes
Follow existing code patterns and conventions
Keep functions focused and single-purpose
Add type hints where appropriate

See AGENTS.md for a fuller architecture map and known gotchas (written for AI coding agents, equally useful for humans).

Docstring Format:

def function_name(param1: str, param2: int) -> pd.DataFrame:
    """
    Brief description of what the function does.

    Parameters
    ----------
    param1 : str
        Description of param1.
    param2 : int
        Description of param2.

    Returns
    -------
    pd.DataFrame
        Description of return value.

    Examples
    --------
    >>> result = function_name("example", 42)
    >>> print(result)
    """

Adding Tests

All new features and bug fixes should include tests:

Test Organization:

tests/test_basic.py - Unit tests for core functionality
tests/integration/ - Integration tests requiring API calls
tests/performance/ - Performance and stress tests

Writing Tests:

def test_new_feature():
    """Test description explaining what is being tested."""
    # Arrange
    input_data = prepare_test_data()

    # Act
    result = your_function(input_data)

    # Assert
    assert result is not None
    assert isinstance(result, pd.DataFrame)
    assert len(result) > 0

Submitting Changes

Pull Request Process

Update documentation to reflect any changes
Add tests for new functionality

Ensure all tests pass:

pytest
black --check pycancensus
flake8 pycancensus

Push your changes to your fork:

git push origin feature/your-feature-name

Open a pull request on GitHub

Pull Request Checklist

Before submitting, verify:

Tests pass locally
Code is formatted with Black
No linting errors from flake8
Documentation is updated
Docstrings added for new functions
Examples added where appropriate
CHANGELOG.md updated (for significant changes)
Commit messages are clear and descriptive

Pull Request Description

Provide a clear description of your changes:

## Description
Brief summary of the changes and their purpose.

## Motivation
Why are these changes needed? What problem do they solve?

## Changes
- List of specific changes made
- Include any breaking changes
- Note any new dependencies

## Testing
How were these changes tested?

## Related Issues
Fixes #123
Relates to #456

Reporting Issues

Bug Reports

When reporting bugs, include:

Description: Clear description of the bug
Steps to Reproduce: Minimal code to reproduce the issue
Expected Behavior: What you expected to happen
Actual Behavior: What actually happened
Environment:
- pycancensus version
- Python version
- Operating system
- Relevant dependencies

Example:

**Description**
`get_census()` fails when requesting national-level data

**Steps to Reproduce**
```python
import pycancensus as pc
data = pc.get_census('CA21', level='C', regions={'C': '01'})

Expected Behavior Should return national-level census data for Canada

Actual Behavior Raises ValueError: Invalid level: C

Environment

pycancensus 0.1.0
Python 3.9.6
macOS 12.0


### Feature Requests

When requesting features, include:

1. **Use Case**: Describe the problem this feature would solve
2. **Proposed Solution**: How you envision the feature working
3. **Alternatives**: Other approaches you've considered
4. **R cancensus Comparison**: If applicable, how R cancensus handles this

## Code Review Process

After submitting a pull request:

1. **Automated Checks**: CI will run tests and code quality checks
2. **Maintainer Review**: A maintainer will review your code
3. **Feedback**: Address any requested changes
4. **Approval**: Once approved, your PR will be merged

**Review Timeline:**
- Initial response within 7 days
- Most PRs reviewed within 2 weeks
- Complex changes may take longer

## Development Setup Tips

### Virtual Environment

Use a virtual environment for development:

```bash
python -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate  # Windows

pip install -e .[dev,docs]

Pre-commit Hooks

Consider setting up pre-commit hooks to automatically format code:

pip install pre-commit
pre-commit install

Create .pre-commit-config.yaml:

repos:
  - repo: https://github.com/psf/black
    rev: 23.3.0
    hooks:
      - id: black

Questions?

If you have questions about contributing:

Check existing issues and pull requests
Review the documentation
Open a discussion on GitHub
Ask in your pull request or issue

License

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

Thank You!

Thank you for contributing to pycancensus! Your contributions help make Canadian census data more accessible to the Python community.