Skip to content

[docutils]: Add annotations for docutils.parsers.rst.states #14209

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 16 commits into
base: main
Choose a base branch
from

Conversation

Harry-Lees
Copy link
Contributor

@Harry-Lees Harry-Lees commented Jun 1, 2025

Linked Issue: #14031

This PR overlaps with #14191, apologies to @donBarbos, I didn't see your PR while working on this. I think this PR is a more fully implemented version of annotations in docutils.parsers.rst.states, but #14191 covers significantly more than just this file.

It might be possible to merge the two together, I will check the other PR to ensure that they line up on the parts which are overlapping.

Edit: I merged some changes where I thought #14191's implementation was more complete than this one, I added Co-authored attribution to the relevant commits, @donBarbos if you are unhappy in any way with the attribution, please let me know how I can update it, I'm not too well versed in Git, but I think I can transfer the commit ownership entirely, or remove you from the commit(s) entirely if you're unhappy to have your name associated with them :)

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

@donBarbos
Copy link
Contributor

Thank you, I suggest merging my PR first and then we can see what improvements you have made ;)

I will also note that stubs for docutils are already fully generated in my draft PR (WIP) and for now I am sorting out the errors and sending separate updates for directories

@srittau
Copy link
Collaborator

srittau commented Jun 3, 2025

I've merged @donBarbos's PR. This now has (as expected) merge conflicts.

@Harry-Lees
Copy link
Contributor Author

I rebased the PR and fixed a couple of obvious errors, I'm sure the CI will have some failures as-well :D.

I need to take a more detailed look at some of the differences, I should be able to get round to it later today.

self, match: Match[str], context: list[str] | None, next_state: str | None
) -> tuple[list[str], str | None, list[str]]: ...
self, match: Match[str], context: Any, next_state: _NextState
) -> tuple[list[Any], _NextState, list[Any]]: ...
Copy link
Contributor Author

Choose a reason for hiding this comment

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

I would appreciate some input in these cases as-well. The implementing function is:

def field_marker(self, match, context, next_state):
    """Field list field."""
    field, blank_finish = self.field(match)
    self.parent += field
    self.blank_finish = blank_finish
    return [], next_state, []

I'm not sure how the [] should be annotated ideally. This is another very common pattern which I have always annotated as list[Any]. I stayed away from list[Never] here, because this will throw an error if the array is appended to (which I can only assume it often is)

Copy link
Member

@AA-Turner AA-Turner Jun 3, 2025

Choose a reason for hiding this comment

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

You will find answers in the docstring of the State class:

    Transition methods all return a 3-tuple:

    - A context object, as (potentially) modified by the transition method.
    - The next state name (a return value of ``None`` means no state change).
    - The processing result, a list, which is accumulated by the state
      machine.

This comment has been minimized.

This comment has been minimized.

Copy link
Contributor

github-actions bot commented Jun 3, 2025

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉

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.

4 participants