Skip to content
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

change: Stop caching parsed docstrings #340

Open
pawamoy opened this issue Dec 5, 2024 · 0 comments
Open

change: Stop caching parsed docstrings #340

pawamoy opened this issue Dec 5, 2024 · 0 comments
Assignees
Labels
griffe: docstrings Related to docstring parsing refactor Change suggestion, not a bug nor a feature.

Comments

@pawamoy
Copy link
Member

pawamoy commented Dec 5, 2024

Is your change request related to a problem? Please describe.

Cached parsed docstrings are causing more issues than they solve. See mkdocstrings/python#183. Cache invalidation of course! The second of the two hardest problems in computer science, after naming things and before off-by-1 errors.

Templates can very easily iterate on the sections once. Other programmatic uses can store the sections in a variable. No need to cache it. I think I initially decided to cache it because it would allow extensions to easily modify sections, which are data structures, instead of having to mess with the raw docstring. But we can solve this too, see next section.

Describe the solution you'd like

Instead of caching the parsed docstrings, provide utilities to make it as easy to modify raw docstrings. Typically:

  • appending a section: docstring.append(DocstringSectionStuff(...)). Here, we don't care what style is used: append will internally parse the docstring using the attached style (or auto-infer it when the feature is available), append the section, and re-dump everything.
  • that means we must implement the opposite of parsers: writers?
  • that will incur a small performance cost too, since we'll more often parse docstrings, but I don't expect them to be parsed a lot anyway (not a lot of extensions modify docstrings, and these extensions do not modify a lot of docstrings).
  • append is just a suggestion, we should design a good API. For example, and related to perfs, we should allow appending several sections at once, etc. Context manager (transactions)?

Describe alternatives you've considered

Not considering. Needs to be done.

Additional context

This will need a deprecation period of course, with warnings and all. We should also reach out to extension authors using cached parsed sections. We use this ourselves in griffe-warnings-deprecated I believe.

@pawamoy pawamoy added griffe: docstrings Related to docstring parsing refactor Change suggestion, not a bug nor a feature. labels Dec 5, 2024
@pawamoy pawamoy self-assigned this Dec 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
griffe: docstrings Related to docstring parsing refactor Change suggestion, not a bug nor a feature.
Projects
None yet
Development

No branches or pull requests

1 participant