edsger 0.0.14__tar.gz → 0.1.0__tar.gz

edsger-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Documentation
+
+on:
+  push:
+    branches: [ release ]
+  pull_request:
+    branches: [ release ]
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+    
+    - name: Install documentation dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r docs/requirements.txt
+    
+    - name: Build documentation
+      run: |
+        cd docs
+        make html
+    
+    - name: Upload documentation artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: documentation-html
+        path: docs/build/html/
+    
+    - name: Deploy to GitHub Pages (on release branch)
+      if: github.ref == 'refs/heads/release' && github.event_name == 'push'
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/build/html
+        publish_branch: gh-pages

{edsger-0.0.14 → edsger-0.1.0}/.github/workflows/tests.yml

@@ -9,13 +9,13 @@ jobs:
   test:
     strategy:
       matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
+        os: [ubuntu-22.04, windows-2022, macos-14]
         python-version: ["3.11"]
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies

{edsger-0.0.14 → edsger-0.1.0}/.gitignore

@@ -45,9 +45,22 @@ sdist/*
 docs/api/*
 docs/_rst/*
 docs/_build/*
+docs/build/*
 cover/*
 MANIFEST
 
+# Documentation backup and temporary folders
+docs_BCKP/
+docs_old/
+site/
+tmp/
+
+# Credentials and config
+.pypirc
+
+# MkDocs (unused)
+mkdocs.yml
+
 # Per-project virtualenvs
 .venv*/
 .conda*/

edsger-0.1.0/.readthedocs.yaml

@@ -0,0 +1,27 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# Explicitly set the version of Python and its requirements
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - requirements: requirements.txt
+    - method: pip
+      path: .
+
+# Optional but recommended, pin the Python requirements used to build docs
+formats:
+  - pdf
+  - htmlzip

{edsger-0.0.14/src/edsger.egg-info → edsger-0.1.0}/PKG-INFO

@@ -1,11 +1,12 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: edsger
-Version: 0.0.14
+Version: 0.1.0
 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>
 License: MIT License
 Project-URL: Repository, https://github.com/aetperf/Edsger
+Project-URL: Documentation, https://edsger.readthedocs.io
 Keywords: python,graph,shortest path,Dijkstra
 Platform: any
 Classifier: Development Status :: 4 - Beta
@@ -31,6 +32,7 @@ Provides-Extra: doc
 Requires-Dist: sphinx; extra == "doc"
 Requires-Dist: sphinx_design; extra == "doc"
 Requires-Dist: sphinx_rtd_theme; extra == "doc"
