byecycle 🚲

Find and expose cyclic imports in python projects.

Installation

byecycle uses the built-in ast module to parse code files. As a consequence, it can only handle python code within the same major version (read: no support for python 1 and 2), and the same or lower minor version of the python interpreter it was installed with. If byecycle raises SyntaxErrors in code that you know to be working, try using a byecycle that is installed with the same python version that can run the code in question.

From PyPI

Requirements:

• python 3.11 or higher
• pipx

pipx install byecycle

Development Setup

Requirements:

• python 3.11 or higher
• pdm
• git

git clone https://github.com/a-recknagel/byecycle.git
cd byecycle
pdm install -G:all

Usage

As a Command Line Tool

# with a path
byecycle /home/me/dev/byecycle/src/byecycle/
# or the name of an installed package
byecycle byecycle

The result will be a json string:

{
  "byecycle.misc": {},
  "byecycle.graph": {
    "byecycle": {
      "tags": [
        "vanilla",
        "parent"
      ],
      "cycle": "complicated"
    },
    "byecycle.misc": {
      "tags": [
        "vanilla"
      ],
      "cycle": null
    }
  },
  [...]
  "byecycle": {
    "byecycle.graph": {
      "tags": [
        "vanilla",
        "parent"
      ],
      "cycle": "complicated"
    }
  }
}

By default, the result is printed with some rich formatting to highlight types and such. If you need the output to be plain ascii, pass the --no-rich flag.

For bigger projects, you might get much more complex output. The intent of returning json is to have something that can be easily piped into e.g. jq for further processing:

# filter out imports that don't have a cycle
byecycle byecycle | jq '.[] |= (.[] |= select(.cycle != null) | select(. != {}))'

{
  "byecycle.graph": {
    "byecycle": {
      "tags": [
        "parent",
        "vanilla"
      ],
      "cycle": "complicated"
    }
  },
  "byecycle.cli": {
    "byecycle": {
      "tags": [
        "parent",
        "vanilla"
      ],
      "cycle": "complicated"
    }
  },
  "byecycle": {
    "byecycle.graph": {
      "tags": [
        "parent",
        "vanilla"
      ],
      "cycle": "complicated"
    },
    "byecycle.cli": {
      "tags": [
        "parent",
        "vanilla"
      ],
      "cycle": "complicated"
    }
  }
}

Alternatively, you can also call the main entrypoint's core functionality as a regular python function. Among other things, it returns a dictionary equivalent to the CLI's json that you can work with:

from byecycle import run
cycles, *_ = run("byecycle")
# filter out imports that don't have a cycle
for outer_k, outer_v in cycles.items():
    for inner_k, inner_v in outer_v.items():
        if inner_v["cycle"]:
            print(f"{outer_k} -> {inner_k}: {inner_v['cycle']}")

byecycle.graph -> byecycle -> complicated
byecycle.cli -> byecycle -> complicated
byecycle -> byecycle.graph -> complicated
byecycle -> byecycle.cli -> complicated

See the help text of byecycle for an explanation of tags/ImportKinds and cycle/EdgeKinds.

In short, if there is a cycle, the tags of all involved imports inform the cycle-severity, with the highest severity winning out if multiple apply. The defaults can be overriden in order to isolate, filter, or highlight cycles with specific severities.

To Visualize the Import Graph

If you pass the --draw flag¹ on your command-line-call, byecycle will create an image of the import graph instead:

byecycle byecycle --draw

^[1] _{Requires installation of the draw-extra, i.e. pipx install "byecycle[draw]".}