v3.4.0

.github/workflows/continuous-integration-pip.yml

@@ -26,18 +26,17 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v2
+        uses: github/codeql-action/init@v3
         # Override language selection
         with:
           languages: python
-          setup-python-dependencies: false
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v2
+        uses: github/codeql-action/analyze@v3
 
   test-pip:
     needs: skip_duplicate
@@ -48,9 +47,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        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
@@ -59,29 +58,32 @@ jobs:
           python -m pip install --upgrade -r requirements_ci.txt
       - name: Lint all python files with flake8
         run: |
-          # stop the build if there are flake8 errors (E203,W505 not compatible to black)
-          flake8 src tests --count --extend-ignore=E203,W503 --max-line-length=88 --show-source --statistics
+          # stop the build if there are flake8 errors
+          flake8 src tests --count --show-source --statistics
       - name: Type check package source with mypy
         run: |
           mypy src/nographs
       - name: Check source code formatting with Black
         run: |
-          black src/nographs --check --verbose --diff
+          black src/nographs tests --check --verbose --diff
       - name: Install from source (required for the pre-commit tests)
         run: python -m pip install .
       - name: Run all tests (including doc tests)
         run: python ./tests/test_nographs.py
       - name: Upload coverage
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
+        with:
+          fail_ci_if_error: true
+          token: ${{ secrets.CODECOV_TOKEN }}
 
   build:
     name: Build
     runs-on: ubuntu-latest
     steps:
       - name: Checkout source
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Set up Python 3.9
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: 3.9
       - name: Build package
@@ -99,9 +101,9 @@ jobs:
 #    runs-on: ubuntu-latest
 #    steps:
 #      - name: Checkout source
-#        uses: actions/checkout@v3
+#        uses: actions/checkout@v4
 #      - name: Set up Python 3.9
-#        uses: actions/setup-python@v4
+#        uses: actions/setup-python@v5
 #        with:
 #          python-version: 3.9
 #      - name: Build package

README.rst

@@ -62,10 +62,14 @@ Think of it as *graph analysis - the lazy (evaluation) way*.
 - Unidirectional traversal algorithms: DFS, BFS, topological search,
   Dijkstra, A\* and MST.
 - Bidirectional search algorithms: BFS and Dijkstra.
-- Results: Reachability, depth, distance, paths and trees.
+- Results: Reachability, depth, distance, and paths.
   Paths can be
   calculated with vertices, edges, or attributed edges,
   and can be iterated in both directions.
+  Additionally, for DFS:
+  forest, all kinds of edge types, both entering and leaving events,
+  and DFS tree edges or
+  all paths or all walks.
 - Flexible graph notion:
 
   - Infinite directed multigraphs with loops and
@@ -119,14 +123,26 @@ Think of it as *graph analysis - the lazy (evaluation) way*.
   positive / zero / negative edge weights, graph does not need to be complete)
 - Dijkstra shortest paths algorithm for
   infinitely branching graphs with locally sorted edges.
-- Example for computing the
-  longest path
-  between two vertices in a weighted, acyclic graph.
 - Gadget functions for test purposes. They make the easy task of
   adapting existing explicit test graphs a no brainer, may they be
   stored in edge indices or edge iterables
   or in arrays.
 
+**Examples with further algorithms**
+
+- Depth-limited search
+- Iterative deepening depth-first search
+- Critical path
+  in a weighted, acyclic graph
+- Longest path
+  between two vertices in a weighted, acyclic graph
+- Longest path
+  between two vertices in a weighted graph or in an unweighted graph
+- Strongly connected components
+  of a graph
+- Biconnected components of a connected undirected graph
+
+
 **Example**
 
 Our graph is directed, weighted and has infinitely many edges. These edges are

docs/source/api.rst

@@ -433,6 +433,14 @@ the comparing examples `here <examples_all_graphs>`, and
 TraversalDepthFirst
 +++++++++++++++++++
 
+**Enumerations used in the definition of parameters:**
+
+.. autoclass:: DFSEvent
+
+.. autoclass:: DFSMode
+
+**About the class:**
+
 Examples: See `example-traversal-depth-first-integers` and
 the comparing examples `here <examples_all_graphs>`.
 
@@ -445,8 +453,22 @@ the comparing examples `here <examples_all_graphs>`.
 
    .. autoattribute:: visited
 
+   .. autoattribute:: event
+
+   .. autoattribute:: trace
+
+   .. autoattribute:: trace_labels
+
+   .. autoattribute:: on_trace
+
+   .. autoattribute:: index
+
    .. automethod:: start_from
 
+   .. automethod:: __iter__
+
+   .. automethod:: skip_expanding_entered_vertex
+
 .. autoclass:: TraversalDepthFirst
    :show-inheritance: yes
 

docs/source/bidirectional_search.rst

@@ -5,9 +5,7 @@ Bidirectional search algorithms
    Import nographs for doctests of this document. Does not go into docs.
    >>> import nographs as nog
 
-.. versionchanged:: 3.1
-
-   Bidirectional search algorithms added.
+.. versionadded:: 3.1
 
 The analysis algorithms `presented so far <traversals>` traverse a graph
 in "forward" direction, i.e., they start from one or more start vertices, follow the

docs/source/changelog.rst

@@ -1,6 +1,44 @@
 ChangeLog
 ---------
 
+**v3.4.0** (2024-07-25)
+
+- Method TraversalDepthsFirst.start_from: New parameters:
+
+  - report: Instead of just ENTERING_SUCCESSOR, many
+    different events can be chosen to be reported.
+  - mode: Two new traversal modes can be chosen, ALL_PATHS and ALL_WALKS.
+  - compute_trace: Maintains the list of the vertices on the trace,
+    the current path from a start vertex to the current vertex.
+  - compute_on_trace: Maintains the set of the vertices on the trace.
+  - compute_index: Numbers vertices in DFS pre-order.
+
+- Class TraversalDepthsFirst:
+
+  - Start vertices are evaluated successively. This enables a direct
+    computation of the DFS forest.
+  - Attribute __iter__ is now a generator instead of just an iterator,
+    and throwing a *StopIteration*
+    signals to the generator to skip the vertex that has just be entered
+    and reported.
+
+- Methods *start_from* of traversals: Argument for parameter *start_vertices*
+  is traversed at most once. Thus, it can be an Iterator or a Generator.
+
+- Tutorial: Further examples added:
+
+  - depth-limited search
+  - iterative deepening depth-first search (IDDFS)
+  - longest path between two vertices in a weighted graph or in an
+    unweighted graph
+  - strongly connected components of a graph
+  - biconnected components of a connected undirected graph (Tarjan).
+
+- Code quality improved: Code structure improved.
+  Source code macro system used to improve code consistency.
+
+- pyproject.toml instead of setup.py
+
 **v3.3.2** (2024-02-04)
 
 - Added method paths.predecessor