Development Setup#

This guide covers setting up a development environment for EEGPrep and contributing to the project.

Prerequisites#

System Requirements#

  • Python: 3.11 or higher

  • Git: For version control

  • pip: Python package manager

  • Virtual environment: venv or conda

Check your Python version:

python --version

Required Tools#

Optional Tools#

  • Conda: For environment management (https://conda.io/)

  • Docker: For containerized development

  • Make: For running build commands

Installation from Source#

Clone the Repository#

git clone https://github.com/NeuroTechX/eegprep.git
cd eegprep

Create Virtual Environment#

Using venv:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Using conda:

conda create -n eegprep python=3.10
conda activate eegprep

Install in Editable Mode#

Install the package with all development dependencies:

pip install -e ".[dev]"

This installs:

  • The eegprep package in editable mode (changes are reflected immediately)

  • Development dependencies (testing, linting, formatting)

  • Documentation dependencies

Install Documentation Dependencies#

pip install -r requirements-docs.txt

This includes:

  • Sphinx (documentation generator)

  • sphinx-rtd-theme (Read the Docs theme)

  • sphinx-autodoc-typehints (Type hints in documentation)

  • sphinx-gallery (Example gallery)

Running Tests#

Test Discovery#

Tests are located in the tests/ directory. Run all tests:

pytest

Run specific test file:

pytest tests/test_clean_artifacts.py

Run specific test function:

pytest tests/test_clean_artifacts.py::test_remove_artifacts

Pytest Options#

Verbose output:

pytest -v

Stop on first failure:

pytest -x

Show print statements:

pytest -s

Run only tests matching a pattern:

pytest -k "artifact"

Test Coverage#

Generate coverage report:

pytest --cov=src/eegprep --cov-report=html

View HTML coverage report:

open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux
start htmlcov/index.html  # Windows

Continuous Integration#

Tests run automatically on:

  • Every push to a branch

  • Every pull request

  • Scheduled nightly runs

Check CI status on GitHub Actions.

Building Documentation#

Build HTML Documentation#

Navigate to the docs directory and build:

cd docs
make html

The built documentation is in docs/_build/html/.

View Documentation Locally#

Open the built documentation in your browser:

open docs/_build/html/index.html  # macOS
xdg-open docs/_build/html/index.html  # Linux
start docs/_build/html/index.html  # Windows

Or use a local server:

cd docs/_build/html
python -m http.server 8000

Then visit http://localhost:8000 in your browser.

Clean Build#

Remove old build files and rebuild:

cd docs
make clean
make html

Build Options#

Build PDF documentation (requires LaTeX):

cd docs
make latexpdf

Build EPUB documentation:

cd docs
make epub

Debugging Tips#

Logging#

Enable debug logging in your code:

import logging

# Set up logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)

# Use logging in your code
logger.debug("Debug message")
logger.info("Info message")
logger.warning("Warning message")
logger.error("Error message")

Breakpoints#

Use Python’s built-in debugger:

import pdb

def my_function():
    x = 10
    pdb.set_trace()  # Execution pauses here
    y = x + 5
    return y

Or use the newer breakpoint() function (Python 3.7+):

def my_function():
    x = 10
    breakpoint()  # Execution pauses here
    y = x + 5
    return y

Profiling#

Profile code performance:

import cProfile
import pstats

# Profile a function
profiler = cProfile.Profile()
profiler.enable()

# Your code here
my_function()

profiler.disable()
stats = pstats.Stats(profiler)
stats.sort_stats('cumulative')
stats.print_stats(10)  # Print top 10 functions

Memory Profiling#

Install memory profiler:

pip install memory-profiler

Use it in your code:

from memory_profiler import profile

@profile
def my_function():
    large_list = [i for i in range(1000000)]
    return sum(large_list)

Run with:

python -m memory_profiler script.py

Release Process#

Version Numbering#

EEGPrep uses Semantic Versioning:

  • MAJOR: Incompatible API changes

  • MINOR: New functionality (backward compatible)

  • PATCH: Bug fixes (backward compatible)

Example: 1.2.3 (Major.Minor.Patch)

Versioning Steps#

  1. Update version in src/eegprep/__init__.py:

__version__ = "1.2.3"

  1. Update version in pyproject.toml:

[project]
version = "1.2.3"

  1. Update docs/source/changelog.rst with release notes

  2. Commit changes:

git add .
git commit -m "Release version 1.2.3"

Tagging#

Create a git tag for the release:

git tag -a v1.2.3 -m "Release version 1.2.3"
git push origin v1.2.3

PyPI Release#

Build distribution packages:

pip install build twine
python -m build

Upload to PyPI:

python -m twine upload dist/*

Or upload to TestPyPI first:

python -m twine upload --repository testpypi dist/*

Common Issues#

Import Errors#

Problem: ModuleNotFoundError: No module named 'eegprep'

Solution: Install the package in editable mode:

pip install -e .

Test Failures#

Problem: Tests fail with import errors

Solution: Ensure you’re in the virtual environment and dependencies are installed:

source venv/bin/activate
pip install -e ".[dev]"
pytest

Documentation Build Errors#

Problem: Sphinx build fails with missing modules

Solution: Install documentation dependencies:

pip install -r requirements-docs.txt

Git Conflicts#

Problem: Merge conflicts when pulling upstream changes

Solution: Resolve conflicts manually:

git fetch upstream
git rebase upstream/main
# Resolve conflicts in your editor
git add .
git rebase --continue

Virtual Environment Issues#

Problem: Virtual environment not activating

Solution: Recreate the virtual environment:

rm -rf venv
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

Dependency Conflicts#

Problem: Dependency version conflicts

Solution: Update pip and reinstall:

pip install --upgrade pip
pip install -e ".[dev]" --force-reinstall

Getting Help#

Happy developing!