PYDUS - Python Diagram UML Specific

A lightweight bash tool built as a wrapper around pyreverse that automatically generates individual UML class diagrams for Python files.

Requirements

Essential

• Python 3.x
• pyreverse (included in pylint package)

pip install pylint

Optional (for PNG and PDF formats)

• Graphviz - Required for PNG and PDF generation

Ubuntu/Debian:

sudo apt-get install graphviz

macOS:

brew install graphviz

Windows:

choco install graphviz

Installation

Cloning the repository

Before installing the tool, start by cloning the GitHub repository :

git clone https://github.com/JRosierIGN/PyDUS.git
cd PyDUS

Global installation (recommended)

To use pydus from anywhere on your system, follow the instructions below:

Ubuntu/Debian:

# Make the script executable
chmod +x pydus.sh

# Install globally
sudo cp pydus.sh /usr/local/bin/pydus

Local installation (without sudo)

Ubuntu/Debian:

# Create local bin directory if it doesn't exist
mkdir -p ~/.local/bin

# Copy and make executable
cp pydus.sh ~/.local/bin/pydus
chmod +x ~/.local/bin/pydus

# Add to PATH (add this line to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

# Reload your shell configuration
source ~/.bashrc  # or source ~/.zshrc

Windows:

Add the script to the PATH for global access:

1. Place pydus.bat in a folder, for example C:\Program Files\PyDus
2. Add this folder to your PATH environment variable:
   • Open the Start menu, search for Environment Variables, and open Edit the system environment variables
   • Click Environment Variables…
   • In the User variables section, select Path and click Edit…
   • Click New and add C:\Program Files\PyDus
   • Click OK to close all windows

Usage

Basic syntax

pydus [options] <source_directory> <output_directory> [format]

Options

• -v, --verbose - Show detailed output from pyreverse during processing
• -h, --help - Display help message with complete documentation

Arguments

• source_directory - Root directory containing .py files to analyze
• output_directory - Directory where generated diagrams will be saved
• format - (Optional) Output format: svg, png, dot, or pdf (default: svg)

Examples

Generate SVG diagrams (default):

pydus ./my_project ./docs/uml

Generate PNG diagrams:

pydus ./my_project ./docs/uml png

Generate PDF diagrams:

pydus ./my_project ./docs/uml pdf

Generate DOT files for custom processing:

pydus ./my_project ./docs/uml dot

Verbose mode for debugging:

pydus -v ./my_project ./docs/uml svg

Get help:

pydus --help
# or
pydus -h

Output Formats

Format	Extension	Description	Graphviz Required
svg	.svg	Scalable Vector Graphics (recommended)	No
png	.png	Portable Network Graphics (raster)	Yes
pdf	.pdf	Portable Document Format	Yes
dot	.dot	Graphviz DOT format for further processing	No

Project Structure Example

Input structure

my_project/
├── models/
│   ├── user.py          # Contains User class
│   ├── product.py       # Contains Product class
│   └── __init__.py      # Automatically skipped
├── utils/
│   ├── helpers.py       # Contains Helper class
│   └── config.py        # No class - skipped
└── main.py              # No class - skipped

Output after running pydus ./my_project ./uml_output svg

uml_output/
├── user.svg
├── product.svg
└── helpers.svg

What Gets Processed

Included

• Python files (.py) containing one or more class definitions
• Files in subdirectories
• All class types (regular classes, abstract classes, dataclasses, etc.)

Excluded

• __init__.py files
• Python scripts without class definitions
• Non-Python files

Diagram Content

Each generated diagram includes:

• Class names
• Attributes with type annotations
• Methods with parameters and return types

Troubleshooting

Error: "pyreverse not found"

pip install pylint

PNG/PDF generation fails

# Install Graphviz (see Requirements section)

Permission denied

chmod +x pydus.sh

Script not found after installation

# Make sure ~/.local/bin is in your PATH
echo $PATH | grep ".local/bin"