Development Guide

October 15, 2025 · View on GitHub

This guide covers everything you need to know to contribute to pypresence.

Setting Up Development Environment

Clone the repository

git clone https://github.com/qwertyquerty/pypresence.git
cd pypresence

Create a virtual environment

python -m venv .venv

# On Windows
.venv\Scripts\activate

# On macOS/Linux
source .venv/bin/activate

Install in editable mode with development dependencies
```
pip install -e ".[dev]"
```
This installs pypresence in editable mode along with all development tools:
- pytest - Testing framework
- pytest-asyncio - Async test support
- pytest-mock - Mocking utilities
- pytest-cov - Coverage reporting
- black - Code formatter
- flake8 - Linter
- mypy - Type checker
- isort - Import sorter
- sphinx - Documentation generator

Running Tests

Run all tests:

pytest

Run tests with verbose output:

pytest -v

Run specific test file:

pytest tests/test_presence.py

Run tests with coverage:

pytest --cov=pypresence --cov-report=html

Exclude manual tests (require Discord running):

pytest -m "not manual"

Test Markers

asyncio - Async tests
integration - Integration tests
manual - Tests requiring manual setup (e.g., Discord running)

Code Quality

Format code with Black:

black .

Check code style with flake8:

flake8 pypresence tests

Sort imports with isort:

isort .

Type check with mypy:

mypy pypresence

Run all checks at once:

black . && isort . && flake8 pypresence tests && mypy pypresence && pytest

Project Structure

pypresence/
├── pypresence/          # Main package
│   ├── __init__.py     # Package initialization, version
│   ├── baseclient.py   # Base RPC client
│   ├── client.py       # Full RPC client (authorize, etc.)
│   ├── presence.py     # Simple presence client
│   ├── payloads.py     # Payload builders
│   ├── exceptions.py   # Custom exceptions
│   ├── types.py        # Type definitions
│   └── utils.py        # Utility functions
├── tests/              # Test suite
│   ├── test_baseclient.py
│   ├── test_presence.py
│   ├── test_payloads.py
│   └── ...
├── examples/           # Example scripts
├── docs/              # Documentation
└── pyproject.toml     # Project configuration

Key Files

pypresence/__init__.py - Package entry point, defines __version__
pypresence/baseclient.py - Core IPC communication with Discord
pypresence/presence.py - Simple Rich Presence API
pypresence/client.py - Full RPC client with authorization
pyproject.toml - All project configuration (build, tools, dependencies)

Making Changes

Create a new branch

git checkout -b feature/your-feature-name

Make your changes
- Write code following the existing style
- Add tests for new functionality
- Update documentation if needed
- Ensure type hints are included

Run tests and linters

pytest
black .
flake8 pypresence tests
mypy pypresence

Commit your changes

git add .
git commit -m "Description of your changes"

Push and create a Pull Request

git push origin feature/your-feature-name

Version Management

The project uses a single source of truth for versioning. The version is defined only in pypresence/__init__.py:

__version__ = "4.5.2"

The pyproject.toml automatically reads this version using dynamic versioning:

[project]
dynamic = ["version"]

[tool.setuptools.dynamic]
version = {attr = "pypresence.__version__"}

When releasing a new version, only update the version in pypresence/__init__.py. The version will automatically propagate to:

Package metadata
Build artifacts
PyPI uploads
All imports

Building the Package

Install build tools:

pip install build

Build source distribution and wheel:

python -m build

The built packages will be in the dist/ directory:

pypresence-x.x.x.tar.gz (source distribution)
pypresence-x.x.x-py3-none-any.whl (wheel)

Continuous Integration

The project uses GitHub Actions for CI/CD:

Test Workflow (`.github/workflows/test.yml`)

Runs on every push and pull request
Tests Python 3.8, 3.9, 3.10, 3.11, 3.12, 3.13
Tests on Ubuntu, Windows, and macOS
Ensures cross-platform compatibility

Lint Workflow (`.github/workflows/lint_python.yml`)

Runs bandit, black, codespell, flake8, isort, mypy
Checks code quality and security
Some checks are non-blocking (|| true)

Publish Workflow (`.github/workflows/publish-to-pypi.yml`)

Automatically publishes to PyPI on GitHub releases
Uses trusted publishing (no API tokens needed)

✅ All tests pass (pytest)
✅ Code is formatted (black .)
✅ Imports are sorted (isort .)
✅ No linting errors (flake8 pypresence tests)
✅ Type checking passes (mypy pypresence)
✅ New features have tests
✅ Documentation is updated if needed

Code Style

Follow PEP 8 (enforced by black and flake8)
Use type hints for all functions
Write docstrings for public APIs
Keep functions focused and testable
Prefer clarity over cleverness

Commit Messages

This project follows Conventional Commits specification.

Format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Common types:

feat: - New feature
fix: - Bug fix
docs: - Documentation changes
style: - Code style changes (formatting, missing semi-colons, etc.)
refactor: - Code refactoring (no feature changes or bug fixes)
test: - Adding or updating tests
chore: - Maintenance tasks (dependencies, build process, etc.)
ci: - CI/CD changes

Examples:

feat: add support for Discord activity buttons
fix: resolve connection timeout on Windows
docs: update async client documentation
test: add coverage for presence.update method
chore: update pytest to 8.0.0
ci: add Python 3.13 to test matrix

With scope:

feat(presence): add button support
fix(client): handle connection timeout properly
docs(readme): add development section

Breaking changes:

feat!: remove deprecated sync_handler parameter

BREAKING CHANGE: The sync_handler parameter has been removed.
Use error_handler instead.

Pull Request Process

Fork the repository
Create a branch for your feature
Make your changes with tests
Run all checks (tests, linters, type checker)
Push to your fork
Open a Pull Request with a clear description
Respond to feedback from maintainers