plone.api 2.2.4__tar.gz → 2.3.0__tar.gz

{plone_api-2.2.4 → plone_api-2.3.0}/CHANGES.rst

@@ -8,6 +8,48 @@ Changelog
 
 .. towncrier release notes start
 
+2.3.0 (2025-02-21)
+------------------
+
+New features:
+
+
+- Added the content API helper function ``api.content.get_path``, which gets either the relative or absolute path of an object. @ujsquared (#532)
+- Added two new portal API functions:
+  - ``api.portal.get_vocabulary``: Get a vocabulary by name
+  - ``api.portal.get_vocabulary_names``: Get a list of all available vocabulary names
+  @ujsquared (#533)
+
+
+Internal:
+
+
+- Making it easier for new contributors to get started with a simple Makefile and a tidy 'contributing' chapter. @ksuess (#558)
+
+
+2.2.5 (2025-01-24)
+------------------
+
+Bug fixes:
+
+
+- Fix api.content.get(path=path) when a item in the path is not accessible to the user.
+  [pbauer] (#549)
+- Fix DeprecationWarnings. [maurits] (#4090)
+
+
+Documentation:
+
+
+- Preview docs on Read the Docs instead of Netlify. @stevepiercy (#545)
+- Remove Netlify stuff, follow up to #545. @stevepiercy
+  - Sort and remove duplicate entries in `pyproject.toml`
+  - Remove unused docs requirements.
+  - Fix comments and remove unnecessary steps from `tox.ini`.
+  - Enable copy button for code blocks.
+  - Add linkcheck to documentation of documentation. (#546)
+
+
 2.2.4 (2024-12-16)
 ------------------
 

{plone_api-2.2.4 → plone_api-2.3.0}/MANIFEST.in

@@ -13,6 +13,8 @@ global-exclude *.pyc
 include pyproject.toml
 recursive-exclude news *
 exclude news
+recursive-exclude .vscode *
+exclude .readthedocs.yaml
 
 # added by check-manifest
 recursive-include src *.py

{plone_api-2.2.4 → plone_api-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: plone.api
-Version: 2.2.4
+Version: 2.3.0
 Summary: A Plone API.
 Home-page: https://github.com/plone/plone.api
 Author: Plone Foundation
@@ -34,8 +34,8 @@ Requires-Dist: decorator
 Requires-Dist: plone.app.uuid
 Requires-Dist: plone.app.dexterity
 Requires-Dist: plone.app.intid
-Requires-Dist: plone.app.layout
 Requires-Dist: plone.app.linkintegrity
+Requires-Dist: plone.base
 Requires-Dist: plone.dexterity
 Requires-Dist: plone.i18n
 Requires-Dist: plone.registry
@@ -110,6 +110,48 @@ Changelog
 
 .. towncrier release notes start
 
+2.3.0 (2025-02-21)
+------------------
+
+New features:
+
+
+- Added the content API helper function ``api.content.get_path``, which gets either the relative or absolute path of an object. @ujsquared (#532)
+- Added two new portal API functions:
+  - ``api.portal.get_vocabulary``: Get a vocabulary by name
+  - ``api.portal.get_vocabulary_names``: Get a list of all available vocabulary names
+  @ujsquared (#533)
+
+
+Internal:
+
+
+- Making it easier for new contributors to get started with a simple Makefile and a tidy 'contributing' chapter. @ksuess (#558)
+
+
+2.2.5 (2025-01-24)
+------------------
+
+Bug fixes:
+
+
+- Fix api.content.get(path=path) when a item in the path is not accessible to the user.
+  [pbauer] (#549)
+- Fix DeprecationWarnings. [maurits] (#4090)
+
+
+Documentation:
+
+
+- Preview docs on Read the Docs instead of Netlify. @stevepiercy (#545)
+- Remove Netlify stuff, follow up to #545. @stevepiercy
+  - Sort and remove duplicate entries in `pyproject.toml`
+  - Remove unused docs requirements.
+  - Fix comments and remove unnecessary steps from `tox.ini`.
+  - Enable copy button for code blocks.
+  - Add linkcheck to documentation of documentation. (#546)
+
+
 2.2.4 (2024-12-16)
 ------------------
 

{plone_api-2.2.4 → plone_api-2.3.0}/docs/content.md

@@ -78,7 +78,7 @@ plone (portal root)
 % api.content.create(container=events, type='Event', id='conference')
 % api.content.create(container=events, type='Event', id='sprint')
 
-The following operations will get objects from the structure above, including using {meth}`api.content.get`.
+The following operations will get objects from the structure above, using {meth}`api.content.get`.
 
 ```python
 # let's first get the portal object
@@ -118,7 +118,7 @@ not_found = api.content.get(UID='notfound')
 
 ## Find content objects
 
-You can use the find function to search for content.
+You can use the {func}`api.content.find` function to search for content.
 
 Finding all Documents:
 
@@ -460,7 +460,6 @@ portal = api.portal.get()
 api.content.transition(obj=portal['about'], transition='reject', comment='You had a typo on your page.')
 ```
 
-
 (content-disable-roles-acquisition-example)=
 
 ## Disable local roles acquisition
@@ -536,6 +535,60 @@ view = api.content.get_view(
 %
 % self.assertEqual(view.__name__, u'plone')
 
+(content-get-path-example)=
+
+## Get content path
+
+To get the path of a content object, use {func}`api.content.get_path`.
+This function accepts an object for which you want to get its path as the required parameter `obj`, and an optional boolean parameter `relative` whose default is `False`.
+
+It returns either an absolute path from the Zope root by default or when `relative` is set to `False`, or a relative path from the portal root when `relative` is set to `True`.
+
+The following example shows how to get the absolute path from the Zope root.
+
+```python
+from plone import api
+portal = api.portal.get()
+
+folder = portal['events']['training']
+path = api.content.get_path(obj=folder)
+assert path == '/plone/events/training'
+```
+
+The following example shows how to get the portal-relative path.
+
+```python
+rel_path = api.content.get_path(obj=folder, relative=True)
+assert rel_path == 'events/training'
+```
+
+If the API is used to fetch an object with the `relative` parameter set as `True`, and the object is outside the portal, it throws an `InvalidParameterError` error.
+
+% invisible-code-block: python
+%
+% # Setup an object outside portal for testing error case
+% app = portal.aq_parent
+% app.manage_addFolder('outside_folder')
+%
+% # Test that getting relative path for object outside portal raises error
+% from plone.api.exc import InvalidParameterError
+% with self.assertRaises(InvalidParameterError):
+%     api.content.get_path(obj=app.outside_folder, relative=True)
+
+```python
+from plone.api.exc import InvalidParameterError
+
+# Getting path of an object outside portal raises InvalidParameterError
+try:
+    outside_path = api.content.get_path(
+        obj=app.outside_folder,
+        relative=True
+    )
+    assert False, "Should raise InvalidParameterError and not reach this code"
+except InvalidParameterError as e:
+    assert "Object not in portal path" in str(e)
+```
+
 ## Further reading
 
 For more information on possible flags and usage options please see the full {ref}`plone-api-content` specification.

{plone_api-2.2.4 → plone_api-2.3.0}/docs/contribute.md

@@ -18,65 +18,42 @@ Prepare your system by installing prerequisites.
 
 ### System libraries
 
-You need to install system libraries, as described in {ref}`plone:plone-prerequisites-label`, with the exception of GNU make.
+You need to install system libraries, as described in {ref}`plone:plone-prerequisites-label`.
 
-### tox
-
-[tox](https://tox.wiki/en/stable/index.html) automates and standardizes testing in Python.
-Install tox into your Python user space with the following command.
-
-```shell
-python -m pip install --user tox
-```
-
-### pre-commit
-
-`plone.api` uses [pre-commit](https://pre-commit.com/) to automate code quality checks before every commit.
-
-Install pre-commit either with your system package manager.
-Alternatively you can install pre-commit into your Python user.
-
-```shell
-python -m pip install --user pre-commit
-```
-
-Once installed, set up the git hook scripts to run on every commit.
-
-```shell
-pre-commit install
-```
 
 ## Create development environment
 
 After satisfying the prerequisites, you are ready to create your development environment.
 `plone.api` uses `tox` as a wrapper around `coredev.buildout` to simplify development, whereas Plone core uses `coredev.buildout` directly.
+Additionally `plone.api` uses `make` commands that invoke the `tox` commands as a convenience and for consistency across Plone packages.
 
-Start by changing your working directory to your project folder, and download the latest `plone.api` source code.
+Start by changing your working directory to your project folder, and check out the latest `plone.api` source code.
 
 ```shell
 cd <your_project_folder>
 git clone https://github.com/plone/plone.api.git
 ```
 
-Next go into the newly created directory, and build your environment.
+Run `make help` to see the available `make` commands.
 
-```shell
-cd plone.api
-tox
+```console
+check                          Check code base according to Plone standards
+clean                          Clean environment
+help                           This help message
+linkcheck                      Check links in documentation
+livehtml                       Build docs and watch for changes
+test                           Run tests
 ```
 
-Go make some tea while `tox` runs all tasks listed by issuing the command `tox -l`.
+The `make` commands `check`, `livehtml`, and `test` will create a development environment, if it does not already exist.
 
-Open `tox.ini` in your code editor to see all configured commands and what they do.
-Some helpful `tox` commands are shown below.
+Test your code changes with the following command.
 
 ```shell
-tox -e py39-plone-60  # run all tests for Python 3.9 and Plone 6
-tox -e plone6docs     # build documentation
-tox -e livehtml       # build, serve, and reload changes to documentation
-tox -l                # list all tox environments
+make test
 ```
 
+
 (git-workflow)=
 
 ## git
@@ -109,16 +86,17 @@ For every feature change or addition to `plone.api`, you must add documentation
 {doc}`plone:contributing/documentation/index`
 ```
 
-After adding or modifying documentation, you can build the documentation with the following command.
+When adding or modifying documentation, you can build the documentation with the following command.
+As you edit the documentation, the started process automatically reloads your changes in the web browser.
 
 ```shell
-tox -e plone6docs
+make livehtml
 ```
 
-Alternatively, you can automatically reload changes to the documentation as you edit it in a web browser.
+You can run a link checker on documentation.
 
 ```shell
-tox -e livehtml
+make linkcheck
 ```
 
 The [`plone.api` documentation](https://6.docs.plone.org/plone.api) is automatically generated from the documentation source files when its submodule is updated in the [main Plone `documentation` repository](https://github.com/plone/documentation/).
@@ -166,6 +144,10 @@ def foo(path=None, UID=None):
 % InvalidParameterError,
 % lambda: foo("/plone/blog", "abcd001")
 % )
+%
+% # Make it available for testing below
+% from plone import api
+% api.content.foo = foo
 
 Add documentation in {file}`docs/api/content.md`.
 Narrative documentation should describe what your function does.
@@ -192,7 +174,8 @@ blog_foo = api.content.foo(path="/plone/blog")
 
 % invisible-code-block: python
 %
-% self.assertEqual(blog_foo,"foo")
+% self.assertEqual(blog_foo, "foo")
+
 ````
 
 Code blocks are rendered in documentation.
@@ -209,7 +192,7 @@ Invisible code blocks are not rendered in documentation and can be used for test
 ```markdown
 % invisible-code-block: python
 %
-% self.assertEqual(blog_foo,"foo")
+% self.assertEqual(blog_foo, "foo")
 ```
 
 Invisible code blocks are also handy for enriching the namespace without cluttering the narrative documentation.

{plone_api-2.2.4 → plone_api-2.3.0}/docs/portal.md

@@ -45,7 +45,7 @@ Assuming there is a document `english_page` in a folder `en`, which is the navig
 % invisible-code-block: python
 %
 % from plone import api
-% from plone.app.layout.navigation.interfaces import INavigationRoot
+% from plone.base.interfaces import INavigationRoot
 % from zope.interface import alsoProvides
 %
 % portal = api.portal.get()
@@ -416,6 +416,49 @@ api.portal.set_registry_record('field_one', 'new value', interface=IMyRegistrySe
 %     'new value'
 % )
 
+(portal-get-vocabulary-example)=
+
+## Get vocabulary
+
+To get a vocabulary by name, use {func}`api.portal.get_vocabulary`.
+
+```python
+from plone import api
+
+# Get vocabulary using default portal context
+vocabulary = api.portal.get_vocabulary(name='plone.app.vocabularies.PortalTypes')
+
+# Get vocabulary with specific context
+context = api.portal.get()
+states_vocabulary = api.portal.get_vocabulary(
+    name='plone.app.vocabularies.WorkflowStates',
+    context=context
+)
+```
+
+(portal-get-all-vocabulary-names-example)=
+
+## Get all vocabulary names
+
+To get a list of all available vocabulary names in your Plone site, use {meth}`api.portal.get_vocabulary_names`.
+
+```python
+from plone import api
+
+# Get all vocabulary names
+vocabulary_names = api.portal.get_vocabulary_names()
+
+# Common vocabularies that should be available
+common_vocabularies = [
+    'plone.app.vocabularies.PortalTypes',
+    'plone.app.vocabularies.WorkflowStates',
+    'plone.app.vocabularies.WorkflowTransitions'
+]
+
+for vocabulary_name in common_vocabularies:
+    assert vocabulary_name in vocabulary_names
+```
+
 ## Further reading
 
 For more information on possible flags and usage options please see the full {ref}`plone-api-portal` specification.

{plone_api-2.2.4 → plone_api-2.3.0}/pyproject.toml

@@ -140,14 +140,14 @@ ignore = [
     "dependabot.yml",
     "mx.ini",
     "tox.ini",
-    ".editorconfig",
     "*.cfg",
+    ".editorconfig",
+    ".readthedocs.yaml",
     "constraints_plone52.txt",
     "constraints_plone60.txt",
     "constraints.txt",
     "fix-converted-myst.py",
     "Makefile",
-    "netlify.toml",
     "requirements-docs.txt",
     "requirements.txt",
 

{plone_api-2.2.4 → plone_api-2.3.0}/setup.py

@@ -3,7 +3,7 @@ from setuptools import find_packages
 from setuptools import setup
 
 
-version = "2.2.4"
+version = "2.3.0"
 
 long_description = (
     f"{Path('README.md').read_text()}\n"
@@ -36,8 +36,8 @@ setup(
         "plone.app.uuid",
         "plone.app.dexterity",
         "plone.app.intid",
-        "plone.app.layout",
         "plone.app.linkintegrity",
+        "plone.base",
         "plone.dexterity",
         "plone.i18n",
         "plone.registry",

{plone_api-2.2.4 → plone_api-2.3.0}/src/plone/api/content.py

@@ -133,7 +133,12 @@ def get(path=None, UID=None):
                 relative_path=path,
             )
         try:
-            content = site.restrictedTraverse(path)
+            path = path.split("/")
+            if len(path) > 1:
+                parent = site.unrestrictedTraverse(path[:-1])
+                content = parent.restrictedTraverse(path[-1])
+            else:
+                content = site.restrictedTraverse(path[-1])
         except (KeyError, AttributeError):
             return None  # When no object is found don't raise an error
         else:
@@ -564,6 +569,36 @@ def get_uuid(obj=None):
     return IUUID(obj)
 
 
+@required_parameters("obj")
+def get_path(obj=None, relative=False):
+    """Get the path of an object.
+
+    :param obj: [required] Object for which to get its path
+    :type obj: Content object
+    :param relative: Return a relative path from the portal root
+    :type relative: boolean
+    :returns: Path to the object
+    :rtype: string
+    :raises:
+        InvalidParameterError
+    :Example: :ref:`content-get-path-example`
+    """
+    if not hasattr(obj, "getPhysicalPath"):
+        raise InvalidParameterError(f"Cannot get path of object {obj!r}")
+
+    if not relative:
+        return "/".join(obj.getPhysicalPath())
+    site = portal.get()
+    site_path = site.getPhysicalPath()
+    obj_path = obj.getPhysicalPath()
+    if obj_path[: len(site_path)] != site_path:
+        raise InvalidParameterError(
+            "Object not in portal path. Object path: {}".format("/".join(obj_path))
+        )
+    rel_path = obj_path[len(site_path) :]
+    return "/".join(rel_path) if rel_path else ""
+
+
 def _parse_object_provides_query(query):
     """Create a query for the object_provides index.
 

{plone_api-2.2.4 → plone_api-2.3.0}/src/plone/api/portal.py

@@ -7,16 +7,19 @@ from logging import getLogger
 from plone.api.exc import CannotGetPortalError
 from plone.api.exc import InvalidParameterError
 from plone.api.validation import required_parameters
-from plone.app.layout.navigation.root import getNavigationRootObject
+from plone.base.navigationroot import get_navigation_root_object
 from plone.registry.interfaces import IRegistry
 from Products.CMFCore.interfaces import ISiteRoot
 from Products.CMFCore.utils import getToolByName
 from Products.statusmessages.interfaces import IStatusMessage
+from zope.component import ComponentLookupError
+from zope.component import getUtilitiesFor
 from zope.component import getUtility
 from zope.component import providedBy
 from zope.component.hooks import getSite
 from zope.globalrequest import getRequest
 from zope.interface.interfaces import IInterface
+from zope.schema.interfaces import IVocabularyFactory
 
 import datetime as dtime
 import re
@@ -86,7 +89,7 @@ def get_navigation_root(context=None):
     :Example: :ref:`portal-get-navigation-root-example`
     """
     context = aq_inner(context)
-    return getNavigationRootObject(context, get())
+    return get_navigation_root_object(context, get())
 
 
 @required_parameters("name")
@@ -431,3 +434,41 @@ def translate(msgid, domain="plone", lang=None):
         # Pass the request, so zope.i18n.translate can negotiate the language.
         query["context"] = getRequest()
     return translation_service.utranslate(**query)
+
+
+@required_parameters("name")
+def get_vocabulary(name=None, context=None):
+    """Return a vocabulary object with the given name.
+
+    :param name: Name of the vocabulary.
+    :type name: str
+    :param context: Context to be applied to the vocabulary. Default: portal root.
+    :type context: object
+    :returns: A SimpleVocabulary instance that implements IVocabularyTokenized.
+    :rtype: zope.schema.vocabulary.SimpleVocabulary
+    :Example: :ref:`portal-get-vocabulary-example`
+    """
+    if context is None:
+        context = get()
+    try:
+        vocabulary = getUtility(IVocabularyFactory, name)
+    except ComponentLookupError:
+        raise InvalidParameterError(
+            "Cannot find a vocabulary with name '{name}'.\n"
+            "Available vocabularies are:\n"
+            "{vocabularies}".format(
+                name=name,
+                vocabularies="\n".join(get_vocabulary_names()),
+            ),
+        )
+    return vocabulary(context)
+
+
+def get_vocabulary_names():
+    """Return a list of vocabulary names.
+
+    :returns: A sorted list of vocabulary names.
+    :rtype: list[str]
+    :Example: :ref:`portal-get-all-vocabulary-names-example`
+    """
+    return sorted([name for name, vocabulary in getUtilitiesFor(IVocabularyFactory)])

{plone_api-2.2.4 → plone_api-2.3.0}/src/plone/api/relation.py

@@ -10,8 +10,8 @@ from plone.api.validation import at_least_one_of
 from plone.api.validation import required_parameters
 from plone.app.linkintegrity.handlers import modifiedContent
 from plone.app.linkintegrity.utils import referencedRelationship
+from plone.base.utils import base_hasattr
 from plone.dexterity.utils import iterSchemataForType
-from Products.CMFPlone.utils import base_hasattr
 from z3c.relationfield import event
 from z3c.relationfield import RelationValue
 from z3c.relationfield.schema import Relation

{plone_api-2.2.4 → plone_api-2.3.0}/src/plone/api/testing.zcml

@@ -14,7 +14,7 @@
       title="plone.api: Test fixture"
       description="Extension profile to configure a test fixture"
       provides="Products.GenericSetup.interfaces.EXTENSION"
-      for="Products.CMFPlone.interfaces.ITestCasePloneSiteRoot"
+      for="plone.base.interfaces.ITestCasePloneSiteRoot"
       directory="profiles/testfixture"
       />
 

{plone_api-2.2.4 → plone_api-2.3.0}/src/plone/api/tests/doctests/content.md

@@ -78,7 +78,7 @@ plone (portal root)
 % api.content.create(container=events, type='Event', id='conference')
 % api.content.create(container=events, type='Event', id='sprint')
 
-The following operations will get objects from the structure above, including using {meth}`api.content.get`.
+The following operations will get objects from the structure above, using {meth}`api.content.get`.
 
 ```python
 # let's first get the portal object
@@ -118,7 +118,7 @@ not_found = api.content.get(UID='notfound')
 
 ## Find content objects
 
-You can use the find function to search for content.
+You can use the {func}`api.content.find` function to search for content.
 
 Finding all Documents:
 
@@ -460,7 +460,6 @@ portal = api.portal.get()
 api.content.transition(obj=portal['about'], transition='reject', comment='You had a typo on your page.')
 ```
 
-
 (content-disable-roles-acquisition-example)=
 
 ## Disable local roles acquisition
@@ -536,6 +535,60 @@ view = api.content.get_view(
 %
 % self.assertEqual(view.__name__, u'plone')
 
+(content-get-path-example)=
+
+## Get content path
+
+To get the path of a content object, use {func}`api.content.get_path`.
+This function accepts an object for which you want to get its path as the required parameter `obj`, and an optional boolean parameter `relative` whose default is `False`.
+
+It returns either an absolute path from the Zope root by default or when `relative` is set to `False`, or a relative path from the portal root when `relative` is set to `True`.
+
+The following example shows how to get the absolute path from the Zope root.
+
+```python
+from plone import api
+portal = api.portal.get()
+
+folder = portal['events']['training']
+path = api.content.get_path(obj=folder)
+assert path == '/plone/events/training'
+```
+
+The following example shows how to get the portal-relative path.
+
+```python
+rel_path = api.content.get_path(obj=folder, relative=True)
+assert rel_path == 'events/training'
+```
+
+If the API is used to fetch an object with the `relative` parameter set as `True`, and the object is outside the portal, it throws an `InvalidParameterError` error.
+
+% invisible-code-block: python
+%
+% # Setup an object outside portal for testing error case
+% app = portal.aq_parent
+% app.manage_addFolder('outside_folder')
+%
+% # Test that getting relative path for object outside portal raises error
+% from plone.api.exc import InvalidParameterError
+% with self.assertRaises(InvalidParameterError):
+%     api.content.get_path(obj=app.outside_folder, relative=True)
+
+```python
+from plone.api.exc import InvalidParameterError
+
+# Getting path of an object outside portal raises InvalidParameterError
+try:
+    outside_path = api.content.get_path(
+        obj=app.outside_folder,
+        relative=True
+    )
+    assert False, "Should raise InvalidParameterError and not reach this code"
+except InvalidParameterError as e:
+    assert "Object not in portal path" in str(e)
+```
+
 ## Further reading
 
 For more information on possible flags and usage options please see the full {ref}`plone-api-content` specification.