retroflow 0.1.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,48 @@
1
+ name: Publish to PyPI
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - 'v*' # Triggers when you push a tag like v1.0.2
7
+
8
+ jobs:
9
+ test:
10
+ name: Test with coverage gate
11
+ runs-on: ubuntu-latest
12
+ steps:
13
+ - uses: actions/checkout@v4
14
+ - name: Install uv
15
+ uses: astral-sh/setup-uv@v5
16
+ - name: Set up Python
17
+ run: uv python install
18
+ - name: Install dependencies
19
+ run: uv sync --all-extras --dev
20
+ - name: Run tests with 95% coverage requirement
21
+ run: uv run pytest --cov=retroflow --cov-fail-under=95
22
+
23
+ build-n-publish:
24
+ name: Build and publish to PyPI
25
+ needs: test
26
+ runs-on: ubuntu-latest
27
+ # This environment name MUST match what you set on PyPI later
28
+ environment: pypi
29
+ permissions:
30
+ # This permission is required for Trusted Publishing (OIDC)
31
+ id-token: write
32
+ contents: read
33
+
34
+ steps:
35
+ - uses: actions/checkout@v4
36
+
37
+ - name: Install uv
38
+ uses: astral-sh/setup-uv@v5
39
+
40
+ - name: Set up Python
41
+ run: uv python install
42
+
43
+ - name: Build package
44
+ run: uv build
45
+
46
+ - name: Publish to PyPI
47
+ # uv publish automatically uses the OIDC token if available
48
+ run: uv publish
@@ -0,0 +1,52 @@
1
+ name: Test
2
+
3
+ on:
4
+ push:
5
+ branches: [ main ]
6
+ pull_request:
7
+ branches: [ main ]
8
+
9
+ jobs:
10
+ # New Job: Check for style and common bugs
11
+ lint:
12
+ name: Lint and Format
13
+ runs-on: ubuntu-latest
14
+ steps:
15
+ - uses: actions/checkout@v4
16
+ - name: Install uv
17
+ uses: astral-sh/setup-uv@v5
18
+ - name: Run Ruff Check
19
+ run: uvx ruff check .
20
+ - name: Run Ruff Format
21
+ run: uvx ruff format --check .
22
+
23
+ # Original Job: Run the test suite
24
+ test:
25
+ name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
26
+ needs: lint # Only run tests if linting passes
27
+ runs-on: ${{ matrix.os }}
28
+ strategy:
29
+ fail-fast: false
30
+ matrix:
31
+ os: [ubuntu-latest, windows-latest, macos-latest]
32
+ python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
33
+
34
+ steps:
35
+ - uses: actions/checkout@v4
36
+ - name: Install uv
37
+ uses: astral-sh/setup-uv@v5
38
+ with:
39
+ enable-cache: true
40
+ - name: Set up Python ${{ matrix.python-version }}
41
+ run: uv python install ${{ matrix.python-version }}
42
+ - name: Install dependencies
43
+ run: uv sync --all-extras --dev
44
+ - name: Run tests with coverage
45
+ run: uv run pytest --cov=retroflow --cov-report=xml --cov-report=term
46
+ - name: Upload coverage to Codecov
47
+ if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
48
+ uses: codecov/codecov-action@v4
49
+ with:
50
+ files: ./coverage.xml
51
+ fail_ci_if_error: true
52
+ token: ${{ secrets.CODECOV_TOKEN }}
@@ -0,0 +1,209 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[codz]
4
+ *$py.class
5
+
6
+ *.png
7
+
8
+ # C extensions
9
+ *.so
10
+
11
+ # Distribution / packaging
12
+ .Python
13
+ build/
14
+ develop-eggs/
15
+ dist/
16
+ downloads/
17
+ eggs/
18
+ .eggs/
19
+ lib/
20
+ lib64/
21
+ parts/
22
+ sdist/
23
+ var/
24
+ wheels/
25
+ share/python-wheels/
26
+ *.egg-info/
27
+ .installed.cfg
28
+ *.egg
29
+ MANIFEST
30
+
31
+ # PyInstaller
32
+ # Usually these files are written by a python script from a template
33
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
34
+ *.manifest
35
+ *.spec
36
+
37
+ # Installer logs
38
+ pip-log.txt
39
+ pip-delete-this-directory.txt
40
+
41
+ # Unit test / coverage reports
42
+ htmlcov/
43
+ .tox/
44
+ .nox/
45
+ .coverage
46
+ .coverage.*
47
+ .cache
48
+ nosetests.xml
49
+ coverage.xml
50
+ *.cover
51
+ *.py.cover
52
+ .hypothesis/
53
+ .pytest_cache/
54
+ cover/
55
+
56
+ # Translations
57
+ *.mo
58
+ *.pot
59
+
60
+ # Django stuff:
61
+ *.log
62
+ local_settings.py
63
+ db.sqlite3
64
+ db.sqlite3-journal
65
+
66
+ # Flask stuff:
67
+ instance/
68
+ .webassets-cache
69
+
70
+ # Scrapy stuff:
71
+ .scrapy
72
+
73
+ # Sphinx documentation
74
+ docs/_build/
75
+
76
+ # PyBuilder
77
+ .pybuilder/
78
+ target/
79
+
80
+ # Jupyter Notebook
81
+ .ipynb_checkpoints
82
+
83
+ # IPython
84
+ profile_default/
85
+ ipython_config.py
86
+
87
+ # pyenv
88
+ # For a library or package, you might want to ignore these files since the code is
89
+ # intended to run in multiple environments; otherwise, check them in:
90
+ # .python-version
91
+
92
+ # pipenv
93
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
94
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
95
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
96
+ # install all needed dependencies.
97
+ #Pipfile.lock
98
+
99
+ # UV
100
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
101
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
102
+ # commonly ignored for libraries.
103
+ #uv.lock
104
+
105
+ # poetry
106
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
107
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
108
+ # commonly ignored for libraries.
109
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
110
+ #poetry.lock
111
+ #poetry.toml
112
+
113
+ # pdm
114
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
115
+ # pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
116
+ # https://pdm-project.org/en/latest/usage/project/#working-with-version-control
117
+ #pdm.lock
118
+ #pdm.toml
119
+ .pdm-python
120
+ .pdm-build/
121
+
122
+ # pixi
123
+ # Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
124
+ #pixi.lock
125
+ # Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
126
+ # in the .venv directory. It is recommended not to include this directory in version control.
127
+ .pixi
128
+
129
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
130
+ __pypackages__/
131
+
132
+ # Celery stuff
133
+ celerybeat-schedule
134
+ celerybeat.pid
135
+
136
+ # SageMath parsed files
137
+ *.sage.py
138
+
139
+ # Environments
140
+ .env
141
+ .envrc
142
+ .venv
143
+ env/
144
+ venv/
145
+ ENV/
146
+ env.bak/
147
+ venv.bak/
148
+
149
+ # Spyder project settings
150
+ .spyderproject
151
+ .spyproject
152
+
153
+ # Rope project settings
154
+ .ropeproject
155
+
156
+ # mkdocs documentation
157
+ /site
158
+
159
+ # mypy
160
+ .mypy_cache/
161
+ .dmypy.json
162
+ dmypy.json
163
+
164
+ # Pyre type checker
165
+ .pyre/
166
+
167
+ # pytype static type analyzer
168
+ .pytype/
169
+
170
+ # Cython debug symbols
171
+ cython_debug/
172
+
173
+ # PyCharm
174
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
175
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
176
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
177
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
178
+ #.idea/
179
+
180
+ # Abstra
181
+ # Abstra is an AI-powered process automation framework.
182
+ # Ignore directories containing user credentials, local state, and settings.
183
+ # Learn more at https://abstra.io/docs
184
+ .abstra/
185
+
186
+ # Visual Studio Code
187
+ # Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
188
+ # that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
189
+ # and can be added to the global gitignore or merged into this file. However, if you prefer,
190
+ # you could uncomment the following to ignore the entire vscode folder
191
+ # .vscode/
192
+
193
+ # Ruff stuff:
194
+ .ruff_cache/
195
+
196
+ # PyPI configuration file
197
+ .pypirc
198
+
199
+ # Cursor
200
+ # Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
201
+ # exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
202
+ # refer to https://docs.cursor.com/context/ignore-files
203
+ .cursorignore
204
+ .cursorindexingignore
205
+
206
+ # Marimo
207
+ marimo/_static/
208
+ marimo/_lsp/
209
+ __marimo__/
@@ -0,0 +1 @@
1
+ 3.12
@@ -0,0 +1,128 @@
1
+ # CLAUDE.md - Development Guidance and Context
2
+
3
+ ## Project Overview
4
+
5
+ This is a project to help engineers, researchers, project managers, and others create beautiful, retro ASCII flow diagrams. ASCII diagrams are pretty, and harken back to the mid-20th century technical documentation. They also have real advantages:
6
+
7
+ 1) ASCII diagrams optimize for thinking speed, not presentation quality. It encourages iteration and deletion instead of premature refinement
8
+ 2) ASCII diagrams can live inline with: PRs, Markdown files, Slack threads, etc
9
+ 3) Minimalist diagrams reduce visual noise (although they do still look retro and pretty)
10
+ 4) They're tool agnostic and can be rendered anywhere
11
+ 5) They work wonderfully in the age of agentic AI, which can easily read and parse these small diagram representations
12
+
13
+ ## Who you are
14
+
15
+ You are a kind, immensely-intelligent engineer that has a love for ASCII-minimalism and the intersection of engineering and art and psychology. You enjoy adding a reasonable amount (not too much, but here and there it's okay) of ASCII art here and there in the project artifacts. You are also have a powerful mastery of the python language, and a vast knowledge of all of the currently popular tools and frameworks that are used.
16
+
17
+ ## Some Golden Rules to Follow
18
+
19
+ When unsure about implementation details, ALWAYS ask the developer.
20
+
21
+ As much as possible, just pure python should be used in implementation. We want to the implementation light, fast, and not dependent on a bunch of packages.
22
+
23
+ At the same time, we optimize for maintainability over cleverness. When in doubt, choose the boring, well-tested solution that future developers can easily understand and modify.
24
+
25
+ Also use the python `uv` tool and its associated virtual environment for running tests and project code.
26
+
27
+ Every source code addition must be accompanied by:
28
+ * Either updating or adding new unit and integration tests in the `tests/` folder. Ensure that test coverage is > 95% at any time.
29
+ * Linting and formatting with the `ruff` package
30
+ * Updating both the `README.md` and `CLAUDE.md` file. If the source code update is a tiny fix, there is no need to update these documents. Generally, update the documents if a user-facing change has been made.
31
+
32
+ This project follows semantic versioning, with the current version being located in the `pyproject.toml` file and the `git` tag. Always ask the developer if your suggested version update is correct.
33
+
34
+ Never modify anything outside of this project folder without asking the developer for explicit permission.
35
+
36
+ ## PyPI Deployment Process
37
+
38
+ This project uses **GitHub Actions + PyPI Trusted Publishing** for automated releases. No API tokens are needed.
39
+
40
+ ### How It Works
41
+
42
+ 1. **CI/CD Workflows** (in `.github/workflows/`):
43
+ - `test.yml`: Runs linting and tests on every push/PR to main
44
+ - `publish.yml`: Builds and publishes to PyPI when a version tag is pushed
45
+
46
+ 2. **Coverage Requirements**:
47
+ - 95% test coverage is enforced before publishing
48
+ - Codecov integration tracks coverage over time
49
+ - Configuration in `codecov.yml`
50
+
51
+ ### To Release a New Version
52
+
53
+ Again, always confirm with the developer any updates or changes you make related to versioning.
54
+
55
+ ```bash
56
+ # 1. Update version in pyproject.toml
57
+ # 2. Commit the change
58
+ git add pyproject.toml
59
+ git commit -m "Bump version to X.Y.Z"
60
+
61
+ # 3. Create and push a version tag
62
+ git tag vX.Y.Z
63
+ git push origin main
64
+ git push origin vX.Y.Z
65
+ ```
66
+
67
+ The `publish.yml` workflow will automatically:
68
+ 1. Run tests with 95% coverage requirement
69
+ 2. Build the package with `uv build`
70
+ 3. Publish to PyPI via OIDC (Trusted Publishing)
71
+
72
+ ### Initial Setup (Already Done)
73
+
74
+ - PyPI pending publisher configured for `ronikobrosly/retroflow`
75
+ - GitHub environment `pypi` created with OIDC permissions
76
+ - Codecov integration activated at https://app.codecov.io/gh
77
+
78
+
79
+ ## Features
80
+
81
+ - **Simple syntax**: Define flowcharts using intuitive `A -> B` arrow notation
82
+ - **ASCII output**: Generate text-based flowcharts for terminals and documentation
83
+ - **PNG export**: Create high-resolution images for presentations and reports
84
+ - **Intelligent layout**: Automatic node positioning with the Sugiyama algorithm
85
+ - **Cycle detection**: Handles cyclic graphs gracefully
86
+ - **Customizable**: Adjust box sizes, spacing, and layout algorithms
87
+
88
+
89
+ ## Project Structure
90
+
91
+ ```
92
+ retroflow/
93
+ ├── .github/workflows/
94
+ │ ├── publish.yml # PyPI release workflow (triggers on version tags)
95
+ │ └── test.yml # CI workflow (lint + test matrix)
96
+ ├── src/retroflow/
97
+ │ ├── __init__.py # Public API exports
98
+ │ ├── flowchart.py # FlowchartGenerator class (main entry point)
99
+ │ ├── parser.py # Text input parser (A -> B syntax)
100
+ │ ├── graph.py # Graph data structure and algorithms
101
+ │ ├── layout.py # Layout algorithms (Sugiyama, simple)
102
+ │ ├── renderer.py # ASCII canvas and rendering
103
+ │ ├── png_renderer.py # PNG image generation
104
+ │ └── py.typed # PEP 561 type marker
105
+ ├── tests/
106
+ │ ├── conftest.py # Shared pytest fixtures
107
+ │ ├── test_parser.py # Parser tests
108
+ │ ├── test_graph.py # Graph tests
109
+ │ ├── test_layout.py # Layout algorithm tests
110
+ │ ├── test_renderer.py # ASCII renderer tests
111
+ │ ├── test_png_renderer.py # PNG renderer tests
112
+ │ └── test_integration.py # End-to-end tests
113
+ ├── codecov.yml # Coverage threshold config (95%)
114
+ ├── pyproject.toml # Package metadata and dependencies
115
+ ├── README.md # User documentation
116
+ └── CLAUDE.md # Developer/agent guidance (this current file)
117
+ ```
118
+
119
+ ### Key Source Files
120
+
121
+ | File | Purpose |
122
+ |------|---------|
123
+ | `flowchart.py` | Main `FlowchartGenerator` class - orchestrates parsing, layout, and rendering |
124
+ | `parser.py` | Parses `A -> B` text syntax into connection tuples |
125
+ | `graph.py` | Directed graph with cycle detection, topological sort, feedback edge finding |
126
+ | `layout.py` | Sugiyama layered layout algorithm for node positioning |
127
+ | `renderer.py` | ASCII canvas with box drawing, lines, and arrows |
128
+ | `png_renderer.py` | PIL-based PNG generation with shadows and arrowheads |
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Roni Kobrosly
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.