Development Guide

This guide covers development workflows, Makefile commands, testing, and contributing to py3plex.

View the full development guide: development.md

Getting Started

Clone the repository and install in development mode:

git clone https://github.com/SkBlaz/py3plex.git
cd py3plex

# Setup development environment
make setup

# Install package in editable mode with dev dependencies
make dev-install

Makefile Commands

The project includes a production-grade Makefile for streamlined development:

# View all available commands
make help

# Environment setup
make setup          # Create virtual environment
make dev-install    # Install in editable mode

# Code quality
make format         # Auto-format code
make lint           # Run linters

# Testing
make test           # Run tests with coverage
make coverage       # Open coverage report

# Documentation
make docs           # Build Sphinx documentation

# Build & publish
make clean          # Remove build artifacts
make build          # Build distributions
make publish        # Publish to PyPI

# CI
make ci             # Run full CI checks

Key Features:

  • Smart tool detection: Uses .venv/bin/ tools if available, otherwise falls back to global tools

  • Colorized output: Clear success/warning/error messages

  • Cross-platform: Works on Linux and macOS

Testing

Quick testing:

python run_tests.py

Development testing with pytest:

# Run all tests
pytest

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

# Run specific test file
pytest tests/test_core.py

# Using Makefile (recommended)
make test

Code Quality

Tools configured in pyproject.toml:

  • Black: Code formatting

  • Ruff: Fast linting

  • isort: Import sorting

  • Mypy: Type checking

  • Pytest: Testing with coverage

Before committing:

make format  # Auto-format code
make lint    # Check code quality
make test    # Run tests
make ci      # Run all checks

Contributing

We welcome contributions! Here’s how:

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Run tests and linting: make ci

  5. Commit with clear messages

  6. Push to your fork

  7. Open a Pull Request

Code Guidelines:

  • Follow existing code style (enforced by Black and Ruff)

  • Add tests for new features

  • Update documentation as needed

  • Keep changes focused and atomic

  • Write clear commit messages

Documentation

Build Sphinx documentation:

# Using Makefile (recommended)
make docs

# Manual build
cd docfiles
sphinx-build -b html . _build/html

The built documentation will be in docfiles/_build/html/.

Resources

For comprehensive project context, see LLM.md.