Make match captures a dict[str,Node|list[Node]]

[jhandley]

Return the captures of a match as a dict where the key is the capture name and the value is a Node or a list of Nodes. For regular captures, the value is a Node. For captures that can contain multiple nodes because they use a * or + quantifier, the value is a list of Nodes.

---

Closes #182

[amaanq]

Although I agree it'd be nicer to index a Node/Nodes by the capture name, this is a breaking change. Are there any other benefits to use a dict besides that?

[jhandley]

Although I agree it'd be nicer to index a Node/Nodes by the capture name, this is a breaking change. Are there any other benefits to use a dict besides that?

This only changes the API for the Query.matches method, not the Query.captures method. Given that matches has not been implemented yet in the main branch it shouldn't break anything.

The benefit to using the dict is just a simpler API. At least in the code I've written so far, I always want to look up using the name so this avoids writing extra utility functions to search through the list. So it is just a convenience and not critical. If leaving this out means getting the matches PR (#159) merged faster that it is fine with me. I can work around the lack of dict easily but the workaround for not having Query.matches is not so easy.

[amaanq]

Oops sorry, I just noticed it was for matches, yeah this is totally fine

It's currently a draft, if you think it's ready let me know (unless you intend to change some stuff still)

[jhandley]

I marked it as ready. Note that is against the tree-sitter:prepare-bindings branch, not master.

Let me know if I can help get the matches PR over the finish line. Having matches would be a big help for our current project so I can put some time into it if it would help.

[ObserverOfTime]

@jhandley Are you available to rebase this PR once #159 is merged?

[jhandley]

@jhandley Are you available to rebase this PR once #159 is merged?

Sure. Will do.

[ObserverOfTime]

Also note that | unions are a Python 3.9 feature and py-tree-sitter will continue to support 3.8 until the next version.
Same for list[] and dict[].

[amaanq]

feel free to rebase now @jhandley, sorry for taking so long to get to #159

[ObserverOfTime]

Thank you. This looks good.

[Akuli]

Also note that | unions are a Python 3.9 feature and py-tree-sitter will continue to support 3.8 until the next version.
Same for list[] and dict[].

This is true, but there's still a way for Python 3.8 compatible projects to use list[], dict[], and | unions.

Adding from __future__ import annotations to the beginning of the file makes Python ignore all type annotations (more specifically, make them strings implicitly), so that you can use list[], dict[] and | unions even though Python wouldn't understand them. Type checkers, IDEs and other typing tools know this.

[sgoai]

Did the docs never get updated for this?

[maxbrunsfeld]

Hi, sorry for chiming late here. I don’t think this is an improvement. Having to check, for every usage, whether the values in the dictionary are lists or single nodes is going to make the API more error prone and verbose. The captures within a match have a meaningful order to them, so I think a list of tuples makes more sense than this dictionary of maybe-lists-maybe-nodes.

[ObserverOfTime]

Did the docs never get updated for this?

That is true. I'll update them soon.

Having to check, for every usage, whether the values in the dictionary are lists or single nodes is going to make the API more error prone and verbose.

The values are always lists now.

py-tree-sitter/tree_sitter/__init__.pyi

Lines 282 to 293 in e164972

	def captures(
	self,
	node: Node,
	/,
	predicate: QueryPredicate | None = None
	) -> dict[str, list[Node]]: ...
	def matches(
	self,
	node: Node,
	/,
	predicate: QueryPredicate | None = None
	) -> list[tuple[int, dict[str, list[Node]]]]: ...