Modernise pyflowchart: Python 3.7–3.14 support, bug fixes, packaging, and CI (v0.5.0b1)

.github/workflows/TestPyPi-publish.yml

@@ -1,41 +1,35 @@
-# This workflow will build & upload a Python Package to TestPyPi using Twine 
-# whenever a PR is merged or a commit is made to the master branch.
+# Build and upload to TestPyPI on every push to master.
+name: Build and Publish Package to TestPyPI
 
-name: Build and Publish Package to TestPyPi
-
-# This workflow will run when a PR is merged or when a commit is made directly to the master branch.
-# ref: https://github.community/t/trigger-workflow-only-on-pull-request-merge/17359/3
 on:
   push:
-    branches: [ master ]
+    branches: [master]
 
 jobs:
   build-and-publish:
-    name: Build and publish distributions to TestPyPI
+    name: Build and publish to TestPyPI
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write   # required for trusted publishing
+
     steps:
-    - uses: actions/checkout@master
-    - name: Set up Python 3.7
-      uses: actions/setup-python@v1
-      with:
-        python-version: 3.7
-    - name: Install pypa/build
-      run: >-
-        python -m
-        pip install
-        build
-        --user
-    - name: 🔨Build a binary wheel and a source tarball
-      run: >-
-        python -m
-        build
-        --sdist
-        --wheel
-        --outdir dist/
-        .
-    - name: Publish distribution 📦 to Test PyPI
-      uses: pypa/gh-action-pypi-publish@master
-      with:
-        password: ${{ secrets.TEST_PYPI_API_TOKEN }}
-        repository_url: https://test.pypi.org/legacy/
-        skip_existing: true
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build
+        run: python -m pip install --upgrade build
+
+      - name: Build sdist and wheel
+        run: python -m build --sdist --wheel --outdir dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true

.github/workflows/codeql-analysis.yml

@@ -1,67 +1,36 @@
-# For most projects, this workflow file will not need changing; you simply need
-# to commit it to your repository.
-#
-# You may wish to alter this file to override the set of languages analyzed,
-# or to provide custom queries or build logic.
-#
-# ******** NOTE ********
-# We have attempted to detect the languages in your repository. Please check
-# the `language` matrix defined below to confirm you have the correct set of
-# supported CodeQL languages.
-#
 name: "CodeQL"
 
 on:
   push:
-#     branches: [ master ]
   pull_request:
-    # The branches below must be a subset of the branches above
-#     branches: [ master ]
   schedule:
     - cron: '42 10 * * 6'
 
 jobs:
   analyze:
     name: Analyze
     runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
 
     strategy:
       fail-fast: false
       matrix:
-        language: [ 'python' ]
-        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python' ]
-        # Learn more:
-        # https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#changing-the-languages-that-are-analyzed
+        language: ['python']
 
     steps:
-    - name: Checkout repository
-      uses: actions/checkout@v2
+      - name: Checkout repository
+        uses: actions/checkout@v4
 
-    # Initializes the CodeQL tools for scanning.
-    - name: Initialize CodeQL
-      uses: github/codeql-action/init@v1
-      with:
-        languages: ${{ matrix.language }}
-        # If you wish to specify custom queries, you can do so here or in a config file.
-        # By default, queries listed here will override any specified in a config file.
-        # Prefix the list here with "+" to use these queries and those in the config file.
-        # queries: ./path/to/local/query, your-org/your-repo/queries@main
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
 
-    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
-    # If this step fails, then you should remove it and run the build manually (see below)
-    - name: Autobuild
-      uses: github/codeql-action/autobuild@v1
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
 
-    # ℹ️ Command-line programs to run using the OS shell.
-    # 📚 https://git.io/JvXDl
-
-    # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
-    #    and modify them (or add more) to build your code if your project
-    #    uses a compiled language
-
-    #- run: |
-    #   make bootstrap
-    #   make release
-
-    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v1
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3

.github/workflows/release-publish.yml

@@ -1,38 +1,29 @@
-# This workflow will upload a Python Package using Twine when a release is published
-# For more information see: https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
-
-name: Upload Release to PyPi
+# Build and upload to PyPI when a GitHub Release is published.
+name: Upload Release to PyPI
 
 on:
   release:
     types: [published]
 
 jobs:
   deploy:
-
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@master
-    - name: Set up Python 3.7
-      uses: actions/setup-python@v1
-      with:
-        python-version: 3.7
-    - name: Install pypa/build
-      run: >-
-        python -m
-        pip install
-        build
-        --user
-    - name: Build a binary wheel and a source tarball
-      run: >-
-        python -m
-        build
-        --sdist
-        --wheel
-        --outdir dist/
-        .
-    - name: Publish distribution 📦 to PyPI
-      uses: pypa/gh-action-pypi-publish@master
-      with:
-        password: ${{ secrets.PYPI_API_TOKEN }}
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build
+        run: python -m pip install --upgrade build
+
+      - name: Build sdist and wheel
+        run: python -m build --sdist --wheel --outdir dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/tests.yml

