Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
143 lines (102 loc) · 3.41 KB

CONTRIBUTING.md

File metadata and controls

143 lines (102 loc) · 3.41 KB

Contributing to pyOpTools

Thank you for your interest in contributing to pyOpTools! This document provides guidelines and instructions for setting up your development environment and contributing to the project.

Development Setup

Prerequisites

  • Python 3.8 or higher
  • C++ compiler (for Cython extensions)
  • Git

Installation

  1. Clone the repository:
git clone https://github.com/cihologramas/pyoptools.git
cd pyoptools
  1. Install the package in editable mode with development dependencies:
pip install -e .[test]

This command will automatically build the Cython extensions and install the package in development mode.

Rebuilding Extensions

If you modify Cython source files (.pyx or .pxd), you can rebuild extensions without reinstalling:

python setup.py build_ext -i

Alternatively, re-run the editable install:

pip install -e .

Pre-commit Hooks

We use pre-commit hooks to ensure code quality and consistency. These hooks automatically check your code before each commit.

Setup

  1. Install pre-commit hooks (one-time setup):
pre-commit install

Usage

After installation, pre-commit hooks will run automatically on git commit. The hooks will:

  • Lint all Cython files (.pyx and .pxd) for style and potential issues
  • Ensure all Cython strings use double quotes for consistency

To run hooks manually without committing:

pre-commit run --all-files

To run hooks only on staged files:

pre-commit run

Configured Hooks

The project uses the following hooks (defined in .pre-commit-config.yaml):

  • cython-lint: Lints all .pyx and .pxd files
  • double-quote-cython-strings: Enforces double quotes in Cython strings

All hooks must pass before a commit is allowed. To bypass hooks (not recommended):

git commit --no-verify

Running Tests

Run all tests:

pytest

Run tests with coverage:

pytest --cov=pyoptools

Run a specific test:

pytest tests/path/to/test_file.py::test_function_name

Code Style

  • Follow PEP8 with line length preference of 88 characters
  • Use 4 spaces for indentation (no tabs)
  • Prefer double quotes for strings (enforced by pre-commit hooks)
  • Use NumPy-style docstrings
  • Import order: standard library, third-party, local imports

For more detailed code style guidelines, see AGENTS.md.

Utility Scripts

The scripts/ directory contains helpful development tools:

  • clean.py: Remove Cython-generated build artifacts

    python scripts/clean.py

  • autopep8_cython.py: Auto-format Cython source files

    python scripts/autopep8_cython.py

Making Changes

  1. Create a new branch for your changes:
git checkout -b feature-or-fix-name
  1. Make your changes and ensure tests pass
  2. Commit your changes (pre-commit hooks will run automatically)
  3. Push your branch and create a pull request

Additional Resources

Questions?

If you have questions or need help, please:

  • Open an issue on GitHub
  • Check the existing documentation
  • Contact the development team

Thank you for contributing to pyOpTools!