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