spytial: Instructions file for GitHub Copilot

sPyTial: Spatial Python Visualization Library

sPyTial is a Python library for spatial visualization of structured data using declarative constraints. It compiles to the Spytial diagramming language to generate interactive HTML visualizations. The library enables developers to visualize Python objects (trees, graphs, nested structures) with minimal effort while providing advanced spatial annotation capabilities.

Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.

Working Effectively

Bootstrap and Install (15-20 seconds)

# Install the package in development mode
python -m pip install -e .

NEVER CANCEL: This typically takes 15-20 seconds. Set timeout to 60+ seconds.

Install Development Dependencies (30-45 seconds)

# Install testing and linting tools
python -m pip install pytest>=7.0.0 flake8>=6.0.0 black>=23.0.0

NEVER CANCEL: This typically takes 30-45 seconds. Set timeout to 90+ seconds.

Build the Package (10-15 seconds)

# Build source and wheel distributions
python -m pip install build
python -m build --no-isolation

NEVER CANCEL: Build takes 10-15 seconds. Set timeout to 60+ seconds.

Run Tests (<1 second)

# Run test suite with pytest
python -m pytest test/ -v

# Run individual test files directly
python test/test_group_selector.py
python test/test_object_annotations.py

Note: Test suite currently has 2 failing tests out of 14 total, but core functionality works correctly. Do not modify code to fix unrelated test failures.

Code Quality and Linting (immediate)

# Check code style - expect 270+ violations in current codebase
python -m flake8 spytial/ --count --statistics

# Check code formatting - expect 5 files need reformatting
python -m black spytial/ --check

# Apply code formatting
python -m black spytial/

ALWAYS run python -m black spytial/ and python -m flake8 spytial/ before committing changes or CI will fail.