+Dynamic: license-file
 
 
 ![Tests Status](https://github.com/aetperf/edsger/actions/workflows/tests.yml/badge.svg?branch=release)
@@ -205,11 +207,11 @@ shortest_paths[-5:]
 
 ####  Run method options
 
-The `run` method can take the following arguments besides the source vertex index:
+The `run` method can take the following arguments besides the source/target vertex index:
 
 - `path_tracking` : bool, optional (default=False)
 
-Whether to track the shortest path(s) from the source vertex to all other vertices in the graph.
+Whether to track the shortest path(s) from/to the source/target vertex to all other vertices in the graph.
 
 ```python
 dijkstra = Dijkstra(edges)
@@ -229,7 +231,7 @@ The path is returned as an array of vertex indices. This is an ordered list of v
 
 - `return_inf` : bool, optional (default=True)
     
-Whether to return path length(s) as infinity (np.inf) when no path exists.
+Whether to return path lengths as infinity (np.inf) when no path exists.
 
 ```python
 dijkstra = Dijkstra(edges, orientation='in')
@@ -262,7 +264,7 @@ shortest_paths
 
 - `heap_length_ratio` : float, optional (default=1.0)
     
-This is an experimental parameter that controls the size of the heap used in the algorithm. The heap is a static array that is used to store the vertices that are may be visited next. A value of 1.0 means that the heap is the same size as the number of vertices, so there is no risk of overflow. Be aware that there is no guarantee that the algorithm will work with a heap length smaller that 1. The lowest ratio that works for a given graph depends on the graph structure and the source vertex. For a rather sparse graph, a small ratio may work, but for a dense graph, a ratio of 1.0 is required.
+This is an experimental parameter that controls the size of the heap used in the algorithm. The heap is a static array that is used to store the vertices that may be visited next. A value of 1.0 means that the heap is the same size as the number of vertices, so there is no risk of overflow. Be aware that there is no guarantee that the algorithm will work with a heap length ratio smaller that 1. The lowest ratio that works for a given graph depends on the graph structure and the source vertex. For a rather sparse graph, a small ratio may work, but for a dense graph, a ratio of 1.0 is required.
 
 ## Contributing
 

{edsger-0.0.14 → edsger-0.1.0}/README.md

@@ -171,11 +171,11 @@ shortest_paths[-5:]
 
 ####  Run method options
 
-The `run` method can take the following arguments besides the source vertex index:
+The `run` method can take the following arguments besides the source/target vertex index:
 
 - `path_tracking` : bool, optional (default=False)
 
-Whether to track the shortest path(s) from the source vertex to all other vertices in the graph.
+Whether to track the shortest path(s) from/to the source/target vertex to all other vertices in the graph.
 
 ```python
 dijkstra = Dijkstra(edges)
@@ -195,7 +195,7 @@ The path is returned as an array of vertex indices. This is an ordered list of v
 
 - `return_inf` : bool, optional (default=True)
     
-Whether to return path length(s) as infinity (np.inf) when no path exists.
+Whether to return path lengths as infinity (np.inf) when no path exists.
 
 ```python
 dijkstra = Dijkstra(edges, orientation='in')
@@ -228,7 +228,7 @@ shortest_paths
 
 - `heap_length_ratio` : float, optional (default=1.0)
     
-This is an experimental parameter that controls the size of the heap used in the algorithm. The heap is a static array that is used to store the vertices that are may be visited next. A value of 1.0 means that the heap is the same size as the number of vertices, so there is no risk of overflow. Be aware that there is no guarantee that the algorithm will work with a heap length smaller that 1. The lowest ratio that works for a given graph depends on the graph structure and the source vertex. For a rather sparse graph, a small ratio may work, but for a dense graph, a ratio of 1.0 is required.
+This is an experimental parameter that controls the size of the heap used in the algorithm. The heap is a static array that is used to store the vertices that may be visited next. A value of 1.0 means that the heap is the same size as the number of vertices, so there is no risk of overflow. Be aware that there is no guarantee that the algorithm will work with a heap length ratio smaller that 1. The lowest ratio that works for a given graph depends on the graph structure and the source vertex. For a rather sparse graph, a small ratio may work, but for a dense graph, a ratio of 1.0 is required.
 
 ## Contributing
 

{edsger-0.0.14 → edsger-0.1.0}/docs/Makefile

@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

edsger-0.1.0/docs/requirements.txt

@@ -0,0 +1,19 @@
+# Documentation build requirements
+sphinx>=7.0.0
+myst-parser>=2.0.0
+sphinx-autodoc-typehints>=1.22.0
+sphinx-copybutton>=0.5.0
+furo>=2023.5.20
+
+# Required for building Cython extensions during doc build
+numpy>=1.26
+pandas>=2.0
+Cython>=3.0
+setuptools>=61.0
+
+# Optional but recommended
+sphinx-design>=0.5.0
+sphinx-tabs>=3.4.0
+
+# ReadTheDocs specific
+readthedocs-sphinx-search>=0.3.0

edsger-0.1.0/docs/source/api.md

@@ -0,0 +1,136 @@
+# API Reference
+
+This section provides detailed documentation for all public classes and functions in Edsger.
+
+## edsger.path Module
+
+### Dijkstra Class
+
+The main class for performing Dijkstra's shortest path algorithm.
+
+#### Constructor Parameters
+
+- `edges`: pandas.DataFrame containing the graph edges
+- `tail`: Column name for edge source nodes (default: 'tail')
+- `head`: Column name for edge destination nodes (default: 'head')
+- `weight`: Column name for edge weights (default: 'weight')
+- `orientation`: Either 'out' (single-source) or 'in' (single-target) (default: 'out')
+- `check_edges`: Whether to validate edge data (default: False)
+- `permute`: Whether to optimize node indexing (default: False)
+
+#### Methods
+
+##### run
+
+```python
+def run(self, vertex_idx, path_tracking=False, return_inf=True, 
+        return_series=False, heap_length_ratio=1.0)
+```
+
+Runs the shortest path algorithm from/to the specified vertex.
+
+**Parameters:**
+- `vertex_idx`: Source/target vertex index
+- `path_tracking`: Whether to track paths for reconstruction (default: False)
+- `return_inf`: Return infinity for unreachable vertices (default: True)
+- `return_series`: Return results as pandas Series (default: False)
+- `heap_length_ratio`: Heap size as fraction of vertices (default: 1.0)
+
+**Returns:**
+- Array or Series of shortest path lengths
+
+##### get_path
+
+```python
+def get_path(self, vertex_idx)
+```
+
+Reconstructs the shortest path to/from a vertex (requires `path_tracking=True`).
+
+**Parameters:**
+- `vertex_idx`: Destination/source vertex index
+
+**Returns:**
+- Array of vertex indices forming the path
+
+##### get_vertices
+
+```python
+def get_vertices(self)
+```
+
+Returns all vertices in the graph.
+
+**Returns:**
+- Array of vertex indices
+
+### Examples
+
+#### Basic Usage
+
+```python
+from edsger.path import Dijkstra
+import pandas as pd
+
+# Create a graph
+edges = pd.DataFrame({
+    'tail': [0, 0, 1],
+    'head': [1, 2, 2],
+    'weight': [1, 4, 2]
+})
+
+# Initialize Dijkstra
+dijkstra = Dijkstra(edges)
+
+# Find shortest paths from vertex 0
+paths = dijkstra.run(vertex_idx=0)
+```
+
+#### With Path Tracking
+
+```python
+# Enable path tracking
+paths = dijkstra.run(vertex_idx=0, path_tracking=True)
+
+# Get the actual path to vertex 2
+path = dijkstra.get_path(vertex_idx=2)
+```
+
+#### Custom Parameters
+
+```python
+# Create with custom settings
+dijkstra = Dijkstra(
+    edges,
+    orientation='in',
+    check_edges=True,
+    permute=True
+)
+
+# Run with custom parameters
+paths = dijkstra.run(
+    vertex_idx=2,
+    return_series=True,
+    heap_length_ratio=0.5
+)
+```
+
+### Graph Data Format
+
+Edsger expects graph data as a pandas DataFrame with the following structure:
+
+| Column | Type    | Description                          |
+|--------|---------|--------------------------------------|
+| tail   | int     | Source vertex ID                     |
+| head   | int     | Destination vertex ID                |
+| weight | float   | Edge weight (must be non-negative)   |
+
+Example:
+```python
+edges = pd.DataFrame({
+    'tail': [0, 0, 1, 2],
+    'head': [1, 2, 2, 3],
+    'weight': [1.0, 4.0, 2.0, 1.0]
+})
+```
+

{edsger-0.0.14 → edsger-0.1.0}/docs/source/conf.py

@@ -3,7 +3,6 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-
 # -- Path setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -13,7 +12,7 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath("../../src/edsger/"))
+sys.path.insert(0, os.path.abspath("../../src/"))
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
@@ -22,6 +21,16 @@ project = "Edsger"
 copyright = "2024, Architecture & Performance"
 author = "Francois Pacull"
 
+# Get version from the package
+try:
+    from edsger._version import __version__
+    release = __version__
+    version = __version__
+except ImportError:
+    # Fallback if import fails
+    release = "0.0.15"
+    version = "0.0.15"
+
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
@@ -44,5 +53,22 @@ extensions = [
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
     "sphinx_design",
+    "myst_parser",  # Enable MyST parser for Markdown
+    "sphinx_copybutton",
 ]
+
+# MyST parser configuration
+myst_enable_extensions = [
+    "deflist",
+    "tasklist",
+    "html_admonition",
+    "html_image",
+]
+
+# Source suffix
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}

