edsger 0.1.5__tar.gz → 0.1.6__tar.gz

{edsger-0.1.5 → edsger-0.1.6}/.pre-commit-config.yaml

@@ -11,4 +11,14 @@ repos:
     hooks:
       - id: cython-lint
         files: '\.(pyx|pxd)$'
-        args: [--max-line-length=88]
+        args: [--max-line-length=88]
+
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: pyright
+        language: system
+        types: [python]
+        pass_filenames: false
+        always_run: true

{edsger-0.1.5 → edsger-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edsger
-Version: 0.1.5
+Version: 0.1.6
 Summary: Graph algorithms in Cython.
 Author-email: François Pacull <francois.pacull@architecture-performance.fr>
 Maintainer-email: François Pacull <francois.pacull@architecture-performance.fr>
@@ -48,6 +48,7 @@ Dynamic: license-file
 [![Python 3.9 | 3.10 | 3.11 | 3.12 | 3.13](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://pypi.org/project/edsger/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Cython lint: cython-lint](https://img.shields.io/badge/cython--lint-enabled-brightgreen.svg)](https://github.com/MarcoGorelli/cython-lint)
+[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 # Edsger
@@ -155,6 +156,53 @@ except ValueError as e:
 
     Error: Negative cycle detected in the graph
 
+## Breadth-First Search: Unweighted Directed Graphs
+
+The BFS (Breadth-First Search) algorithm finds shortest paths in directed graphs where edge weights are ignored (or all edges are treated as having equal weight). It's particularly efficient for finding paths based on the minimum number of hops/edges rather than weighted distances.
+
+```python
+from edsger.path import BFS
+
+# Create an unweighted directed graph
+edges_unweighted = pd.DataFrame({
+    'tail': [0, 0, 1, 2, 2, 3],
+    'head': [1, 2, 3, 3, 4, 4]
+})
+edges_unweighted
+```
+
+|    |   tail |   head |
+|---:|-------:|-------:|
+|  0 |      0 |      1 |
+|  1 |      0 |      2 |
+|  2 |      1 |      3 |
+|  3 |      2 |      3 |
+|  4 |      2 |      4 |
+|  5 |      3 |      4 |
+
+```python
+# Initialize BFS
+bfs = BFS(edges_unweighted)
+
+# Run BFS from vertex 0 with path tracking
+predecessors = bfs.run(vertex_idx=0, path_tracking=True)
+print("Predecessors:", predecessors)
+
+# Extract the path to vertex 4
+path = bfs.get_path(4)
+print("Path from 0 to 4:", path)
+```
+
+    Predecessors: [-9999     0     0     1     2]
+    Path from 0 to 4: [4 2 0]
+
+The BFS algorithm is ideal for directed graphs when:
+- All edges should be treated equally (ignoring edge weights)
+- You need to find paths with the minimum number of edges/hops
+- You want the fastest path-finding algorithm for unweighted directed graphs (O(V + E) time complexity)
+
+Note: The predecessor value -9999 indicates either the start vertex or an unreachable vertex. In the path output, vertices are listed from target to source.
+
 ## Installation
 
 ### Standard Installation
@@ -163,6 +211,80 @@ except ValueError as e:
 pip install edsger
 ```
 
+### Development Installation
+
+For development work, clone the repository and install in development mode:
+
+```bash
+git clone https://github.com/aetperf/Edsger.git
+cd Edsger
+pip install -r requirements-dev.txt
+pip install -e .
+```
+
+## Development
+
+This project uses several development tools to ensure code quality:
+
+### Type Checking
+
+We use [Pyright](https://github.com/microsoft/pyright) for static type checking:
+
+```bash
+# Run type checking
+make typecheck
+
+# Or directly with pyright
+pyright
+```
+
+For more details on type checking configuration and gradual typing strategy, see [TYPING.md](TYPING.md).
+
+### Running Tests
+
+```bash
+# Run all tests
+make test
+
+# Run with coverage
+make coverage
+```
+
+### Code Formatting and Linting
+
+```bash
+# Format code with black
+make format
+
+# Check code style
+make lint
+```
+
+### Pre-commit Hooks
+
+This project uses pre-commit hooks to maintain code quality. The hooks behave differently based on the branch:
+
+- **Protected branches (main, release*)**: All hooks run including pyright type checking
+- **Feature branches**: Only formatting hooks run (black, cython-lint) for faster commits
+  - Run `make typecheck` or `pre-commit run --all-files` to manually check types before merging
+
+```bash
+# Install pre-commit hooks
+pre-commit install
+
+# Run all hooks manually
+pre-commit run --all-files
+
+# Skip specific hooks if needed
+SKIP=pyright git commit -m "your message"
+```
+
+### Available Make Commands
+
+```bash
+make help  # Show all available commands
+```
+
 ## Why Use Edsger?
 
 Edsger is designed to be **dataframe-friendly**, providing seamless integration with pandas workflows for graph algorithms. Also it is rather efficient on Linux. Our benchmarks on the USA road network (23.9M vertices, 57.7M edges) demonstrate nice performance:
@@ -179,4 +301,4 @@ Edsger is licensed under the MIT License. See the LICENSE file for more details.
 
 ## Contact
 
-For any questions or inquiries, please contact François Pacull at [francois.pacull@architecture-performance.fr](mailto:francois.pacull@architecture-performance.fr).
+For any questions or inquiries, please contact me at [francois.pacull@architecture-performance.fr](mailto:francois.pacull@architecture-performance.fr).

{edsger-0.1.5 → edsger-0.1.6}/README.md

@@ -7,6 +7,7 @@
 [![Python 3.9 | 3.10 | 3.11 | 3.12 | 3.13](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://pypi.org/project/edsger/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Cython lint: cython-lint](https://img.shields.io/badge/cython--lint-enabled-brightgreen.svg)](https://github.com/MarcoGorelli/cython-lint)
+[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 # Edsger
@@ -114,6 +115,53 @@ except ValueError as e:
 
     Error: Negative cycle detected in the graph
 
+## Breadth-First Search: Unweighted Directed Graphs
+
+The BFS (Breadth-First Search) algorithm finds shortest paths in directed graphs where edge weights are ignored (or all edges are treated as having equal weight). It's particularly efficient for finding paths based on the minimum number of hops/edges rather than weighted distances.
+
+```python
+from edsger.path import BFS
+
+# Create an unweighted directed graph
+edges_unweighted = pd.DataFrame({
+    'tail': [0, 0, 1, 2, 2, 3],
+    'head': [1, 2, 3, 3, 4, 4]
+})
+edges_unweighted
+```
+
+|    |   tail |   head |
+|---:|-------:|-------:|
+|  0 |      0 |      1 |
+|  1 |      0 |      2 |
+|  2 |      1 |      3 |
+|  3 |      2 |      3 |
+|  4 |      2 |      4 |
+|  5 |      3 |      4 |
+
+```python
+# Initialize BFS
+bfs = BFS(edges_unweighted)
+
+# Run BFS from vertex 0 with path tracking
+predecessors = bfs.run(vertex_idx=0, path_tracking=True)
+print("Predecessors:", predecessors)
+
+# Extract the path to vertex 4
+path = bfs.get_path(4)
+print("Path from 0 to 4:", path)
+```
+
+    Predecessors: [-9999     0     0     1     2]
+    Path from 0 to 4: [4 2 0]
+
+The BFS algorithm is ideal for directed graphs when:
+- All edges should be treated equally (ignoring edge weights)
+- You need to find paths with the minimum number of edges/hops
+- You want the fastest path-finding algorithm for unweighted directed graphs (O(V + E) time complexity)
+
+Note: The predecessor value -9999 indicates either the start vertex or an unreachable vertex. In the path output, vertices are listed from target to source.
+
 ## Installation
 
 ### Standard Installation
@@ -122,6 +170,80 @@ except ValueError as e:
 pip install edsger
 ```
 
+### Development Installation
+
+For development work, clone the repository and install in development mode:
+
+```bash
+git clone https://github.com/aetperf/Edsger.git
+cd Edsger
+pip install -r requirements-dev.txt
+pip install -e .
+```
+
+## Development
+
+This project uses several development tools to ensure code quality:
+
+### Type Checking
+
+We use [Pyright](https://github.com/microsoft/pyright) for static type checking:
+
+```bash
+# Run type checking
+make typecheck
+
+# Or directly with pyright
+pyright
+```
+
+For more details on type checking configuration and gradual typing strategy, see [TYPING.md](TYPING.md).
+
+### Running Tests
+
+```bash
+# Run all tests
+make test
+
+# Run with coverage
+make coverage
+```
+
+### Code Formatting and Linting
+
+```bash
+# Format code with black
+make format
+
+# Check code style
+make lint
+```
+
+### Pre-commit Hooks
+
+This project uses pre-commit hooks to maintain code quality. The hooks behave differently based on the branch:
+
+- **Protected branches (main, release*)**: All hooks run including pyright type checking
+- **Feature branches**: Only formatting hooks run (black, cython-lint) for faster commits
+  - Run `make typecheck` or `pre-commit run --all-files` to manually check types before merging
+
+```bash
+# Install pre-commit hooks
+pre-commit install
+
+# Run all hooks manually
+pre-commit run --all-files
+
+# Skip specific hooks if needed
+SKIP=pyright git commit -m "your message"
+```
+
+### Available Make Commands
+
+```bash
+make help  # Show all available commands
+```
+
 ## Why Use Edsger?
 
 Edsger is designed to be **dataframe-friendly**, providing seamless integration with pandas workflows for graph algorithms. Also it is rather efficient on Linux. Our benchmarks on the USA road network (23.9M vertices, 57.7M edges) demonstrate nice performance:
@@ -138,4 +260,4 @@ Edsger is licensed under the MIT License. See the LICENSE file for more details.
 
 ## Contact
 
-For any questions or inquiries, please contact François Pacull at [francois.pacull@architecture-performance.fr](mailto:francois.pacull@architecture-performance.fr).
+For any questions or inquiries, please contact me at [francois.pacull@architecture-performance.fr](mailto:francois.pacull@architecture-performance.fr).

edsger-0.1.6/clean_build.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+# Clean build script for Edsger Cython project
+# Use this when making significant changes to ensure clean rebuild
+
+echo "Cleaning build artifacts..."
+
+# Remove compiled Cython C files
+find src/ -name "*.c" -delete
+echo "✓ Removed generated C files"
+
+# Remove compiled shared libraries
+find src/ -name "*.so" -delete
+echo "✓ Removed shared libraries"
+
+# Remove build directory
+rm -rf build/
+echo "✓ Removed build directory"
+
+# Remove Python cache
+find . -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null
+find . -name "*.pyc" -delete 2>/dev/null
+echo "✓ Removed Python cache"
+
+# Remove Cython HTML annotation files (if any)
+find . -name "*.html" -path "*/build/*" -delete 2>/dev/null
+
+echo "Clean complete! Ready for fresh build."
+echo "Run: python setup.py build_ext --inplace"

edsger-0.1.6/docs/TYPING.md

@@ -0,0 +1,107 @@
+# Type Checking with Pyright
+
+This project uses [Pyright](https://github.com/microsoft/pyright) for static type checking.
+
+## Setup
+
+1. **Install dependencies**:
+   ```bash
+   pip install -r requirements-dev.txt
+   ```
+
+2. **Run type checking**:
+   ```bash
+   # Basic mode (default)
+   make typecheck
+   # or directly
+   pyright
+   
+   # Strict mode
+   make typecheck-strict
+   ```
+
+## Configuration
+
+The type checking configuration is defined in `pyrightconfig.json`. The project currently uses **basic** type checking mode to allow for gradual type hint adoption.
+
+## Current Status
+
+The project is in the process of adding type hints. Currently:
+
+- **Type checking mode**: Basic
+- **Coverage**: Minimal type hints in Python files
+- **Cython files**: Excluded from type checking (`.pyx` and `.pxd` files)
+
+## Known Issues
+
+### Import Resolution
+Some optional dependencies may show import warnings:
+- `scipy` - Used in tests and scripts
+- `loguru` - Used in scripts
+- `graph_tool` - Optional dependency for benchmarks
+- `networkit` - Optional dependency for benchmarks
+
+These can be safely ignored if you're not using these features.
+
+### Cython Integration
+Cython-generated modules may show as missing imports. These are expected:
+- Imports from `.pyx` files will show warnings
+- This is normal as Pyright cannot analyze Cython files directly
+
+### Test Files
+Some test files import functions directly from Cython modules that are not visible to Pyright.
+
+## Adding Type Hints
+
+When adding type hints to the project:
+
+1. **Start with function signatures**:
+   ```python
+   def compute_path(edges: pd.DataFrame, source: int) -> np.ndarray:
+       ...
+   ```
+
+2. **Use type aliases for clarity**:
+   ```python
+   from typing import TypeAlias
+   
+   NodeID: TypeAlias = int
+   Weight: TypeAlias = float
+   ```
+
+3. **For Cython imports, use type ignore comments**:
+   ```python
+   from edsger.dijkstra import compute_sssp  # type: ignore
+   ```
+
+## VS Code Integration
+
+If using VS Code, the project includes `.vscode/settings.json` with appropriate configurations for Pylance/Pyright integration.
+
+## Pre-commit Hook
+
+Pyright is configured as a pre-commit hook. It will run automatically before commits if you have pre-commit installed:
+
+```bash
+pre-commit install
+```
+
+To run manually:
+```bash
+pre-commit run pyright --all-files
+```
+
+## Gradual Typing Strategy
+
+The project follows a gradual typing approach:
+
+1. **Phase 1** (Current): Basic type checking, focus on obvious type errors
+2. **Phase 2**: Add type hints to public APIs
+3. **Phase 3**: Increase to standard mode, add more comprehensive type hints
+4. **Phase 4**: Consider strict mode for new code
+
+## Resources
+
+- [Pyright Documentation](https://github.com/microsoft/pyright/blob/main/docs/configuration.md)
+- [Python Type Hints](https://docs.python.org/3/library/typing.html)
+- [PEP 484 - Type Hints](https://www.python.org/dev/peps/pep-0484/)