Issue #76 - Rename classic API to express

[wbkboyer]

Resolves #76

NOTE: Once this PR is merged, we'll have to update README.md to have the permalink for the K5-minus-edge.png instead of a relative URL, otherwise TestPyPI and PyPI landing page won't have that image.

Type of change

Please check only relevant options:

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected) - only if folks imported from the express subpackage explicitly rather than from the top level planarity package.
• This change requires a documentation update

Changes

Added

• N/A

Updated

• Renamed planarity/classic to planarity/express
• planarity/express/planarity.pyx - Updated cimport statement to reference new subpackage name, as well as all cross-references in docstrings
• planarity/express/planarity_(functions|networkx).py - updated all cross-references to use planarity.express subpackage
• planarity/__init__.py - updated import statements to use express subpackage and bumped __version__ for TestPyPI purposes
• MANIFEST.in - removed .c files from source distribution, and updated paths for express planarity.pyx module and cplanarity.pxd definition file
• pyproject.toml - updated classic to express
• README.md - updated relative path to express; this is broken on TestPyPI and likely will be for PyPI, so we'll need to subsequently update this to the permalink, something like:

  ![K_5-minus-edge](https://github.com/graph-algorithms/planarity/blob/master/examples/express/output/K5-minus-edge.png "Matplotlib render of $K_5$-minus-edge")
  

• setup.py - updated classic to express for subpackage, as well as naming of sourcefile list

Removed

• N/A

Testing

• Outline manual or automated tests performed and how it relates to the particular feature added or functionality changed
  • Ran git clean -x -d -e .vscode -f to get rid of any pycache or other detritus (including old cythonized .c files)
  • Ran rm -rf .venv and re-created (no cython nor setuptools) then ran pip install -v . to view compilation process (including planarity.express.planarity module)
  • Regenerated html and latexpdf contents and visually inspected (spot check) after installing sphinx-doc in virtual environment
  • Ran pytest -vvv after installing pytest, matplotlib, networkx
  • Ran examples/express/draw.py and examples/full/demo_specific_graph.py to show that all the modules were working as expected
  • Built source distribution using python -m build --sdist, then pushed to TestPyPI with python -m twine upload --repository testpypi dist/planarity-1.0.1.tar.gz, then installed on Debian 13 VM with Python 3.14.7 in fresh virtual environment without cython installed (although had to install setuptools) and install with python -m pip install --index-url https://test.pypi.org/simple/ --no-deps --no-build-isolation planarity. Ran IDLE and tested print(planarity.ascii(edgelist)) for the standard example.
• Upload logs or provide relevant snippets of terminal output to demo functionality

Logs from verification steps above (Macbook, Python 3.14.6)

wbkboyer@Wandas-MacBook-Pro planarity % rm -rf .venv
wbkboyer@Wandas-MacBook-Pro planarity % git clean -x -d -e .vscode -f
Removing .DS_Store
Removing .pytest_cache/
Removing build/
Removing doc/.DS_Store
Removing doc/build/
Removing doc/source/.DS_Store
Removing doc/source/_template/
Removing doc/source/api/
Removing examples/full/__pycache__/
Removing planarity.egg-info/
Removing planarity/__pycache__/
Removing planarity/express/__pycache__/
Removing planarity/express/planarity.c
Removing planarity/full/g6IterationUtils.c
Removing planarity/full/graph.c
Removing planarity/full/graphLib.c
Removing tests/__pycache__/
wbkboyer@Wandas-MacBook-Pro planarity % python3.14 -m venv .venv
wbkboyer@Wandas-MacBook-Pro planarity % source .venv/bin/activate
(.venv) wbkboyer@Wandas-MacBook-Pro planarity % pip install --upgrade pip
...
(.venv) wbkboyer@Wandas-MacBook-Pro planarity % pip install -v .
Using pip 26.2.1 from /Users/wbkboyer/git/planarity/.venv/lib/python3.14/site-packages/pip (python 3.14)
Processing ./.
  Running command installing build dependencies
  Using pip 26.2.1 from /Users/wbkboyer/git/planarity/.venv/lib/python3.14/site-packages/pip (python 3.14)
  Collecting setuptools
    Obtaining dependency information for setuptools from https://files.pythonhosted.org/packages/95/9c/c510029fc6ef33a6275cd2c5d3cecd6613dfd6aa401d57c54f1c18852ccf/setuptools-84.0.0-py3-none-any.whl.metadata
    Using cached setuptools-84.0.0-py3-none-any.whl.metadata (6.6 kB)
  Collecting cython
    Obtaining dependency information for cython from https://files.pythonhosted.org/packages/8a/7f/e409f76bb955ecdcb746b80350b945fbb808846d797346d647a37e1790ca/cython-3.3.0-cp314-cp314-macosx_11_0_arm64.whl.metadata
    Using cached cython-3.3.0-cp314-cp314-macosx_11_0_arm64.whl.metadata (28 kB)
  Using cached setuptools-84.0.0-py3-none-any.whl (818 kB)
  Using cached cython-3.3.0-cp314-cp314-macosx_11_0_arm64.whl (3.2 MB)
  Installing collected packages: setuptools, cython
    Creating /private/var/folders/t1/2kcfnw2902x6gjpfcq7l1r800000gn/T/pip-build-env-r6x8rmip/overlay/bin
    changing mode of /private/var/folders/t1/2kcfnw2902x6gjpfcq7l1r800000gn/T/pip-build-env-r6x8rmip/overlay/bin/cygdb to 755
    changing mode of /private/var/folders/t1/2kcfnw2902x6gjpfcq7l1r800000gn/T/pip-build-env-r6x8rmip/overlay/bin/cython to 755
    changing mode of /private/var/folders/t1/2kcfnw2902x6gjpfcq7l1r800000gn/T/pip-build-env-r6x8rmip/overlay/bin/cythonize to 755

  Successfully installed cython-3.3.0 setuptools-84.0.0
  Installing build dependencies ... done
...
(.venv) wbkboyer@Wandas-MacBook-Pro planarity % pip install matplotlib networkx pytest
...
(.venv) wbkboyer@Wandas-MacBook-Pro planarity % pytest -vvv
========================================= test session starts ==========================================
platform darwin -- Python 3.14.6, pytest-9.1.1, pluggy-1.6.0 -- /Users/wbkboyer/git/planarity/.venv/bin/python3.14
cachedir: .pytest_cache
rootdir: /Users/wbkboyer/git/planarity
configfile: pyproject.toml
collected 22 items                                                                                     

tests/test_planarity.py::TestPlanarity::test_is_planar_edgelist_input PASSED                     [  4%]
tests/test_planarity.py::TestPlanarity::test_is_planar_edgelist_input_function PASSED            [  9%]
tests/test_planarity.py::TestPlanarity::test_is_planar_adj_input PASSED                          [ 13%]
tests/test_planarity.py::TestPlanarity::test_is_planar_adj_input_function PASSED                 [ 18%]
tests/test_planarity.py::TestPlanarity::test_is_planar_adj_symmetric PASSED                      [ 22%]
tests/test_planarity.py::TestPlanarity::test_is_planar_adj_set PASSED                            [ 27%]
tests/test_planarity.py::TestPlanarity::test_is_planar_adj_list PASSED                           [ 31%]
tests/test_planarity.py::TestPlanarity::test_goldner_harary PASSED                               [ 36%]
tests/test_planarity.py::TestPlanarity::test_kuratowski_k5 PASSED                                [ 40%]
tests/test_planarity.py::TestPlanarity::test_kuratowski_k5_function PASSED                       [ 45%]
tests/test_planarity.py::TestPlanarity::test_no_kuratowski_k5m PASSED                            [ 50%]
tests/test_planarity.py::TestPlanarity::test_draw_text PASSED                                    [ 54%]
tests/test_planarity.py::TestPlanarity::test_write_adjlist PASSED                                [ 59%]
tests/test_planarity.py::TestPlanarity::test_write_adjmatrix PASSED                              [ 63%]
tests/test_planarity.py::TestPlanarity::test_write_g6 PASSED                                     [ 68%]
tests/test_planarity.py::TestPlanarity::test_write_function_g6 PASSED                            [ 72%]
tests/test_planarity_networkx.py::TestPlanarityNetworkX::test_is_planar PASSED                   [ 77%]
tests/test_planarity_networkx.py::TestPlanarityNetworkX::test_is_planar_unions PASSED            [ 81%]
tests/test_planarity_networkx.py::TestPlanarityNetworkX::test_goldner_harary PASSED              [ 86%]
tests/test_planarity_networkx.py::TestPlanarityNetworkX::test_kuratowski_k5 PASSED               [ 90%]
tests/test_planarity_networkx.py::TestPlanarityNetworkX::test_kuratowski_k5m PASSED              [ 95%]
tests/test_planarity_networkx.py::TestPlanarityNetworkX::test_networkx_graph PASSED              [100%]

========================================== 22 passed in 0.12s ==========================================

(.venv) wbkboyer@Wandas-MacBook-Pro planarity % cd doc
(.venv) wbkboyer@Wandas-MacBook-Pro doc % make clean && make html
Removing everything under 'build'...
Running Sphinx v9.1.0
loading translations [en]... done
making output directory... done
Running apidoc
loading intersphinx inventory 'python' from https://docs.python.org/3/objects.inv ...
loading intersphinx inventory 'networkx' from https://networkx.org/documentation/stable/objects.inv ...
loading intersphinx inventory 'matplotlib' from https://matplotlib.org/objects.inv ...
intersphinx inventory has moved: https://matplotlib.org/objects.inv -> https://matplotlib.org/stable/objects.inv
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 11 source files that are out of date
updating environment: [new config] 11 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... 
copying static files... 
Writing evaluated template result to /Users/wbkboyer/git/planarity/doc/build/html/_static/basic.css
Writing evaluated template result to /Users/wbkboyer/git/planarity/doc/build/html/_static/language_data.js
Writing evaluated template result to /Users/wbkboyer/git/planarity/doc/build/html/_static/documentation_options.js
Writing evaluated template result to /Users/wbkboyer/git/planarity/doc/build/html/_static/alabaster.css
copying static files: done
copying extra files... 
copying extra files: done
copying assets: done
writing output... [100%] index
generating indices... genindex py-modindex done
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in build/html.
(.venv) wbkboyer@Wandas-MacBook-Pro doc % cd ..       
(.venv) wbkboyer@Wandas-MacBook-Pro planarity % python examples/express/draw.py 
The graph cannot be drawn because it is non-planar.

{1: 'a', 2: 'b', 3: 'c', 4: 'd', 5: 'e'}
----1----
|  |    |
|  --5--|
|   || ||
--4--| ||
 ||  | ||
 |--2--||
 |    |||
 ---3----
         

Ignoring fixed y limits to fulfill fixed data aspect with adjustable data limits.
Ignoring fixed y limits to fulfill fixed data aspect with adjustable data limits.
Ignoring fixed y limits to fulfill fixed data aspect with adjustable data limits.
(.venv) wbkboyer@Wandas-MacBook-Pro planarity % python examples/full/demo_specific_graph.py -i ~/git/edge-addition-planarity-suite-fork/c/samples/nauty_example.g6 -o .

===================================================
This program imports the planarity package, which
is based on the Edge Addition Planarity Suite
version 5.0.0.0, which contains the libPlanarity
graph library version 4:0:0.
===================================================

Planarity embed result was OK.
	The graph is planar
Do you wish to render the drawing to screen (s) or file (f)? (Select any other input to dismiss.)
	f
Draw Planar embed result was OK.
	The graph is planar
Outerplanarity embed result was OK.
	The graph is outerplanar
K_{2, 3} Search embed result was OK.
	The graph is K_{2, 3}-free
K_{3, 3} Search embed result was OK.
	The graph is K_{3, 3}-free
K_4 Search embed result was OK.
	The graph is K_4-free
(.venv) wbkboyer@Wandas-MacBook-Pro planarity % python examples/full/demo_specific_graph.py -i ~/git/edge-addition-planarity-suite-fork/c/samples/Petersen.txt -o .

===================================================
This program imports the planarity package, which
is based on the Edge Addition Planarity Suite
version 5.0.0.0, which contains the libPlanarity
graph library version 4:0:0.
===================================================

Planarity embed result was NONEMBEDDABLE.
	The graph is not planar
Draw Planar embed result was NONEMBEDDABLE.
	The graph is not planar
Outerplanarity embed result was NONEMBEDDABLE.
	The graph is not outerplanar
K_{2, 3} Search embed result was NONEMBEDDABLE.
	The graph is not K_{2, 3}-free
K_{3, 3} Search embed result was NONEMBEDDABLE.
	The graph is not K_{3, 3}-free
K_4 Search embed result was NONEMBEDDABLE.
	The graph is not K_4-free

TestPyPI run

Note that due to an issue with TestPyPI not including setuptools, we must install setuptools before attempting to install:

(.testenv) wbkboyer@debian13:~/planarity-install-test$ python -m pip install --index-url https://test.pypi.org/simple/ --no-deps planarity
Looking in indexes: https://test.pypi.org/simple/
Collecting planarity
  Downloading planarity-1.0.1.tar.gz (739 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 739.4/739.4 kB 14.0 MB/s  0:00:00
  Installing build dependencies ... error
  error: subprocess-exited-with-error
  
  × installing build dependencies for planarity did not run successfully.
  │ exit code: 1
  ╰─> [3 lines of output]
      Looking in indexes: https://test.pypi.org/simple/
      ERROR: Could not find a version that satisfies the requirement setuptools (from versions: none)
      ERROR: No matching distribution found for setuptools
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
ERROR: Failed to build 'planarity' when installing build dependencies for planarity

(.testenv) wbkboyer@debian13:~/planarity-install-test$ pip install setuptools
Collecting setuptools
  Using cached setuptools-84.0.0-py3-none-any.whl.metadata (6.6 kB)
Using cached setuptools-84.0.0-py3-none-any.whl (818 kB)
Installing collected packages: setuptools
Successfully installed setuptools-84.0.0

Then, we can install planarity, without cython installed in the test environment (in this case a Debian VM with Python 3.14.7 in a virtual environment without cython)!

(.testenv) wbkboyer@debian13:~/planarity-install-test$ python -m pip install --index-url https://test.pypi.org/simple/ --no-deps --no-build-isolation planarity
Looking in indexes: https://test.pypi.org/simple/
Collecting planarity
  Using cached planarity-1.0.1.tar.gz (739 kB)
  Preparing metadata (pyproject.toml) ... done
Building wheels for collected packages: planarity
  Building wheel for planarity (pyproject.toml) ... done
  Created wheel for planarity: filename=planarity-1.0.1-cp314-cp314-linux_x86_64.whl size=2144567 sha256=ddf003e79096ca8fe99aa3447a9a7b0c27093da015400b89e83c80e94b9b757a
  Stored in directory: /home/wbkboyer/.cache/pip/wheels/78/2c/1b/ad81c8f7950eb4d1cb63df3379e29698cbf753fa9c7d155f9e
Successfully built planarity
Installing collected packages: planarity
Successfully installed planarity-1.0.1
(.testenv) wbkboyer@debian13:~/planarity-install-test$ pip freeze
planarity==1.0.1
setuptools==84.0.0

Opened IDLE to test only the planarity_functions.py ascii() endpoint (note that the example scripts nor tests are included in the source distribution):

(.testenv) wbkboyer@debian13:~/planarity-install-test$ python
Python 3.14.7 (main, Sep  8 2026, 16:03:20) [GCC 14.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import planarity
>>> edgelist = [('a', 'b'), ('a', 'c'), ('a', 'd'), ('a', 'e'),
...             ('b', 'c'),('b', 'd'),('b', 'e'),
...             ('c', 'd'), ('c', 'e'),
...             ('d', 'e')]
>>> edgelist.remove(('a', 'b'))
>>> print(planarity.ascii(edgelist))
----1----
|  |    |
|  --5--|
|   || ||
--4--| ||
 ||  | ||
 |--2--||
 |    |||
 ---3----

[john-boyer-phd]

You can up the version to 1.0.1 for testing with TestPyPI.

[john-boyer-phd]

This look great.
The fix to draw() is nice because we're back to passing the tests, and it'll be part of the next issue to deal with the fact that ax.margins(0) seems to truncate the left, right and bottom of the image by a pixel. Just not part of this issue though.