Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Conversation

@robinmackaij
Copy link
Contributor

closes #5541

@robinmackaij
Copy link
Contributor Author

Updated annotation for source to be 3.8/3.9 and 3.10+ compatible.

While trying some things, I found that Union versions for Unparsed and Element file on all versions, while the stringified source: "Element | Unparsed" works for 3.8/3.9 but fails for 3.10+. So there's somehow a difference in the behavior of Union[Element, Unparsed] and "Element | Unparsed".

While the current source: Source with Source = Union[Element, Any] (where the source can be an Element of Unparsed) isn't great, I'm inclined to say improving this is better done in / after the release where we drop 3.8 and 3.9 support so we get access to TypeAlias and non-stringified | usage. We'd also have access to typing.Annotated that could be helpful in case we can't get rid of the Any usage; using Annotated metadata we could get nice libdoc output even if the internal annotations aren't complete.

class Element(Protocol):
tag: "bytes | str"

text: "None | str"
Copy link
Contributor Author

Choose a reason for hiding this comment

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

@pekkaklarck text and tail can (per the xml.etree.ElementTree.Element documentation) contain arbitrary objects:

These attributes can be used to hold additional data associated with the element. Their values are usually strings but may be any application-specific object.
...
Applications may store arbitrary objects in these attributes.

This means that technically, the annotations here (and in all keywords related to text or tail) would have to be 'object'. At the same time, no tests fail on the current "None | str" annotations which indicates to me that we have no tests that check on handling "application-specific / arbitrary objects" in keywords. I also don't really see how working with arbitrary data for this would actually work. What do we want to do here?

@pekkaklarck
Copy link
Member

pekkaklarck commented Nov 13, 2025

Let's not make this complicated with Protocols. We are adding typing mainly for documentation purposes and partly to help Robot editord, the idea isn't, at least now, to do type checking. Complex types also don't help with the documentation goal, they just look confusing for non-technical users.

I want to get RF 7.4 out soon. To keep this simple and to avoid wasting time, there are only two ways I see source can be annottated:

  1. As Any. This is also the way I believe it should be annotated in the beginning to get all the other annotations in.
  2. As a custom Source class with a custom converter having documentation that explains supported values. This would be good considering the main goal is enhancing documentation. Type checkers may not like it, but type checking isn't the goal so that's not a big problem.

If you want, you can experiment with Protocols and other ways to make typing better after the option 1. above is ready. If that brings concrete benefits, doesn't complicated code and doesn't make Libdoc documentation complicated, I can consider including it. I anyway want to be extremely clear that most likely such a PR will not be merged at least in RF 7.4 timeframe.

My proposal how to move forward:

  1. You create a PR with source: Any (or with source: Source where Source is a type alias Source = Any).
  2. I merge that PR.
  3. You continue experimenting with better typing if you have interest and don't mind if such enhancement may not be accepted.
  4. I test how using a custom class with custom docs looks like.
  5. I make a decision between Any, custom class and your possible PR with enhanced typing.

@robinmackaij
Copy link
Contributor Author

robinmackaij commented Nov 13, 2025 via email

@robinmackaij
Copy link
Contributor Author

Subclassing Any is not possible / allowed. Also, docstrings for custom classes are not reflected in the libdoc annotations, so I've used 2 "empty" classes Element and ElementOrUnparsed.

This means mypy / pylance don't report anything meaningful, but I believe this is the most useful / clear for the users of the library / keyword docs.

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.

Add annotations to XML.py

2 participants