eaidl

This is replacement for idl4-enterprise-architect, but not as plugin, but rather something that can be run as part of CI against database. Similar in concepts in pyMDG, but we have some different assumptions on model structure.

For detailed code structure documentation, see STRUCTURE.md.

setup environment

Using uv (recommended)

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync dependencies including dev tools (pytest, ruff, pre-commit)
uv sync --extra dev

# Install pre-commit hooks
uv run pre-commit install

# Run tests
uv run pytest

Alternative: Using pyenv

# This example uses pyenv
pyenv update
pyenv install 3.13
pyenv virtualenv 3.13 eaidl
pyenv activate eaidl

# Development mode install
pip install -e "."
# We use pre-commit hook
pre-commit install
pytest

Quick Start

Running Tests

uv run pytest                          # All tests
uv run pytest tests/test_diagram.py -v  # Specific test file
uv run pytest --cov=src/eaidl           # With coverage

Running the Tool

There are sample configuration files provided in config.

# Generate IDL from sample SQLite database:
uv run eaidl run --config config/sqlite.yaml

# Generate IDL from PostgreSQL (needs custom configuration):
uv run eaidl run --config config/postgres.yaml > res.idl

# Other commands available:
uv run eaidl diagram --config config/sqlite.yaml --output diagram.puml  # Generate PlantUML diagram
uv run eaidl packages --config config/sqlite.yaml                        # List packages
uv run eaidl docs --config config/sqlite.yaml --output ./_docs           # Generate HTML docs

# Export/import notes for review by non-EA users:
uv run eaidl export-notes --config config/sqlite.yaml --output notes.docx  # Export notes to DOCX
uv run eaidl import-notes --config config/sqlite.yaml --input notes.docx   # Import edited notes (dry-run)

# Export full model structure to YAML or Markdown:
uv run eaidl export-model --config config/sqlite.yaml --output model.yaml              # YAML (default)
uv run eaidl export-model --config config/sqlite.yaml --output model.md --format markdown  # Markdown
uv run eaidl export-model --config config/sqlite.yaml --output model.md --format markdown --diagrams-dir images  # with diagram images

Export and Import Notes for External Review

Export model notes to DOCX for non-EA users to edit, then import changes back:

# Export all notes to DOCX (hierarchical: packages/classes/attributes)
uv run eaidl export-notes --config config/sqlite.yaml --output notes.docx

# Import changes (dry-run by default, use --no-dry-run to commit)
uv run eaidl import-notes --config config/sqlite.yaml --input notes.docx
uv run eaidl import-notes --config config/sqlite.yaml --input notes.docx --no-dry-run  # Live

The export includes metadata for validation. Import supports partial updates (checksum-matched) for parallel editing workflows. Use --strict to fail on mismatches, --report for JSON output.

Export Full Model Structure

The export-model command exports the complete model (all packages, classes, attributes, and relations) to a portable YAML or Markdown file. Packages are listed flat with child packages referenced by GUID.

# Export to YAML (default)
uv run eaidl export-model --config config/sqlite.yaml --output model.yaml

# Export to Markdown
uv run eaidl export-model --config config/sqlite.yaml --output model.md --format markdown

# Export to Markdown with embedded diagram images
uv run eaidl export-model --config config/sqlite.yaml --output model.md --format markdown --diagrams-dir images

The --diagrams-dir option specifies a directory (relative to the output file) containing exported diagram images; when provided, Markdown output embeds them inline.

using uvx

uvx --with sqlite --from git+https://github.com/piappl/ea-idl/ eaidl run --config config/sqlite.yaml
uvx --with psycopg2 --from git+https://github.com/piappl/ea-idl/ eaidl run --config config/postgres.yaml

Generate Interactive HTML Documentation

The docs command generates a complete static website with interactive documentation from your EA model:

# Generate HTML documentation
uv run eaidl docs --config config/sqlite.yaml --output ./docs

# With debug logging
uv run eaidl docs --config config/sqlite.yaml --output ./docs --debug

By default the docs apply the same model transforms as the run command (stereotype filtering, privatization, empty-union collapse, map conversion, abstract-class flattening and unused-class pruning), so the documentation mirrors the generated IDL. Use --raw to skip all transforms and document the unprocessed loaded model:

# Document the raw model, no transforms applied
uv run eaidl docs --config config/sqlite.yaml --output ./docs --raw

Note: Classes removed by transforms (e.g. via filter_stereotypes) get no class page and drop out of auto-generated class diagrams. EA-authored (hand-drawn) diagrams still render filtered classes as nodes, but their cross-reference links won't resolve since the class is no longer in the model.

Regenerate docs

cd scripts
# export WINEPREFIX=~/.wine32
# export WINEARCH=win32
./export_diagrams.sh --model ${PWD}/../tests/data/nafv4.qea  --output /tmp
# rm -r ../docs/images/{data,message}
cp -r /tmp/Model/core/* ../docs/images