pyarch

The tool to generate dynamic class diagrams of python packages to facilitate their development and maintenance.

Motivation:

• Reduction of the cognitive load when learning the structure of a new package.
• Identification of architecture bottlenecks using static analysis of inter-modular dependencies.

Demo

• sklearn
• SuperDuperDB
• Sanic
• FastAPI

GitHub Action

Pyarch can be executed as part of GitHub workflow.

Inputs

Attribute	Description	Required	Default
input	Directory with the package source code	true
output	Directory to save generated HTML file	false	.pyarch/output
title	Custom HTML title	false	Python package architecture
header	Custom HTML header	false	Python package architecture
footer	Custom HTML footer	false	<p style="font-size:15px">Built with ❤️ by <a href="https://www.dkisler.com" target=_blank>Dmitry Kisler - dkisler.com</a></p>

Outputs

• output: Path to generated HTML file.

Example: deployment of the package architecture diagram to GitHub Pages

The following GitHub workflow can be used to generate the package architecture diagram and to publish it using GitHub pages.

name: "Pyarch Pages"

on:
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  pyarch-pages:
    runs-on: ubuntu-20.04
    steps:
      # assumption: the workflow is running in the python package repo
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Generate HTML
        uses: kislerdm/[email protected]
        with:
          # Change to the path with the package's source files
          input: src
          title: "Architecture of my package"
          header: "Architecture of my package"
          output: public

      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: 'public'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

Standalone

How to install

Prerequisites:

• python >= 3.8

Steps

1. Download the latest release of the python script
2. Move it to the bin directory /usr/local/bin
3. Run the script to validate the version:

pyarch --version

Note that sudo permissions will be required. Alternatively, the script can be executed without the step 2:

python3 pyarch --version

Demo

Note curl is required.

sudo curl -SLo /usr/local/bin/pyarch https://github.com/kislerdm/pyarch/releases/download/v0.0.1/pyarch &&\
pyarch --version

Output:

version: 0.0.1

How to use

Prerequisites:

• pylint
• pyarch

Follow the steps to generate the webpage with dynamic architecture diagrams of sklearn:

1. Create a clean directory

mkdir sklearn-diagram && cd sklearn-diagram 

2. Clone sklearn from GitHub to the local repository:

git clone [email protected]:scikit-learn/scikit-learn.git code

3. Generate the package architecture diagrams as UML using pyreverse

pyreverse -Akmy -o puml -d . --ignore=test,tests code/sklearn

4. Generate the webpage with the dynamic diagrams:

pyarch -i . -o . -v --title="sklearn architecture" --header="sklearn architecture"

The directory is expected to have the following structure:

.
├── code
├── classes.puml
├── packages.puml
└── index.html

Open index.html using a web-browser:

Distribution and contribution

The project is distributed under the MIT license - feel free to use it as you will.

Please open github issue, and/or PR with a change proposal to collaborate.