Skip to content

Miscellaneous improvements to the behavior and documentation of Visitor, Transformer, Interpreter, and friends#1543

Open
nchammas wants to merge 4 commits intolark-parser:masterfrom
nchammas:misc-visitor-exceptions-docs
Open

Miscellaneous improvements to the behavior and documentation of Visitor, Transformer, Interpreter, and friends#1543
nchammas wants to merge 4 commits intolark-parser:masterfrom
nchammas:misc-visitor-exceptions-docs

Conversation

@nchammas
Copy link
Copy Markdown
Contributor

@nchammas nchammas commented Jul 14, 2025

This PR makes the following improvements.

Documentation:

  • Add docstrings for visit_children_decor and various methods of Interpreter.
  • Correct the top-level docs for Visitor to clarify that it can traverse the tree in either direction.
  • Move utilities into their own section and add documentation for visit_children_decor, which was previously not visible.

Behavior:

  • Have visit_children_decor raise a TypeError if applied to a method of any class other than Interpreter.
  • Have v_args raise a TypeError if applied to a Visitor or its methods. I had to get help from GPT to figure out to make this check work. I'm not confident in the logic.

Comment on lines +599 to +610
from inspect import isclass
if isclass(obj) and issubclass(obj, Visitor):
raise TypeError("v_args cannot be applied to Visitor classes.")
if callable(obj) and not isclass(obj):
@wraps(obj)
def method_wrapper(*args, **kwargs):
if args:
self_instance = args[0]
if isinstance(self_instance, Visitor):
raise TypeError("v_args cannot be applied to Visitor methods.")
return obj(*args, **kwargs)
return _apply_v_args(method_wrapper, func)
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is incorrect in at least one way: We want this to error out on any classes other than Transformer and Interpreter (or their subclasses), not just Visitor. But I am struggling to fix this without causing other tests to fail; I don't really follow this code well to begin with, and would be OK just stripping it out.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@erezsh - Would you like me to remove this new logic as well, or do you have a suggestion as to how we could make it better?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@erezsh - Checking in again here. Happy to cut this PR back to just documentation changes if you prefer that.

@erezsh
Copy link
Copy Markdown
Member

erezsh commented Jul 14, 2025

visit_topdown would actually get the Interpreter to walk the tree bottom up

Can you explain this comment? Interpreter.top_down() would just use the __default__() method, no?

@nchammas
Copy link
Copy Markdown
Contributor Author

Ah, I think I misinterpreted the behavior and jumped to the wrong conclusion.

Is the behavior of Interpreter.visit_topdown() fine as it is on master? Or is my proposed patch correct and just needs a fixed description?

@erezsh
Copy link
Copy Markdown
Member

erezsh commented Jul 14, 2025

@nchammas Well, I can see how it was confusing. But I don't think adding visit_topdown fixes anything. Interpreter is behaving as expected, and if it's not implemented with the best design, that's another matter, but adding this method won't change that.

@erezsh
Copy link
Copy Markdown
Member

erezsh commented Jul 14, 2025

Maybe it would be better to remove the __getattr__, but that would be slightly backwards-incompatible, in case anyone relied on this behavior, for some reason.

@nchammas
Copy link
Copy Markdown
Contributor Author

@erezsh - No rush; just wanted to check in again if I can do anything to move this PR forward.

@nchammas
Copy link
Copy Markdown
Contributor Author

nchammas commented Mar 9, 2026

Hi @erezsh - Is there anything I can do to move this PR forward, including reducing the scope? If not, happy to just close it.

@erezsh
Copy link
Copy Markdown
Member

erezsh commented Mar 9, 2026

Hi @nchammas , sorry, I was a bit distracted with other projects. I'll try to allocate some time for Lark soon.

Do I have your permission to take the parts I like and leave out the rest? Some of the edits might remove the authorship marker from the commits, but I'll try to avoid it.

@nchammas
Copy link
Copy Markdown
Contributor Author

nchammas commented Mar 9, 2026

Do I have your permission to take the parts I like and leave out the rest? Some of the edits might remove the authorship marker from the commits, but I'll try to avoid it.

Sure, go ahead. I have the "Allow edits by maintainers" thing enabled on this PR, so you can just push commits here if that's easiest for you.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants