Python driver: antlr4-python3-runtime==4.11.1 dependency is incompatible with Python >= 3.13

[uesleilima]

Describe the bug

The driver's setup.py pins antlr4-python3-runtime==4.11.1. This version is incompatible with Python 3.13+, causing runtime errors when the ANTLR4 parser is invoked. The antlr4-python3-runtime 4.13.x series is backward-compatible (same ATN serialized format, version 4) and works correctly on Python 3.13.

How are you accessing AGE?

Python driver (psycopg3)

Steps to Reproduce

# On Python 3.13+
pip install apache-age-python
# or: pip install git+https://github.com/apache/age.git#subdirectory=drivers/python
python -c "import age; print('ok')"

With antlr4-python3-runtime==4.11.1 on Python 3.13, importing or using the driver's parser raises errors related to changes in Python's internal APIs that ANTLR 4.11.1 relies on.

Expected behavior

The driver should install and work on currently supported Python versions (3.10 through 3.13+).

Actual behavior

Runtime errors from antlr4-python3-runtime==4.11.1 on Python 3.13+ due to deprecated/removed CPython internals that the 4.11.x runtime depends on.

Current workaround

Override the dependency pin at the package manager level:

# pyproject.toml (using uv)
[tool.uv]
override-dependencies = ["antlr4-python3-runtime>=4.13.0"]

Suggested fix

Relax the antlr4-python3-runtime version constraint in setup.py from ==4.11.1 to >=4.11.1,<5.0 (or at minimum >=4.13.0). The ANTLR ATN serialized format has not changed between 4.11 and 4.13, so the generated lexer/parser files are compatible. This has been validated in production with antlr4-python3-runtime==4.13.2 on Python 3.13.

Alternatively, regenerate the ANTLR4 lexer/parser with the 4.13.x toolchain and pin to >=4.13.0.

Related issues

• Update Dependencies for Python Driver #694 — Updated deps to 4.11.1 but did not address Python 3.13 compatibility.
• Python driver unable to build from source #388 — Build failures with antlr4 4.10+, resolved for 4.11.1 but not for newer Python.

Environment

• Apache AGE: 1.5.0+ / master
• Python driver: master branch (psycopg3 version)
• antlr4-python3-runtime: 4.11.1 (broken), 4.13.2 (works)
• Python: 3.13.x