plain-parser 0.1.1.dev2__tar.gz → 0.1.2__tar.gz

plain_parser-0.1.2/.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 3
+    commit-message:
+      prefix: "chore"
+    labels:
+      - "dependencies"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "ci"
+    labels:
+      - "dependencies"
+      - "github-actions"
+    groups:
+      actions-minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"

{plain_parser-0.1.1.dev2 → plain_parser-0.1.2}/.github/workflows/lint-and-test.yml

@@ -2,18 +2,24 @@ name: Code Quality & Tests
 
 on:
   # Pushes to PR branches are covered by pull_request; listening to every push
-  # too would run the suite twice per commit.
-  push:
-    branches: [main]
+  # too would run the suite twice per commit. Pushes to main are covered by
+  # the publish-dev-to-pypi workflow, which calls this one as a gate.
   pull_request:
   workflow_dispatch:
+  # Lets the publish workflows run these checks as a job and depend on it.
+  workflow_call:
+
+permissions:
+  contents: read
 
 jobs:
-  check:
+  lint-and-test:
     name: Lint and test
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.11"

{plain_parser-0.1.1.dev2 → plain_parser-0.1.2}/.github/workflows/publish-dev-to-pypi.yml

@@ -23,8 +23,18 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
+  pre-publish-checks:
+    name: Pre-publish checks
+    # Publishing is gated on the same checks PRs run: a red main must not
+    # ship. Running here rather than as a separate workflow is the only way
+    # to make the build job depend on the result.
+    uses: ./.github/workflows/lint-and-test.yml
+    permissions:
+      contents: read
+
   build:
     name: Build dev distribution
+    needs: pre-publish-checks
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -37,13 +47,15 @@ jobs:
         with:
           # hatch-vcs derives the version from git tags, so we need full history.
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Install uv
         # uv provisions its own Python (honoring requires-python), so no
         # separate actions/setup-python step is needed.
-        run: |
-          curl -LsSf https://astral.sh/uv/install.sh | sh
-          echo "$HOME/.local/bin" >> $GITHUB_PATH
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          version: "0.12.23"
+          enable-cache: false
 
       - name: Compute dev version
         id: version
@@ -55,7 +67,7 @@ jobs:
         # run number as the dev counter: it is strictly increasing, so each
         # merge sorts after the last and re-runs never collide.
         run: |
