{"id":605,"library":"antlr4-python3-runtime","title":"ANTLR 4 Python 3 Runtime","description":"ANTLR (ANother Tool for Language Recognition) is a powerful parser generator. This library provides the Python 3 runtime for lexers and parsers generated by the ANTLR 4 tool. It enables Python applications to process structured text, validate input, and build abstract syntax trees (ASTs) for executing or translating languages. The current version is 4.13.2, with releases typically tied to the main ANTLR tool's irregular but generally annual or bi-annual update cycle.","status":"active","version":"4.13.2","language":"python","source_language":"en","source_url":"https://github.com/antlr/antlr4","tags":["parsing","lexer","parser","grammar","language processing","AST","compiler"],"install":[{"cmd":"pip install antlr4-python3-runtime","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required to run the ANTLR 4 tool (JAR file) for generating Python lexer and parser classes from .g4 grammar files.","package":"Java Runtime Environment (JRE)","optional":false},{"reason":"The Java-based ANTLR 4 tool (e.g., antlr-4.13.2-complete.jar) is necessary to compile .g4 grammars into Python source files (lexer, parser, listener/visitor). The Python runtime uses these generated files.","package":"ANTLR 4 Tool (JAR)","optional":false}],"imports":[{"note":"While `import antlr4` might work for some top-level components, specific classes are typically imported directly from the `antlr4` package or from the *generated* grammar files (e.g., `MyGrammarLexer.py`, `MyGrammarParser.py`).","wrong":"import antlr4","symbol":"InputStream, CommonTokenStream, Lexer, Parser, ParseTreeWalker, ParserRuleContext","correct":"from antlr4 import InputStream, CommonTokenStream\nfrom MyGrammarLexer import MyGrammarLexer # Assumes MyGrammar.g4 was compiled\nfrom MyGrammarParser import MyGrammarParser # Assumes MyGrammar.g4 was compiled\nfrom MyGrammarListener import MyGrammarListener # For listener pattern"}],"quickstart":{"code":"import os\nfrom antlr4 import InputStream, CommonTokenStream, ParseTreeWalker\n\n# --- BEGIN: Dummy generated classes for demonstration ---\n# In a real scenario, these would be generated by the ANTLR tool:\n# java -jar antlr-4.x.x-complete.jar -Dlanguage=Python3 MyGrammar.g4\n\nclass MyGrammarLexer:\n    def __init__(self, input_stream): pass\n    def getAllTokens(self): return []\n\nclass MyGrammarParser:\n    def __init__(self, token_stream): pass\n    def startRule(self): return None # Replace 'startRule' with your grammar's entry rule\n\nclass MyGrammarListener:\n    def enterEveryRule(self, ctx): pass\n    def exitEveryRule(self, ctx): pass\n    # ... other enter/exit methods for your grammar rules\n\n# --- END: Dummy generated classes ---\n\n# Assuming MyGrammar.g4 contains:\n# grammar MyGrammar;\n# startRule: 'hello' ID EOF;\n# ID: [a-zA-Z]+;\n# WS: [ \\t\\r\\n]+ -> skip;\n\ndef parse_input(text):\n    input_stream = InputStream(text)\n    lexer = MyGrammarLexer(input_stream) # Use your generated Lexer class\n    stream = CommonTokenStream(lexer)\n    parser = MyGrammarParser(stream)    # Use your generated Parser class\n    \n    # Optionally, set up error handling\n    # parser.removeErrorListeners()\n    # parser.addErrorListener(MyCustomErrorListener())\n    \n    tree = parser.startRule() # Call the entry rule of your grammar\n    \n    # Optionally, walk the parse tree with a listener or visitor\n    # walker = ParseTreeWalker()\n    # listener = MyGrammarListener() # Use your generated Listener/Visitor class\n    # walker.walk(listener, tree)\n    \n    print(f\"Parse tree: {tree.toStringTree(recog=parser)}\")\n\nif __name__ == '__main__':\n    # Simulate user input or a file content\n    # For a real application, you might read from stdin or a file\n    test_input = os.environ.get('ANTLR_TEST_INPUT', 'hello world')\n    print(f\"Parsing: '{test_input}'\")\n    parse_input(test_input)\n    print(\"Note: In a real scenario, 'MyGrammarLexer' and 'MyGrammarParser' would be generated .py files from your .g4 grammar using the ANTLR Java tool.\")","lang":"python","description":"This quickstart demonstrates the general workflow for using the ANTLR4 Python runtime. It assumes you have already created a `.g4` grammar file (e.g., `MyGrammar.g4`) and used the ANTLR Java tool to generate `MyGrammarLexer.py`, `MyGrammarParser.py`, and `MyGrammarListener.py` (or `MyGrammarVisitor.py`) files in your project directory. The example then shows how to take an input string, tokenize it with the generated lexer, parse it with the generated parser, and print the resulting parse tree. For actual parsing, replace the dummy classes with your real generated classes and ensure the `startRule()` method matches your grammar's entry point."},"warnings":[{"fix":"Upgrade your Python environment to Python 3.6 or higher. For Python 3.5, you must pin the `antlr4-python3-runtime` version to `4.9.x` or earlier (e.g., `pip install antlr4-python3-runtime==4.9.3`).","message":"ANTLR 4.10 and newer versions drop support for Python 3.5. Attempts to install or run the runtime on Python 3.5 will result in `SyntaxError` due to the use of f-strings in the codebase.","severity":"breaking","affected_versions":"4.10.x, 4.11.x, 4.12.x, 4.13.x"},{"fix":"Install a JRE and download the `antlr-4.x.x-complete.jar` file from the official ANTLR website. Then use `java -jar antlr-4.x.x-complete.jar -Dlanguage=Python3 YourGrammar.g4` to generate the Python code before attempting to import it.","message":"The `antlr4-python3-runtime` package only provides the runtime libraries. To generate Python lexer/parser source files (`.py` files) from your `.g4` grammar, you *must* have a Java Runtime Environment (JRE) installed and download the ANTLR 4 tool (a `.jar` file).","severity":"gotcha","affected_versions":"All ANTLR 4 versions"},{"fix":"Upgrade to `antlr4-python3-runtime==4.13.2` or later to resolve this specific version disagreement. Always ensure your ANTLR tool version matches your runtime version as closely as possible.","message":"A known issue existed in version 4.13.1 where the ANTLR runtime's internal version check might conflict with the version of the generated code, leading to runtime errors.","severity":"breaking","affected_versions":"4.13.1"},{"fix":"Select the appropriate input stream class based on your data source: `InputStream(text)` for strings, `FileStream(filepath)` for files, and `StdinStream()` for standard input.","message":"Care must be taken when choosing input streams. For string input, `InputStream` is generally used. For file input, `FileStream` is suitable. For reading from `sys.stdin`, `StdinStream` is available. Mismatching can lead to unexpected behavior or errors.","severity":"gotcha","affected_versions":"All ANTLR 4 versions"},{"fix":"Understand the differences between Listeners (generated with `-listener`) and Visitors (generated with `-visitor`) and choose the pattern that best suits your parse tree processing needs. When using Visitors, remember to explicitly call `visit()` on child nodes if you want to traverse them.","message":"ANTLR 4 provides both Listener and Visitor patterns for traversing parse trees. Listeners are event-driven and perform an LR traversal, calling `enter` and `exit` methods. Visitors offer more control by explicitly requiring you to call `visit()` methods, making them more flexible for complex tree manipulations.","severity":"gotcha","affected_versions":"All ANTLR 4 versions"},{"fix":"Ensure your input string strictly adheres to the defined grammar rules. Specifically, check that the input matches the entry rule you are invoking on the parser (e.g., `parser.myEntryRule()`). You may also want to implement a custom `ErrorListener` to get more detailed feedback on parsing errors.","message":"The parser returned a `None` parse tree, leading to `AttributeError: 'NoneType' object has no attribute 'toStringTree'`. This typically occurs when the input string does not conform to the grammar's rules, especially the entry rule, or if the parser encountered unrecoverable syntax errors.","severity":"breaking","affected_versions":"All ANTLR 4 versions"}],"env_vars":null,"last_verified":"2026-05-12T16:29:54.666Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Install the module using pip: 'pip install antlr4-python3-runtime'.","cause":"The 'antlr4' module is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'antlr4'"},{"fix":"Ensure the module is installed with 'pip install antlr4-python3-runtime' and that the Python path is correctly set.","cause":"The 'antlr4' module is not installed or not found in the Python path.","error":"ImportError: No module named 'antlr4'"},{"fix":"Check the available versions and install a compatible one using 'pip install antlr4-python3-runtime'.","cause":"The specified version of 'antlr4-python3-runtime' is not available for the current Python version or platform.","error":"ERROR: No matching distribution found for antlr4-python3-runtime==4.8"},{"fix":"Review your grammar rules (`.g4` files) and the input string to ensure they are compatible. Adjust either the grammar or the input to match the expected structure, or implement a custom error strategy for more robust error handling.","cause":"The input text being processed by the ANTLR parser does not conform to the grammar rules defined in your `.g4` files at the point where the error occurred.","error":"Mismatched input '...' expecting '...'"},{"fix":"Wrap your input string in `antlr4.InputStream`: `input_stream = antlr4.InputStream(your_string)` then pass `input_stream` to the lexer.","cause":"You are attempting to pass a raw Python string directly to an ANTLR lexer or parser constructor that expects an ANTLR `InputStream` object.","error":"AttributeError: 'str' object has no attribute 'getInputStream'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"4.13.2","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.6,"disk_size":"18.8M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.6,"disk_size":"18.8M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.02,"mem_mb":1.6,"disk_size":"19M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.6,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":1.9,"disk_size":"20.8M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.9,"disk_size":"20.8M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.7,"import_time_s":0.04,"mem_mb":1.9,"disk_size":"21M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.9,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.7,"disk_size":"12.7M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.7,"disk_size":"12.7M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.4,"import_time_s":0.04,"mem_mb":1.7,"disk_size":"13M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.7,"disk_size":"13M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.7,"disk_size":"12.4M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.7,"disk_size":"12.3M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.03,"mem_mb":1.5,"disk_size":"13M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.5,"disk_size":"13M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.6,"disk_size":"18.3M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.6,"disk_size":"18.3M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":0.03,"mem_mb":1.6,"disk_size":"19M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.6,"disk_size":"19M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}