Installation

Virtual Environment Setup

Always use a virtual environment to isolate project dependencies. This prevents version conflicts between projects and keeps your system Python clean.

uv (Recommended)pip + venv

uv provides fast virtual environment creation and management.

# Create a new virtual environment
uv venv

# Activate it
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

Python's built-in venv module works everywhere.

# Create a new virtual environment
python -m venv .venv

# Activate it
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

Why Virtual Environments?

Virtual environments prevent dependency conflicts by isolating packages per project. Without them, installing different versions of libraries for different projects becomes impossible, and upgrading one package can break unrelated code.

Basic Installation

With your virtual environment activated, install PrimeFeat:

uv (Recommended)pip

uv offers faster dependency resolution and installation.

uv pip install primefeat

pip install primefeat

Optional Dependencies

PrimeFeat offers optional features that require additional packages.

Interactive Notebooks

For interactive Marimo notebooks:

uvpip

uv pip install primefeat[interactive]

pip install primefeat[interactive]

Includes: marimo - Modern reactive Python notebooks

JIT Compilation

For accelerated computation with Numba:

uvpip

uv pip install primefeat[jit]

pip install primefeat[jit]

Includes: numba - JIT compiler for numerical Python code

Multiple Optional Groups

Install multiple optional dependencies:

uvpip

uv pip install primefeat[interactive,jit]

pip install primefeat[interactive,jit]

Development Installation

For contributing to PrimeFeat or running tests:

1. Clone the Repository

git clone git@github.com:rcalderonb6/primefeat.git
cd primefeat

2. Install in Editable Mode with Dev Dependencies

uv (Recommended)pip

# Create and activate virtual environment
uv venv
source .venv/bin/activate

# Install in editable mode with dev dependencies
uv pip install -e . --group dev

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate

# Install in editable mode
pip install -e .

# Install dev dependencies
pip install pytest pytest-cov mkdocs mkdocs-material \
            mkdocs-jupyter mkdocstrings[python] \
            bump-my-version codespell pywavelets

Editable Mode

The -e flag installs the package in editable mode. Changes to the source code take effect immediately without reinstalling.

Development Dependencies

The dev dependency group includes:

• Testing: pytest, pytest-cov
• Documentation: mkdocs, mkdocs-material, mkdocs-jupyter, mkdocstrings
• Code Quality: codespell
• Version Management: bump-my-version
• Analysis: pywavelets (for wavelet analysis features)

3. Verify Installation

# Run tests
pytest

# Build documentation locally
mkdocs serve

Troubleshooting

Import Errors

If you encounter import errors after installation, ensure your virtual environment is activated:

which python  # Should point to .venv/bin/python

Dependency Conflicts

uv handles this better than pip, but if you encounter issues:

# With uv: recreate the environment
rm -rf .venv
uv venv
source .venv/bin/activate
uv pip install primefeat