edsger-0.1.0/docs/source/contributing.md

@@ -0,0 +1,69 @@
+# Contributing to Edsger
+
+We welcome contributions to the Edsger library! This document provides guidelines for contributing to the project.
+
+## Getting Started
+
+### Development Environment
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/aetperf/Edsger.git
+   cd Edsger
+   ```
+
+2. Create a virtual environment:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+3. Install development dependencies:
+   ```bash
+   pip install -r requirements-dev.txt
+   pip install -e .
+   ```
+
+## Development Guidelines
+
+### Code Style
+
+- Follow PEP 8 for Python code
+- Use meaningful variable and function names
+- Add docstrings to all public functions and classes
+- Keep functions focused and concise
+
+### Testing
+
+- Write tests for all new features
+- Ensure all tests pass before submitting a pull request
+- Aim for high test coverage
+
+### Documentation
+
+- Update documentation for any new features or changes
+- Use clear and concise language
+- Include examples where appropriate
+
+## Submitting Changes
+
+1. Fork the repository on GitHub
+2. Create a new branch for your feature or bugfix
+3. Make your changes and commit them with clear commit messages
+4. Push your branch to your fork
+5. Submit a pull request with a clear description of your changes
+
+## Reporting Issues
+
+When reporting issues, please include:
+
+- A clear description of the problem
+- Steps to reproduce the issue
+- Expected vs actual behavior
+- System information (OS, Python version, etc.)
+
+## Questions?
+
+If you have questions about contributing, please open an issue on GitHub or contact the maintainers.
+
+Thank you for contributing to Edsger!

edsger-0.1.0/docs/source/index.md

@@ -0,0 +1,54 @@
+---
+github_url: https://github.com/aetperf/Edsger
+---
+
+# Edsger
+
+*Graph algorithms in Cython*
+
+Welcome to the Edsger documentation! Edsger is a Python library for efficient graph algorithms implemented in Cython. The library currently focuses on shortest path algorithms, with Dijkstra's algorithm fully implemented and additional algorithms planned for future releases.
+
+## Key Features
+
+- Fast implementation of Dijkstra's algorithm
+- Support for both single-source and single-target shortest paths
+- Easy integration with pandas DataFrames
+- Memory-efficient 4-ary heap implementation
+- Path tracking and reconstruction capabilities
+
+## Quick Links
+
+- [Installation](installation.md) - How to install Edsger
+- [Quick Start](quickstart.md) - Get started quickly with basic examples
+- [API Reference](api.md) - Complete API reference
+
+## Table of Contents
+
+```{toctree}
+:maxdepth: 2
+:caption: User Guide
+
+installation
+quickstart
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: API Reference
+
+api
+```
+
+```{toctree}
+:maxdepth: 1
+:caption: Development
+
+contributing
+```
+
+## Indices
+
+- {ref}`genindex`
+- {ref}`modindex`
+- {ref}`search`
+

edsger-0.1.0/docs/source/installation.md

@@ -0,0 +1,148 @@
+# Installation Guide
+
+This guide will help you install the `edsger` package on your system.
+
+## Requirements
+
+Before you begin, ensure you have the following prerequisites:
+
+- Python 3.11 or higher
+- pip (Python package installer) or uv (recommended)
+- (Optional) git for installing from source
+
+## Method 1: Using Python venv + pip
+
+Create a virtual environment and install with pip:
+
+```bash
+# Create a virtual environment
+python -m venv edsger-env
+
+# Activate the virtual environment
+source edsger-env/bin/activate  # On Windows: edsger-env\Scripts\activate
+
+# Install edsger
+pip install edsger
+```
+
+## Method 2: Using uv (Recommended)
+
+[uv](https://github.com/astral-sh/uv) provides faster installation and better dependency resolution:
+
+```bash
+# Install uv if you haven't already
+pip install uv
+
+# Create a virtual environment with uv
+uv venv edsger-env
+
+# Activate the virtual environment
+source edsger-env/bin/activate  # On Windows: edsger-env\Scripts\activate
+
+# Install edsger
+uv pip install edsger
+```
+
+## Installing from Source
+
+If you prefer to install from source or contribute to development:
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/aetperf/Edsger.git
+cd Edsger
+```
+
+### 2. Using Python venv + pip
+
+```bash
+# Create and activate virtual environment
+python -m venv edsger-env
+source edsger-env/bin/activate  # On Windows: edsger-env\Scripts\activate
+
+# Install in editable mode
+pip install -e .
+```
+
+### 3. Using uv (Recommended)
+
+```bash
+# Create and activate virtual environment
+uv venv edsger-env
+source edsger-env/bin/activate  # On Windows: edsger-env\Scripts\activate
+
+# Install in editable mode
+uv pip install -e .
+```
+
+### 4. Verify the Installation
+
+Check that the installation was successful by importing the package in a Python shell:
+
+```python
+python
+>>> import edsger
+>>> edsger.__version__
+```
+
+You should see the version number of the `edsger` package.
+
+## Development Installation
+
+For contributors who need development dependencies:
+
+### Using Python venv + pip
+
+```bash
+# Create and activate virtual environment
+python -m venv edsger-env
+source edsger-env/bin/activate  # On Windows: edsger-env\Scripts\activate
+
+# Install development dependencies
+pip install -r requirements-dev.txt
+pip install -e .
+```
+
+### Using uv (Recommended)
+
+```bash
+# Create and activate virtual environment
+uv venv edsger-env
+source edsger-env/bin/activate  # On Windows: edsger-env\Scripts\activate
+
+# Install development dependencies
+uv pip install -r requirements-dev.txt
+uv pip install -e .
+```
+
+## Troubleshooting
+
+### Module Not Found Error
+
+If you encounter a `ModuleNotFoundError`, make sure that:
+1. The `edsger` package is installed correctly
+2. You're using the correct Python environment
+3. The `PYTHONPATH` is set appropriately (if needed)
+
+### Compilation Issues
+
+If you experience compilation issues, ensure you have:
+- A working C compiler
+- NumPy installed
+- Cython >= 3.0 installed
+
+## Uninstallation
+
+To uninstall the `edsger` package:
+
+```bash
+pip uninstall edsger
+```
+
+## Getting Help
+
+For further assistance:
+- Check the [documentation](index.md)
+- Open an issue on [GitHub](https://github.com/aetperf/Edsger)
+- Contact the maintainer at [francois.pacull@architecture-performance.fr](mailto:francois.pacull@architecture-performance.fr)