fix(python-driver): add null-guards in ANTLR parser and relax runtime version pin

[uesleilima]

Summary

Fix two related issues in the Python driver's ANTLR4 parsing pipeline:

1. ANTLR4 agtype parser crashes on vertices with complex properties (#2367)

The ResultVisitor in builder.py crashes with AttributeError: 'NoneType' object has no attribute 'stop' when deserializing certain vertex records whose properties contain large arrays, long text fields with special characters, or deeply nested structures.

Root cause: Several visitor methods access child nodes (.symbol, .getText(), .accept()) without null-checking first. When the ANTLR4 parser tree contains None nodes, these calls crash.

Fix: Add null-guards in visitAgValue, visitFloatLiteral, visitPair, visitObj, and handleAnnotatedValue. Also replaces shadowing of builtin dict with d in handleAnnotatedValue, and uses .get() for safer key access on parsed vertex/edge dicts.

2. antlr4-python3-runtime==4.11.1 is incompatible with Python >= 3.13 (#2368)

The exact version pin ==4.11.1 causes runtime errors on Python 3.13+ due to deprecated/removed CPython internals that ANTLR 4.11.x relies on.

Fix: Relax the constraint from ==4.11.1 to >=4.11.1,<5.0 in both pyproject.toml and requirements.txt. The ANTLR ATN serialized format is unchanged between 4.11 and 4.13, so the generated lexer/parser files are compatible. Validated with antlr4-python3-runtime==4.13.2 on Python 3.11-3.14.

Tests

Added 9 new test cases in test_agtypes.py:

• Vertices with large array properties (12 elements)
• Vertices with special characters in properties
• Deeply nested property structures (3 levels)
• Empty properties
• Null property values
• Edges with complex properties (arrays, booleans)
• Paths with multiple edges
• Empty/null input handling
• Arrays of mixed types including nested arrays

All 12 tests pass with antlr4-python3-runtime==4.13.2.

Closes

• Closes Python driver: ANTLR4 agtype parser crashes (AttributeError) on vertices with complex properties #2367
• Closes Python driver: antlr4-python3-runtime==4.11.1 dependency is incompatible with Python >= 3.13 #2368

[tcolo]

@uesleilima thanks alot of the patch - can you please address the issues in the review from claude code?
## Code Review: `fix(python-driver)`: add null-guards in ANTLR parser and relax runtime version pin

### Summary
This PR fixes two real bugs: a crash on `AttributeError` when deserializing complex vertex properties (#2367), and a version pin that blocks Python 3.13+ (#2368). The approach is sound and the test coverage is meaningful. A few things worth discussing before merging.

---

### 🔴 Issues to Address

**1. `visitFloatLiteral` — silent fallback may mask malformed input**

When `ctx.getChild(0)` returns `None`, the node is genuinely malformed. Silently returning a default value hides the problem — a test confirms no `AttributeError`, but an incorrect result is arguably worse. Consider raising `AGTypeError` consistently with how `visitPair` handles missing nodes:

```python
# Suggested
child = ctx.getChild(0)
if child is None:
    raise AGTypeError("Malformed float literal: missing child node")

2. handleAnnotatedValue — type validation failure mid-path construction

When a type check fails mid-path (e.g., vertex dict check passes, edge dict check raises AGTypeError), the partially constructed Path object may already have been mutated. It's discarded on exception so it's minor, but a comment explaining the intended behavior would help.

---

🟡 Suggestions

1. Add a comment explaining the version constraint

The change from ==4.11.1 to >=4.11.1,<5.0 is the right call — ANTLR4 maintains format compatibility within a major version. A brief inline comment in pyproject.toml will help the next person who wonders why it's not pinned more tightly:

# ANTLR4 runtime is format-compatible within major versions; tested on 4.13.2 with Python 3.11–3.14
"antlr4-python3-runtime>=4.11.1,<5.0"

2. Malformed input tests should assert the expected outcome, not just the absence of AttributeError

# Current pattern proves the old crash is gone, but doesn't pin the new contract
try:
    result = handler.parse(malformed_input)
except AttributeError:
    pytest.fail("Should not raise AttributeError")

# Better: assert what *should* happen
with pytest.raises(AGTypeError):
    handler.parse(malformed_input)

# OR if graceful None is expected:
result = handler.parse(malformed_input)
assert result is None

3. visitObj silently skips None values — visitPair hard-fails on them

This inconsistency could cause silent data loss (a property disappearing) instead of a parse error. Either align the behavior or add a comment explaining the intentional difference.

---

✅ What Looks Good

• The visitAgValue null-checks are clean and correctly handle the annotated-type path.
• Replacing dict["key"] with .get("key") in handleAnnotatedValue is the right call for externally-provided data.
• Fixing the shadowed dict builtin is a good catch — subtle but real.
• The nine new test cases cover solid breadth of the real-world inputs that triggered the original bug.
• Both pyproject.toml and requirements.txt are kept in sync on the version change — these often drift.

---

Verdict: Request Changes

The core fix is correct and needed. Two points before merging:

1. Clarify/fix visitFloatLiteral — silent 0.0 default vs. raising AGTypeError.
2. Tighten the malformed-input tests to assert the expected outcome, not just the absence of AttributeError.

The version pin relaxation is ready to merge as-is.

Paste this into **Files changed → Review changes → Leave a comment** on the PR and select **Request changes**.

[Copilot]

Pull request overview

This PR addresses crashes in the Python driver’s ANTLR4 agtype parsing by adding null-guards/error handling in the visitor and updates packaging to allow newer antlr4-python3-runtime versions (needed for Python 3.13+ compatibility).

Changes:

• Added null-guards and additional validation/error reporting in ResultVisitor / handleAnnotatedValue during agtype deserialization.
• Relaxed antlr4-python3-runtime dependency pin to >=4.11.1,<5.0 in packaging files.
• Expanded agtype parsing tests to cover complex vertices/edges/paths and malformed/truncated inputs.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
drivers/python/age/builder.py	Adds null-guards and changes annotated-type object construction logic.
drivers/python/test_agtypes.py	Adds multiple new parsing tests for complex and malformed agtype inputs.
drivers/python/requirements.txt	Relaxes ANTLR runtime constraint for broader Python compatibility.
drivers/python/pyproject.toml	Relaxes ANTLR runtime constraint and documents supported/tested ranges.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[uesleilima]

All review feedback has been addressed:

tcolo's review:

• ✅ visitFloatLiteral: now raises AGTypeError on malformed child node instead of silent fallback.
• ✅ handleAnnotatedValue: added comment explaining partial-construction behavior.
• ✅ visitObj/visitPair: added comment documenting that visitPair's validation makes the None-guard defensive-only.
• ✅ pyproject.toml: added inline comment explaining ANTLR4 version range rationale.
• ✅ Malformed/truncated input tests now assert AGTypeError or validate recovery shape (not just absence of AttributeError).

Copilot review:

• ✅ Vertex and edge branches now default properties to {} via d.get("properties") or {}, preventing __getitem__ crashes.
• ✅ Replaced weak assertNotIsInstance(result, type(NotImplemented)) with structural type checks.
• ✅ Fixed test_truncated_agtype docstring to match actual assertion behavior.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

test_vertex_special_characters_in_properties claims to cover “special characters”, but the test string only contains plain ASCII text (no escaped quotes/backslashes/newlines and no non-ASCII unicode). This makes the test less representative of the reported failure mode in #2367. Consider updating the description value to include actual special/escaped characters (and at least one non-ASCII code point) so the test meaningfully exercises the parser edge case.

Suggested change

	vertexExp = (
	'{"id": 1125899906842626, "label": "TestNode", '
	'"properties": {"name": "test", '
	'"description": "A long description with unicode chars"}}::vertex'
	)
	vertex = self.parse(vertexExp)
	self.assertEqual(vertex.id, 1125899906842626)
	self.assertEqual(vertex["name"], "test")
	self.assertIn("unicode", vertex["description"])
	expected_description = 'Quoted "text", path C:\\tmp\\file, line1\nline2, café 雪'
	vertexExp = (
	'{"id": 1125899906842626, "label": "TestNode", '
	'"properties": {"name": "test", '
	'"description": "Quoted \\"text\\", path C:\\\\tmp\\\\file, line1\\nline2, café 雪"}}::vertex'
	)
	vertex = self.parse(vertexExp)
	self.assertEqual(vertex.id, 1125899906842626)
	self.assertEqual(vertex["name"], "test")
	self.assertEqual(vertex["description"], expected_description)

[uesleilima]

Done in 4d0fb3b: the test now builds properties with json.dumps so we exercise embedded quotes, backslashes, newlines, and non-ASCII (e.g. café / 雪) and assert full round-trip equality.

[Copilot]

The added comment says the runtime was tested with Python 3.9–3.14, but the classifiers list does not include Python 3.9 (while requires-python is >=3.9). Consider either adding the Programming Language :: Python :: 3.9 classifier or adjusting the comment to match the supported/tested versions to avoid confusing package metadata.

[uesleilima]

Added the Programming Language :: Python :: 3.9 classifier so metadata matches requires-python = ">=3.9" and the ANTLR runtime comment (same commit).