-          RAW=$(uvx --from setuptools-scm python -c \
+          RAW=$(uvx --from setuptools-scm==10.3.4 python -c \
             "from setuptools_scm import get_version; print(get_version())")
           echo "setuptools-scm reports: $RAW"
 
@@ -100,7 +112,7 @@ jobs:
   publish-dev:
     name: Publish dev build to PyPI
     needs: build
-    if: needs.build.outputs.should-publish == 'true'
+    if: github.ref == 'refs/heads/main' && needs.build.outputs.should-publish == 'true'
     runs-on: ubuntu-latest
     environment:
       name: pypi
@@ -110,9 +122,6 @@ jobs:
       # authenticate this run — no long-lived API token needed.
       id-token: write
 
-    env:
-      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
-
     steps:
       - name: Download distribution packages
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -128,20 +137,27 @@ jobs:
           skip-existing: true
 
       - name: Notify Slack (success)
-        if: ${{ success() && env.SLACK_WEBHOOK_URL != '' }}
+        if: success()
+        continue-on-error: true
         env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
           VERSION: ${{ needs.build.outputs.version }}
         run: |
           # Spell out the --pre install: a plain "pip install plain-parser" will
           # NOT pick this up, which otherwise reads as a broken publish.
           TEXT="*plain-parser*: dev build \`$VERSION\` published to PyPI :test_tube:. Normal installs are unaffected — try it with \`pip install --pre plain-parser==$VERSION\`."
-          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+          curl -sS --fail -X POST "$SLACK_WEBHOOK_URL" \
             -H 'Content-type: application/json' \
             --data "$(jq -n --arg t "$TEXT" '{text:$t}')"
 
       - name: Notify Slack (failure)
-        if: ${{ failure() && env.SLACK_WEBHOOK_URL != '' }}
+        if: failure()
+        continue-on-error: true
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
         run: |
-          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+          RUN_URL="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+          TEXT="*plain-parser*: Publishing dev build to PyPI FAILED :x: (commit \`$GITHUB_SHA\`). See <$RUN_URL|the run log>."
+          curl -sS --fail -X POST "$SLACK_WEBHOOK_URL" \
             -H 'Content-type: application/json' \
-            --data "{\"text\":\"*plain-parser*: Publishing dev build to PyPI FAILED :x: (commit \`${{ github.sha }}\`). See <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|the run log>.\"}"
+            --data "$(jq -n --arg t "$TEXT" '{text:$t}')"

plain_parser-0.1.2/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,171 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+# Least privilege by default: jobs get no GITHUB_TOKEN scopes unless they
+# opt in below.
+permissions: {}
+
+jobs:
+  pre-publish-checks:
+    name: Pre-publish checks
+    # Publishing is gated on the same checks PRs run: a red main must not
+    # ship. Running here rather than as a separate workflow is the only way
+    # to make the build job depend on the result.
+    uses: ./.github/workflows/lint-and-test.yml
+    permissions:
+      contents: read
+
+  build:
+    name: Build distribution
+    needs: pre-publish-checks
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # hatch-vcs derives the version from git tags, so we need full history.
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Notify Slack (start)
+        continue-on-error: true
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+          TAG: ${{ github.ref_name }}
+          ACTOR: ${{ github.actor }}
+        run: |
+          TEXT="*plain-parser*: Release \`$TAG\` published by *$ACTOR* — building and publishing to PyPI..."
+          curl -sS --fail -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "$(jq -n --arg t "$TEXT" '{text:$t}')"
+
+      - name: Install uv
+        # uv provisions its own Python (honoring requires-python), so no
+        # separate actions/setup-python step is needed.
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          version: "0.12.23"
+          enable-cache: false
+
+      - name: Build package
+        # hatch-vcs reads the version straight from the release tag.
+        run: |
+          uv build
+          echo "Built distributions:"
+          ls -l dist/
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Notify Slack (build failure)
+        if: failure()
+        continue-on-error: true
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          RUN_URL="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+          TEXT="*plain-parser*: Build of \`$TAG\` FAILED :x:. Nothing was published to PyPI. See <$RUN_URL|the run log>."
+          curl -sS --fail -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "$(jq -n --arg t "$TEXT" '{text:$t}')"
+
+  upload-release-assets:
+    name: Upload assets to GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Upload assets to GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          gh release upload "$TAG" dist/* --clobber
+
+      - name: Notify Slack (upload failure)
+        if: failure()
+        continue-on-error: true
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          RUN_URL="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+          TEXT="*plain-parser*: Uploading \`$TAG\` to the GitHub Release FAILED :x:. Nothing was published to PyPI. See <$RUN_URL|the run log>."
+          curl -sS --fail -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "$(jq -n --arg t "$TEXT" '{text:$t}')"
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: [build, upload-release-assets]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/plain-parser
+    permissions:
+      # Mint a short-lived OIDC token so PyPI Trusted Publishing can
+      # authenticate this run — no long-lived API token needed.
+      id-token: write
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+
+      - name: Notify Slack (success)
+        if: success()
+        continue-on-error: true
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+          # GitHub marks the release itself as a pre-release; the tag
+          # (v0.2.0rc1) carries the same intent for PEP 440.
+          IS_PRERELEASE: ${{ github.event.release.prerelease }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          VERSION="${TAG#v}"
+          if [ "$IS_PRERELEASE" = "true" ]; then
+            # pip and uv skip pre-releases by default, so "--upgrade" would
+            # NOT pick this up. Tell people the command that actually works.
+            TEXT="*plain-parser*: pre-release \`$TAG\` published to PyPI :test_tube:. Normal installs are unaffected — try it with \`pip install --pre plain-parser==$VERSION\`."
+          else
+            TEXT="*plain-parser*: \`$TAG\` published to PyPI :white_check_mark:. Install with \`pip install --upgrade plain-parser\`."
+          fi
+          curl -sS --fail -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "$(jq -n --arg t "$TEXT" '{text:$t}')"
+
+      - name: Notify Slack (failure)
+        if: failure()
+        continue-on-error: true
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          RUN_URL="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+          TEXT="*plain-parser*: Publishing \`$TAG\` to PyPI FAILED :x:. See <$RUN_URL|the run log>."
+          curl -sS --fail -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "$(jq -n --arg t "$TEXT" '{text:$t}')"

{plain_parser-0.1.1.dev2 → plain_parser-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plain-parser
-Version: 0.1.1.dev2
+Version: 0.1.2
 Summary: Parser for ***plain specification files
 License-Expression: MIT
 License-File: LICENSE
@@ -10,7 +10,6 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Software Development :: Compilers
 Requires-Python: >=3.11
 Requires-Dist: mistletoe<2,>=1.6.0
-Requires-Dist: networkx<4,>=3.6.1
 Requires-Dist: python-frontmatter<2,>=1.3.0
 Requires-Dist: python-liquid2<0.5,>=0.4.0
 Requires-Dist: pyyaml<7,>=6

{plain_parser-0.1.1.dev2 → plain_parser-0.1.2}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["hatchling", "hatch-vcs"]
+requires = ["hatchling>=1.32,<2", "hatch-vcs>=0.5,<0.6"]
 build-backend = "hatchling.build"
 
 [project]
@@ -20,7 +20,6 @@ dependencies = [
     "python-liquid2>=0.4.0,<0.5",
     "mistletoe>=1.6.0,<2",
     "python-frontmatter>=1.3.0,<2",
-    "networkx>=3.6.1,<4",
     "pyyaml>=6,<7",
 ]
 

{plain_parser-0.1.1.dev2 → plain_parser-0.1.2}/src/plain_parser/concept_utils.py

@@ -1,11 +1,11 @@
 import re
 from copy import deepcopy
+from graphlib import CycleError, TopologicalSorter
 from typing import Optional
 
 import mistletoe.block_token
-import networkx as nx
 
-from plain_parser import plain_spec
+from plain_parser import graph, plain_spec
 from plain_parser.exceptions import PlainSyntaxError
 
 # These are reserved concept names that are pre-defined and must not be redefined in the definitions section.
@@ -186,34 +186,63 @@ def build_adjacency_list(definitions: Optional[list[dict]]) -> tuple[dict, dict]
     return adjacency_list, concept_definitions
 
 
+MAX_REPORTED_CYCLES = 10
+
+
+def format_cycles_error(adjacency_list: dict[str, list[str]], concept_definitions: dict[str, dict]) -> str:
+    """
+    List the elementary cycles in the graph, each as a "Cycle N: :A: -> :B: -> :A:" line
+    followed by the definition of every concept in the cycle. Arrows point from a definition
+    to a concept it mentions, each cycle starts at its earliest-defined concept, and cycles
+    are ordered by definition position, so the report reads top to bottom like the file.
+    At most MAX_REPORTED_CYCLES are listed; the search stops once one more than that is found.
+    """
+    position = {concept: index for index, concept in enumerate(concept_definitions)}
+    cycles = []
+    # key the graph in definition order so a search cut short by the limit has found the earliest cycles
+    by_position = {concept: adjacency_list[concept] for concept in [*concept_definitions, *adjacency_list]}
+    for cycle in graph.simple_cycles(by_position, limit=MAX_REPORTED_CYCLES + 1):
+        # reverse since simple_cycles edges point from a used concept to the one defined with it
+        cycle = cycle[::-1]
+        first = min(range(len(cycle)), key=lambda i: position[cycle[i]])
+        cycles.append(cycle[first:] + cycle[:first])
+    cycles.sort(key=lambda cycle: (position[cycle[0]], len(cycle), [position[c] for c in cycle]))
+
+    if len(cycles) > MAX_REPORTED_CYCLES:
+        cycles = cycles[:MAX_REPORTED_CYCLES]
+        lines = [
+            f"Plain syntax error: Found more than {MAX_REPORTED_CYCLES} cycles in concept definitions. Cycles are not allowed.",
+            f"Showing the first {MAX_REPORTED_CYCLES}.",
+        ]
+    else:
+        lines = [f"Plain syntax error: Found {len(cycles)} cycle(s) in concept definitions. Cycles are not allowed."]
+    for number, cycle in enumerate(cycles, start=1):
+        lines.append("")
+        lines.append(f"Cycle {number}: " + " -> ".join(cycle + [cycle[0]]))
+        # concepts defined on one line can share a cycle; print that line once
+        lines.extend(dict.fromkeys(concept_definitions[concept]["markdown"] for concept in cycle))
+    return "\n".join(lines)
+
+
 def sort_definitions(definitions: list[dict]) -> list[dict]:
     if len(definitions) <= 1:
         return
 
     adjacency_list, concept_definitions = build_adjacency_list(definitions)
 
-    concept_graph = nx.DiGraph()
+    # adjacency_list maps a used concept to the concepts defined in terms of it,
+    # so the used concept is a predecessor of each of them
+    sorter: TopologicalSorter[str] = TopologicalSorter()
     for node, neighbors in adjacency_list.items():
+        sorter.add(node)
         for neighbour in neighbors:
-            concept_graph.add_edge(node, neighbour)
-        if not neighbors:
-            concept_graph.add_node(node)
-
-    if not nx.is_directed_acyclic_graph(concept_graph):
-        msg = "Found cycles in the concept graph. Cycles are not allowed."
-        all_cycles = list(nx.simple_cycles(concept_graph))
-
-        for cycle in all_cycles:
-            cyclic_definitions = []
-            cyclic_definitions.append(concept_definitions[cycle[0]]["markdown"])
-            cyclic_definitions.append(concept_definitions[cycle[1]]["markdown"])
-            msg += "Cyclic definitons:\n"
-            msg += "\n".join(cyclic_definitions)
-            msg += "\n"
+            sorter.add(neighbour, node)
 
-        raise PlainSyntaxError(f"Plain syntax error: {msg}")
+    try:
+        order = list(sorter.static_order())
+    except CycleError:
+        raise PlainSyntaxError(format_cycles_error(adjacency_list, concept_definitions)) from None
 
-    order = list(nx.topological_sort(concept_graph))
     if len(order) > 0:
         definition_to_order_idx = {
             plain_spec.hash_text(str(concept_definitions[concept])): idx for idx, concept in enumerate(order)

plain_parser-0.1.2/src/plain_parser/graph.py

@@ -0,0 +1,164 @@
+"""Cycle search over a directed graph given as a mapping from node to its successors.
+
+Nodes that appear only as successors are treated as having no outgoing edges.
+
+The search is Johnson's algorithm, written from the pseudocode in the paper, with the
+strongly connected components found by Tarjan's algorithm as given on Wikipedia.
+
+- D. B. Johnson, "Finding all the elementary circuits of a directed graph",
+  SIAM J. Comput. 4(1):77-84, 1975, doi:10.1137/0204007
+- R. Tarjan, "Depth-first search and linear graph algorithms",
+  SIAM J. Comput. 1(2):146-160, 1972, doi:10.1137/0201010
+- https://en.wikipedia.org/wiki/Tarjan%27s_strongly_connected_components_algorithm
+
+Both searches keep their own stack of frames instead of recursing, so the depth of a
+tangle is not limited by Python's recursion limit.
+"""
+
+import heapq
+from collections import defaultdict
+from collections.abc import Hashable, Iterable, Iterator, Mapping
+from typing import Optional, TypeVar
+
+Node = TypeVar("Node", bound=Hashable)
+
+
+def _successors(graph: Mapping[Node, Iterable[Node]]) -> dict[Node, list[Node]]:
+    # a repeated edge would otherwise yield every cycle through it once per repeat
+    successors = {node: list(dict.fromkeys(targets)) for node, targets in graph.items()}
+    for targets in list(successors.values()):
+        for target in targets:
+            successors.setdefault(target, [])
+    return successors
+
+
+def strongly_connected_components(graph: Mapping[Node, Iterable[Node]]) -> list[set[Node]]:
+    """Tarjan: one depth-first walk, each node stamped with its visit index and the lowest
+    index it can reach; a node whose lowest reachable index is its own closes a component."""
+    successors = _successors(graph)
+    index: dict[Node, int] = {}
+    lowlink: dict[Node, int] = {}
+    stack: list[Node] = []
+    on_stack: set[Node] = set()
+    components: list[set[Node]] = []
+
+    def visit(node: Node) -> tuple[Node, Iterator[Node]]:
+        index[node] = lowlink[node] = len(index)
+        stack.append(node)
+        on_stack.add(node)
+        return node, iter(successors[node])
+
+    for root in successors:
+        if root in index:
+            continue
+        frames = [visit(root)]
+        while frames:
+            node, targets = frames[-1]
+            for target in targets:
+                if target not in index:
+                    frames.append(visit(target))
+                    break
+                if target in on_stack:
+                    lowlink[node] = min(lowlink[node], index[target])
+            else:
+                frames.pop()
+                if frames:
+                    parent = frames[-1][0]
+                    lowlink[parent] = min(lowlink[parent], lowlink[node])
+                if lowlink[node] == index[node]:
+                    component: set[Node] = set()
+                    while True:
+                        member = stack.pop()
+                        on_stack.discard(member)
+                        component.add(member)
+                        if member == node:
+                            break
+                    components.append(component)
+    return components
+
+
+def _cycles_through(adjacency: dict[Node, list[Node]], s: Node) -> Iterator[list[Node]]:
+    """Johnson's CIRCUIT: every elementary cycle through `s` in one strongly connected component.
+
+    A node is blocked while it is on the path, and stays blocked after backtracking until a
+    cycle is found through some node it was waiting on."""
+    blocked: set[Node] = set()
+    blocked_map: dict[Node, set[Node]] = defaultdict(set)
+
+    def unblock(node: Node) -> None:
+        pending = [node]
+        while pending:
+            current = pending.pop()
+            blocked.discard(current)
+            pending.extend(waiting for waiting in blocked_map.pop(current, ()) if waiting in blocked)
+
+    path = [s]
+    blocked.add(s)
+    frames = [iter(adjacency[s])]
+    found_below = [False]
+    while frames:
+        node = path[-1]
+        for target in frames[-1]:
+            if target == s:
+                yield list(path)
+                found_below[-1] = True
+            elif target not in blocked:
+                path.append(target)
+                blocked.add(target)
+                frames.append(iter(adjacency[target]))
+                found_below.append(False)
+                break
+        else:
+            frames.pop()
+            path.pop()
+            if found_below.pop():
+                unblock(node)
+                if found_below:
+                    found_below[-1] = True
+            else:
+                for target in adjacency[node]:
+                    blocked_map[target].add(node)
+
+
+def _all_cycles(graph: Mapping[Node, Iterable[Node]]) -> Iterator[list[Node]]:
+    """Johnson's main loop: every cycle lies inside one strongly connected component, and
+    every cycle inside a component either passes through its least node or survives that
+    node's removal. So search each component from its least node, drop the node, and split
+    what is left into components again. Components are taken least node first, so a caller
+    that stops early has seen the cycles through the earliest nodes."""
+    successors = _successors(graph)
+    for node, targets in successors.items():
+        if node in targets:
+            yield [node]
+    successors = {node: [t for t in targets if t != node] for node, targets in successors.items()}
+    position = {node: i for i, node in enumerate(successors)}
+
+    # components are disjoint, so no two entries share a least position and the sets are never compared
+    components: list[tuple[int, set[Node]]] = []
+
+    def push_components(adjacency: Mapping[Node, Iterable[Node]]) -> None:
+        for component in strongly_connected_components(adjacency):
+            if len(component) >= 2:
+                heapq.heappush(components, (min(map(position.__getitem__, component)), component))
+
+    push_components(successors)
+    while components:
+        _, component = heapq.heappop(components)
+        s = min(component, key=position.__getitem__)
+        adjacency = {n: [t for t in successors[n] if t in component] for n in component}
+        yield from _cycles_through(adjacency, s)
+        del adjacency[s]
+        for targets in adjacency.values():
+            if s in targets:
+                targets.remove(s)
+        push_components(adjacency)
+
+
+def simple_cycles(graph: Mapping[Node, Iterable[Node]], limit: Optional[int] = None) -> Iterator[list[Node]]:
+    """Yield the elementary cycles of `graph`, each as its nodes in edge order, stopping
+    after `limit` cycles when one is given. Self-loops come first; longer cycles follow in
+    order of their earliest node in `graph`'s iteration order."""
+    for found, cycle in enumerate(_all_cycles(graph), start=1):
+        if limit is not None and found > limit:
+            return
+        yield cycle