@@ -0,0 +1,55 @@
+# Run the test suite across the full supported Python version range on every
+# push and pull-request so regressions are caught early.
+#
+# Python 3.7 requires ubuntu-22.04; the hosted tool cache for ubuntu-24.04
+# (ubuntu-latest) does not include Python 3.7.
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    name: "Python ${{ matrix.python-version }}"
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: "3.7"
+            os: ubuntu-22.04
+          - python-version: "3.8"
+            os: ubuntu-latest
+          - python-version: "3.9"
+            os: ubuntu-latest
+          - python-version: "3.10"
+            os: ubuntu-latest
+          - python-version: "3.11"
+            os: ubuntu-latest
+          - python-version: "3.12"
+            os: ubuntu-latest
+          - python-version: "3.13"
+            os: ubuntu-latest
+          - python-version: "3.14"
+            os: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true   # ensures pre-release versions (e.g. RC builds) are accepted
+
+      - name: Install package and test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest pyflowchart/test.py -v

.gitignore

@@ -1,8 +1,6 @@
 dev_test
 
-# poetry & pyproject.toml based env is not ready & for internal experiment only.
-# keeps setup.py for a while.
-pyproject.toml
+# poetry lock file is not committed for a library; setup.py / pyproject.toml are the source of truth.
 poetry.lock
 
 .idea

README.md

@@ -23,7 +23,7 @@ Want to **flowchart your Python code in `example.py`?** Run this:
 $ python -m pyflowchart example.py
 ```
 
-> ⚠️ PyFlowchart works with **Python 3.7+**. To check your Python version, run [`python --version`](https://docs.python.org/3/using/cmdline.html#cmdoption-version).
+> ⚠️ PyFlowchart requires **Python 3.7+** and is CI-tested on Python **3.7 through 3.14**. To check your Python version, run [`python --version`](https://docs.python.org/3/using/cmdline.html#cmdoption-version).
 >
 > If you have both Python 2 and Python 3 installed, you may need to use `python3` instead of `python`. This is becoming less common as [Python 2 is sunsetting](https://www.python.org/doc/sunset-python-2/).
 

pyflowchart/__init__.py

@@ -2,8 +2,8 @@
 PyFlowchart
 --------
 
-PyFlowchart is a package to write flowchart in Python
-or translate Python source codes into flowchart.
+PyFlowchart is a package to write flowcharts in Python
+or translate Python source codes into flowcharts.
 
 Copyright 2020 CDFMLR. All rights reserved.
 Use of this source code is governed by a MIT
@@ -14,3 +14,37 @@
 from .ast_node import *
 from .flowchart import *
 from .output_html import *
+
+__all__ = [
+    # Core node classes — for building flowcharts programmatically
+    "Node",
+    "Connection",
+    "NodesGroup",
+    "StartNode",
+    "EndNode",
+    "OperationNode",
+    "InputOutputNode",
+    "SubroutineNode",
+    "ConditionNode",
+    "TransparentNode",
+    "CondYN",
+    # AST-backed node classes
+    "AstNode",
+    "FunctionDef",
+    "Loop",
+    "If",
+    "CommonOperation",
+    "CallSubroutine",
+    "BreakContinueSubroutine",
+    "YieldOutput",
+    "Return",
+    "Match",
+    "MatchCase",
+    # Parsing
+    "ParseProcessGraph",
+    "parse",
+    # Main flowchart class
+    "Flowchart",
+    # HTML output helper
+    "output_html",
+]

pyflowchart/__main__.py

@@ -40,7 +40,7 @@ def detect_decode(file_content: bytes) -> str:
     encoding = detect_result.get("encoding")
     confidence = detect_result.get("confidence")
 
-    if confidence < 0.9:
+    if not confidence or confidence < 0.9:
         encoding = "UTF-8"
 
     # decode file content by detected encoding
@@ -93,7 +93,11 @@ def main(code_file, field, inner, output_file, simplify, conds_align):
     output(flowchart.flowchart(), output_file, field)
 
 
-if __name__ == '__main__':
+def cli():
+    """Entry point for the ``pyflowchart`` command-line tool.
+
+    Registered as the ``pyflowchart`` console script in pyproject.toml / setup.py.
+    """
     parser = argparse.ArgumentParser(description='Python code to flowchart.')
 
     # code_file: open as binary, detect encoding and decode in main later
@@ -113,3 +117,7 @@ def main(code_file, field, inner, output_file, simplify, conds_align):
         args.inner = True
 
     main(args.code_file, args.field, args.inner, args.output, args.no_simplify, args.conds_align)
+
+
+if __name__ == '__main__':
+    cli()