Add typing annotations

[ale-rt]

Initial draft courtesy of monkeytype:

.venv/bin/uv pip install -e plone.api[test] monkeytype zope.testrunner
monkeytype run .venv/bin/zope-testrunner --path plone.api/src/
for module in `monkeytype list-modules`; do monkeytype apply $module || true > /dev/null;done

• I signed and returned the Plone Contributor Agreement, and received and accepted an invitation to join a team in the Plone GitHub organization.
• I verified there aren't any other open pull requests for the same change.
• I followed the guidelines in Contributing to Plone.
• I successfully ran code quality checks on my changes locally.
• I successfully ran tests on my changes locally.
• If needed, I added new tests for my changes.
• If needed, I added documentation for my changes.
• I included a change log entry in my commits.

---

If your pull request closes an open issue, include the exact text below, immediately followed by the issue number. When your pull request gets merged, then that issue will close automatically.

Closes #

---

📚 Documentation preview 📚: https://ploneapi--592.org.readthedocs.build/

[mister-roboto]

@ale-rt thanks for creating this Pull Request and helping to improve Plone!

TL;DR: Finish pushing changes, pass all other checks, then paste a comment:

@jenkins-plone-org please run jobs

To ensure that these changes do not break other parts of Plone, the Plone test suite matrix needs to pass, but it takes 30-60 min. Other CI checks are usually much faster and the Plone Jenkins resources are limited, so when done pushing changes and all other checks pass either start all Jenkins PR jobs yourself, or simply add the comment above in this PR to start all the jobs automatically.

Happy hacking!

[ale-rt]

This exposes an incorrect behavior of this method as long_format can also be a custom string
https://github.com/plone/plone.base/blob/18f2f4c7ca24da0d6b26bf9c25a061c7cf3ec037/src/plone/base/i18nl10n.py#L221-L224

[ale-rt]

@jenkins-plone-org please run jobs

[ale-rt]

@jenkins-plone-org please run jobs

[ericof]

@ale-rt Take a look at https://github.com/plone/plone-stubs. The current state already support plone.api and it should be in a decent state.

[ale-rt]

@jenkins-plone-org please run jobs

[ale-rt]

@ale-rt Take a look at https://github.com/plone/plone-stubs. The current state already support plone.api and it should be in a decent state.

Thanks, I checked it, yet I believe this is an improvement worth to be merged.

[davisagli]

This will take some time to review carefully.

For a start, at first glance, I see lots of annotations with ImplicitAcquisitionWrapper that look wrong. Those are usually meant to be a DexterityContent, and I think monkeytype was confused by the acquisition wrapper.

[ale-rt]

This will take some time to review carefully.

For a start, at first glance, I see lots of annotations with ImplicitAcquisitionWrapper that look wrong. Those are usually meant to be a DexterityContent, and I think monkeytype was confused by the acquisition wrapper.

It does not look wrong to me:

>>> isinstance(api.portal.get(), ImplicitAcquisitionWrapper)
True

I think it is way worse to use in the annotation DexterityContent because that might be not true at all.

[ericof]

@ale-rt Right now, all content types we have are Dexterity based. I understand your point of using ImplicitAcquisitionWrapper, but this is kind of useless in term of auto-complete for IDEs, isn't it?

[davisagli]

Most of these APIs are designed specifically to work with content objects, not any acquisition-wrapped Python object. So using ImplicitAcquisitionWrapper still seems quite wrong to me.

[ale-rt]

@ale-rt Right now, all content types we have are Dexterity based. I understand your point of using ImplicitAcquisitionWrapper, but this is kind of useless in term of auto-complete for IDEs, isn't it?

Autocomplete in the IDE is not the point of this PR, IMO.

Most probably you will anyway end up with code like:

obj: Document = api.content.get(UID="...")
view: PloneView = api.content.get_view("plone")

[ale-rt]

Most of these APIs are designed specifically to work with content objects, not any acquisition-wrapped Python object. So using ImplicitAcquisitionWrapper still seems quite wrong to me.

To me it seems wrong to say it returns a dexterity content :D
I could replace that with Any, because that would be accurate. What do you think?

[davisagli]

Any is not remotely accurate. If the function is meant to do something with a content item and I pass it a str (for example), that will not work.

[ale-rt]

@jenkins-plone-org please run jobs

[davisagli]

@jenkins-plone-org please run jobs

[davisagli]

LGTM, assuming the jenkins builds pass

[ale-rt]

@ericof, @mauritsvanrees are you ok having this merged?

[ericof]

Would you mind taking a look at plone-stubs? It solves many issues I see with your current approach.
Either way, I'm not opposed to your merge

[davisagli]

@ericof I worked on this with @ale-rt at the sprint. We resolved the issues I had noticed earlier and I think it's in pretty good shape now. What are the issues you still see? We can't consider fixing them if you don't say what they are.

You and I have talked about plone-stubs before. I see the reasoning for having one package in the short term where stubs can be added for multiple Plone packages. But I also think in the long term we should try to add type hints to the actual packages.

[ericof]

@davisagli, @ale-rt First, sorry for sounding so "negative", that was not my intention.

Instead of doing a nit-pick about which types should be returned, I would like to suggest two immediate points (considering what I've learned so far about typing plone.api and other packages) to be addressed:

• We probably should be using more @overloads to closely match the signature of the functions here:

@overload
def get(userid: str, username: str | None = None) -> MemberData | None:
@overload
def get(userid: None, username: str) -> MemberData | None:

• To avoid polluting the code with all overloads, we should ship the .pyi files

If plone.api is completely typed I would remove it from plone-stubs and keep working on the other packages.

And, as I said, I'm not opposing this PR

[davisagli]

@ericof Thanks for the clarification. I agree, using overloads for the functions that accept several different combinations of parameters sounds like it would be a nice improvement.

[davisagli]

Let's go ahead and merge this, and work on other improvements (such as overloads) in a new PR.