How cext-dan/pyrx works
1. What this repo is
PyRx is a native C++ extension for CAD hosts, not a .NET layer. It embeds CPython 3.12 into loadable ARX/BRX/GRX/ZRX/IRX modules so Python code can run inside AutoCAD and compatible clones such as BricsCAD, GstarCAD, and ZwCAD.
2. Top-level architecture
The repository is split into three main runtime layers:
- Native host modules in PyRxCore and PyRxLoader
- Python package/API layer in pyrx
- Samples, tests, and tooling in PySamples, tests, and pyrx/doc_utils
3. Native core binding layer
PyRxCore is the main binding implementation. It contains many C++ wrappers grouped by CAD API area: Db, Ge, Ed, Ap, Ax, Gi, Gs, Pl, Sm, plus BricsCAD/Civil/BIM-specific namespaces like PyBrx, PyBrxCv, PyBrxBim, and PyBimCore. These wrappers expose the host application's object model, geometry, editor, graphics, sheet set, and UI services to Python.
4. Host-module entry points
The native modules are built around ARX-style entry points such as acrxEntryPoint.cpp and dllmain.cpp. The loader side in PyRxLoader is the thin bootstrap module that gets loaded by the CAD host and then initializes the embedded Python environment and PyRx runtime.
5. Versioned host compatibility
The repo carries multiple project files and binaries for different CAD host versions and vendors, such as PyRx24.2, PyRx25.0, PyRx26.0, PyRxV*, PyRxG*, and PyRxZ*. This means compatibility is handled at the binary/module boundary, not by a single universal plugin.
6. Python-facing API layer
The pyrx package is the public Python surface. It provides importable modules such as pyrx.db, pyrx.ge, pyrx.ed, pyrx.ap, pyrx.repl, and utility modules for commands, configuration, console integration, reloading, and typing support. The package also ships the generated host-specific extension binaries and startup helpers.
7. Command and scripting flow
Once the CAD host loads the loader module, the runtime exposes commands like PYLOAD, PYRELOAD, PYDEBUG, PYCMDPROMPT, and PYPIP. The flow is: CAD host → native loader → embedded Python runtime → Python command/utility modules → CAD API wrappers. AutoLISP hooks are also provided for script-driven loading and inspection.
8. UI and interactive tooling
GUI support is built around wxPython, with palette/dialog wrappers in the native layer and sample apps under PySamples/wxPython. This is a separate interaction boundary from the CAD database/editor APIs: UI code talks to the Python runtime, which then invokes CAD services through the bindings.
9. Documentation and stub generation pipeline
pyrx/doc_utils, gen_pyi.py, and PyRxStubs/docgen.py indicate a documentation/stub-generation subsystem. It parses docstrings and metadata to produce .pyi stub files shipped in pyrx/, enabling autocomplete and type checking for the exposed CAD APIs.
10. Samples as architectural coverage
PySamples is organized by API domain and scenario rather than by application. It includes command examples, database/entity manipulation, editor interactions, reactors, geometry utilities, Civil/BIM examples, wxPython apps, and small utility scripts. These samples are the primary reference for how the runtime pieces fit together.
11. Test strategy
tests/ is large and host-aware. It includes unit-style Python tests for the pure-Python helpers, plus CAD-integration tests that exercise the wrapped APIs against real DWG/DST/IFC/sample assets under tests/media. The test suite is structured by API area to mirror the module boundaries in pyrx and PyRxCore.
12. Packaging and release boundary
Packaging is handled by standard Python build files (pyproject.toml, setup.py, MANIFEST.in) plus release workflows in GitHub Actions. The repo publishes a pip installable package (cad-pyrx) that includes the Python package, stub files, and the correct host-specific binaries.
13. External dependencies that matter architecturally
The two major external runtime dependencies are the CAD host SDKs/APIs and wxPython. The repo also embeds third-party geometry/utilities in C++ headers such as delaunator.h, concaveman.h, and nanoflann.hpp, which support internal geometric operations exposed through the Python bindings.
14. How to think about the diagram
A useful architecture diagram should show:
- CAD application host at the top
- Native loader modules as the entry point
- Embedded Python runtime inside the host process
- Native binding layer (PyRxCore) bridging Python to CAD SDK APIs
- Public Python package (pyrx) and command/repl utilities on the Python side
- Sample scripts and tests as consumers of the public API, not as separate runtime services
Main entry points: PyRxCore PyRxCore · pyrx pyrx · PyRxLoader Loader · PySamples Samples
Components 20
Native runtime
Loadable CAD host modules and C++ binding layer
- CAD host · AutoCAD and compatible CAD applications that load the modules
- Loader · Thin host-loaded module that initializes embedded Python and the PyRx runtime
PyRxLoader - PyRxCore · Main C++ binding layer exposing CAD SDK APIs to Python
PyRxCore - Entry points · ARX-style entry points and DLL startup for host integration
PyRxCore/acrxEntryPoint.cpp - DB wrappers · Database, object, entity, table, and transaction wrappers
PyRxCore/PyDbDatabase.cpp - Editor wrappers · Command, prompt, selection, reactor, and user interaction wrappers
PyRxCore/PyEdInput.cpp - Geometry wrappers · 2D/3D geometry, curves, surfaces, and spatial helpers
PyRxCore/PyGeCurve3d.cpp - UI wrappers · Palette, plot, graphics, and transient drawing integration
PyRxCore/PyUiPalette.cpp - BricsCAD APIs · BricsCAD-specific core, BIM, and Civil wrappers
PyRxCore/PyBrxCore.cpp
Python API
Public package surface and runtime helpers
- pyrx · Importable Python package exposing the runtime API and helpers
pyrx - Commands · Command registration and command-side utilities such as load, reload, debug, and pip entry points
pyrx/commands.py - REPL · Interactive console and REPL helpers for in-host Python execution
pyrx/repl - Runtime utils · Reload, decorators, test runner, and wx integration helpers
pyrx/utils - Host init · Startup and host-specific initialization used when the package is imported inside the CAD process
pyrx/_host_init.py
Coverage and tooling
Samples, tests, stub generation, and support tooling
- Stub gen · Docstring parsing and .pyi stub generation for the exposed APIs
pyrx/doc_utils - Samples · Domain-organized scripts demonstrating commands, APIs, reactors, geometry, wxPython, and vendor extensions
PySamples - Tests · Host-aware tests plus pure-Python helper tests organized by API area
tests - Stubs · Generated and shipped .pyi surfaces for the public Python modules
pyrx/doc_utils/stubs
Packaging
Build, versioning, and release boundary
- Packaging · Python packaging and release configuration for shipping host-specific binaries and the package
pyproject.toml - Versioning · Version templates and generated package metadata for releases
Version
Connections 21
- CAD host → Loader: loads · The CAD application loads the thin bootstrap module
- Loader → PyRxCore: initializes · Loader brings up the native runtime and bridges to the core binding layer
- PyRxCore → Entry points: enters · Core module is anchored by native entry points and DLL startup
- PyRxCore → DB wrappers: exposes · Database and object model bindings
- PyRxCore → Editor wrappers: exposes · Editor, command, and interaction bindings
- PyRxCore → Geometry wrappers: exposes · Geometry and spatial bindings
- PyRxCore → UI wrappers: exposes · Graphics and palette/UI bindings
- PyRxCore → BricsCAD APIs: exposes · Vendor-specific BricsCAD/Civil/BIM bindings
- Loader → pyrx: boots · Loader prepares the embedded Python runtime used by the package
- pyrx → Commands: publishes · Command layer is part of the public Python surface
- pyrx → REPL: publishes · Interactive execution helpers are exposed to users
- pyrx → Runtime utils: publishes · Runtime utility helpers are available from the package
- pyrx → Host init: starts · Package includes host-specific initialization hooks
- pyrx → Stubs: ships · Typed stubs are distributed alongside the package
- Stub gen → Stubs: generates · Doc utilities generate and maintain the shipped stub files
- Tests → pyrx: validates · Tests exercise the public Python API and helper modules
- Samples → pyrx: consumes · Samples demonstrate the package as the user-facing entry point
- Samples → PyRxCore: exercises · Samples also drive CAD integration through the native bindings
- Packaging → pyrx: packages · Build configuration assembles the Python package and binaries
- Versioning → Packaging: feeds · Version templates support the release process
- Tests → PyRxCore: integration · Host-aware tests cover the native binding layer against real CAD assets