plone.api 2.2.5__tar.gz → 2.3.0__tar.gz

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

@@ -8,6 +8,25 @@ 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)
 ------------------
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: plone.api
-Version: 2.2.5
+Version: 2.3.0
 Summary: A Plone API.
 Home-page: https://github.com/plone/plone.api
 Author: Plone Foundation
@@ -110,6 +110,25 @@ 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)
 ------------------
 

{plone_api-2.2.5 → 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.5 → 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,22 +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
-```
-
-Alternatively, you can automatically reload changes to the documentation as you edit it in a web browser.
-
-```shell
-tox -e livehtml
+make livehtml
 ```
 
 You can run a link checker on documentation.
 
 ```shell
-tox -e linkcheck
+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/).
@@ -172,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.
@@ -198,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.
@@ -215,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.5/src/plone/api/tests/doctests → plone_api-2.3.0/docs}/portal.md

@@ -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.5 → plone_api-2.3.0}/setup.py

@@ -3,7 +3,7 @@ from setuptools import find_packages
 from setuptools import setup
 
 
-version = "2.2.5"
+version = "2.3.0"
 
 long_description = (
     f"{Path('README.md').read_text()}\n"

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

@@ -569,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.5 → plone_api-2.3.0}/src/plone/api/portal.py

@@ -12,11 +12,14 @@ 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
@@ -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.5 → 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.

plone_api-2.3.0/src/plone/api/tests/doctests/contribute.md

@@ -0,0 +1,217 @@
+---
+myst:
+  html_meta:
+    "description": "Contribute to plone.api"
+    "property=og:description": "Contribute to plone.api"
+    "property=og:title": "Contribute to plone.api"
+    "keywords": "plone.api, contribute, Plone, API, development"
+---
+
+# Contribute to `plone.api`
+
+This section describes how to contribute to the `plone.api` project.
+It extends {doc}`plone:contributing/index`.
+
+## Prerequisites
+
+Prepare your system by installing prerequisites.
+
+### System libraries
+
+You need to install system libraries, as described in {ref}`plone:plone-prerequisites-label`.
+
+
+## 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 check out the latest `plone.api` source code.
+
+```shell
+cd <your_project_folder>
+git clone https://github.com/plone/plone.api.git
+```
+
+Run `make help` to see the available `make` commands.
+
+```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
+```
+
+The `make` commands `check`, `livehtml`, and `test` will create a development environment, if it does not already exist.
+
+Test your code changes with the following command.
+
+```shell
+make test
+```
+
+
+(git-workflow)=
+
+## git
+
+Use the following git branches when contributing to `plone.api`.
+
+feature branches
+: All development for a new feature or bug fix must be done on a new branch.
+
+`main`
+: Pull requests should be made from a feature branch against the `main` branch.
+When features and bug fixes are complete and approved, they are merged into the `main` branch.
+
+```{seealso}
+{ref}`plone:contributing-core-work-with-git-label`
+```
+
+## Continuous integration
+
+`plone.api` uses GitHub workflows for continuous integration.
+On every push to the `main` branch, GitHub runs its workflows for all tests and code quality checks.
+GitHub workflows are configured in the directory `.github/workflows` at the root of this package.
+
+## Documentation
+
+For every feature change or addition to `plone.api`, you must add documentation of it.
+`plone.api` uses [MyST](https://myst-parser.readthedocs.io/en/latest/) for documentation syntax.
+
+```{seealso}
+{doc}`plone:contributing/documentation/index`
+```
+
+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
+make livehtml
+```
+
+You can run a link checker on documentation.
+
+```shell
+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/).
+
+## Add a function to an existing module
+
+This section describes how to add a new function `foo` to `plone.api`.
+
+The function would go in the module `plone.api.content`, located in the file {file}`src/plone/api/content.py`.
+
+% invisible-code-block: python
+%
+% from plone.api.validation import at_least_one_of
+% from plone.api.validation import mutually_exclusive_parameters
+
+```python
+@mutually_exclusive_parameters('path', 'UID')
+@at_least_one_of('path', 'UID')
+def foo(path=None, UID=None):
+    """Do foo.
+
+    :param path: Path to the object we want to get,
+        relative to the portal root.
+    :type path: string
+
+    :param UID: UID of the object we want to get.
+    :type UID: string
+
+    :returns: String
+    :raises:
+        :class:`~plone.api.exc.MissingParameterError`,
+        :class:`~plone.api.exc.InvalidParameterError`
+    :Example: :ref:`content-foo-example`
+    """
+    return "foo"
+```
+
+% invisible-code-block: python
+%
+% bar = foo('/plone/blog')
+% self.assertEqual(bar,"foo")
+%
+% from plone.api.exc import InvalidParameterError
+% self.assertRaises(
+% 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.
+
+You should also write some tests in code blocks.
+`TestCase` methods, such as `self.assertEqual()`, are available in `doctests`.
+See [unittest.TestCase assert methods](https://docs.python.org/3/library/unittest.html#unittest.TestCase.debug) for all available methods.
+The file is linked in `/src/plone/api/tests/doctests/`, which includes the doctests in `plone.api`'s test setup.
+The package `manuel` allows you to write doctests as common Python code in code blocks.
+
+The following example shows narrative documentation and doctests.
+
+````markdown
+(content-foo-example)=
+
+## Get the foo of an object
+
+You can use the {meth}`api.content.foo` function to get the `foo` of an object.
+
+```python
+from plone import api
+blog_foo = api.content.foo(path="/plone/blog")
+```
+
+% invisible-code-block: python
+%
+% self.assertEqual(blog_foo, "foo")
+
+````
+
+Code blocks are rendered in documentation.
+
+````markdown
+```python
+from plone import api
+blog_foo = api.content.foo(path="/plone/blog")
+```
+````
+
+Invisible code blocks are not rendered in documentation and can be used for tests.
+
+```markdown
+% invisible-code-block: python
+%
+% self.assertEqual(blog_foo, "foo")
+```
+
+Invisible code blocks are also handy for enriching the namespace without cluttering the narrative documentation.
+
+```markdown
+% invisible-code-block: python
+%
+% portal = api.portal.get()
+% image = api.content.create(type='Image', id='image', container=portal)
+% blog = api.content.create(type='Link', id='blog', container=portal)
+```
+
+Functions and examples in documentation are mutually referenced.
+The function references the narrative documentation via the label `content-foo-example`.
+The narrative documentation references the API function documentation via `` {meth}`api.content.foo` ``.
+The documentation is rendered with a link from the API reference to the narrative documentation, which in turn links back to the API reference.
+
+## Resources
+
+- {doc}`plone:index`
+- [Source code](https://github.com/plone/plone.api)
+- [Issue tracker](https://github.com/plone/plone.api/issues)

{plone_api-2.2.5/docs → plone_api-2.3.0/src/plone/api/tests/doctests}/portal.md

@@ -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.5 → plone_api-2.3.0}/src/plone/api/tests/test_content.py

@@ -1447,3 +1447,66 @@ class TestPloneApiContent(unittest.TestCase):
 
         for should_be_there in should_be_theres:
             self.assertIn((should_be_there + "\n"), str(cm.exception))
+
+    def test_get_path_absolute(self):
+        """Test getting the path of a content object with relative parameter set to False."""
+        from plone.api.exc import InvalidParameterError
+
+        portal = self.layer["portal"]
+
+        # Test portal root
+        self.assertEqual(
+            api.content.get_path(portal), "/plone"  # This assumes default Plone site id
+        )
+
+        # Test folder structure
+        folder = api.content.create(container=portal, type="Folder", id="test-folder")
+        self.assertEqual(api.content.get_path(folder), "/plone/test-folder")
+
+        # Test nested content
+        document = api.content.create(
+            container=folder, type="Document", id="test-document"
+        )
+        self.assertEqual(
+            api.content.get_path(document), "/plone/test-folder/test-document"
+        )
+
+        # Test invalid object
+        invalid_obj = object()
+        with self.assertRaises(InvalidParameterError):
+            api.content.get_path(invalid_obj)
+        self.assertRaisesRegex(
+            InvalidParameterError,
+            r"^Cannot get path of object <object object at 0x[0-9a-f]+>$",
+        )
+
+    def test_get_path_relative(self):
+        from plone.api.exc import InvalidParameterError
+
+        portal = self.layer["portal"]
+
+        # Test portal root
+        self.assertEqual(api.content.get_path(portal, relative=True), "")
+
+        # Test folder structure
+        folder = api.content.create(container=portal, type="Folder", id="test-folder")
+        self.assertEqual(api.content.get_path(folder, relative=True), "test-folder")
+
+        # Test nested content
+        document = api.content.create(
+            container=folder, type="Document", id="test-document"
+        )
+        self.assertEqual(
+            api.content.get_path(document, relative=True),
+            "test-folder/test-document",
+        )
+
+        # Test object outside portal
+        class FauxObject:
+            def getPhysicalPath(self):
+                return ("", "foo", "bar")
+
+        outside_obj = FauxObject()
+        with self.assertRaises(InvalidParameterError) as cm:
+            api.content.get_path(outside_obj, relative=True)
+        self.assertIn("Object not in portal path", str(cm.exception))

{plone_api-2.2.5 → plone_api-2.3.0}/src/plone/api/tests/test_doctests.py

@@ -115,7 +115,7 @@ def DocFileSuite(
 
 
 def test_suite():
-    """Find .rst files and test code examples in them."""
+    """Find .md files and test code examples in them."""
     path = "doctests"
     doctests = []
     docs_path = os.path.join(os.path.dirname(__file__), path)

{plone_api-2.2.5 → plone_api-2.3.0}/src/plone/api/tests/test_portal.py

@@ -19,6 +19,7 @@ from zope import schema
 from zope.component import getUtility
 from zope.component.hooks import setSite
 from zope.interface import Interface
+from zope.schema.vocabulary import SimpleVocabulary
 from zope.site import LocalSiteManager
 
 import DateTime
@@ -894,3 +895,71 @@ class TestPloneApiPortal(unittest.TestCase):
             ),
             "Página",
         )
+
+    def test_get_vocabulary(self):
+        """Test getting a vocabulary by name."""
+        from plone.api.exc import InvalidParameterError
+        from plone.api.exc import MissingParameterError
+
+        # The vocabulary name must be given as parameter
+        with self.assertRaises(MissingParameterError):
+            portal.get_vocabulary()
+
+        # Test getting a commonly available vocabulary
+        vocabulary = portal.get_vocabulary(name="plone.app.vocabularies.PortalTypes")
+        self.assertIsInstance(vocabulary, SimpleVocabulary)
+
+        # Test with invalid vocabulary name
+        with self.assertRaises(InvalidParameterError) as cm:
+            portal.get_vocabulary(name="non.existing.vocabulary")
+
+        expected_msg = (
+            "Cannot find a vocabulary with name 'non.existing.vocabulary'.\n"
+            "Available vocabularies are:\n"
+        )
+        self.assertTrue(str(cm.exception).startswith(expected_msg))
+
+        # Test with context
+        vocabulary_with_context = portal.get_vocabulary(
+            name="plone.app.vocabularies.PortalTypes", context=self.portal
+        )
+        self.assertIsInstance(vocabulary_with_context, SimpleVocabulary)
+
+    def test_get_vocabulary_names(self):
+        """Test getting list of vocabulary names."""
+        names = portal.get_vocabulary_names()
+
+        # Test we get a list of strings
+        self.assertIsInstance(names, list)
+        self.assertTrue(len(names) > 0)
+        self.assertIsInstance(names[0], str)
+
+        # Test that common vocabularies are included
+        common_vocabularies = [
+            "plone.app.vocabularies.PortalTypes",
+            "plone.app.vocabularies.WorkflowStates",
+            "plone.app.vocabularies.WorkflowTransitions",
+        ]
+
+        for vocabulary_name in common_vocabularies:
+            self.assertIn(vocabulary_name, names)
+
+    def test_vocabulary_terms(self):
+        """Test the actual content of retrieved vocabularies."""
+        # Get portal types vocabulary
+        types_vocabulary = portal.get_vocabulary("plone.app.vocabularies.PortalTypes")
+
+        # Check that we have some common content types
+        types = [term.value for term in types_vocabulary]
+        self.assertIn("Document", types)
+        self.assertIn("Folder", types)
+
+        # Get workflow states vocabulary
+        states_vocabulary = portal.get_vocabulary(
+            "plone.app.vocabularies.WorkflowStates"
+        )
+
+        # Check that we have some common workflow states
+        states = [term.value for term in states_vocabulary]
+        self.assertIn("private", states)
+        self.assertIn("published", states)

{plone_api-2.2.5 → plone_api-2.3.0}/src/plone.api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: plone.api
-Version: 2.2.5
+Version: 2.3.0
 Summary: A Plone API.
 Home-page: https://github.com/plone/plone.api
 Author: Plone Foundation
@@ -110,6 +110,25 @@ 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)
 ------------------
 

{plone_api-2.2.5 → plone_api-2.3.0}/src/plone.api.egg-info/SOURCES.txt

@@ -53,6 +53,7 @@ src/plone/api/tests/test_user.py
 src/plone/api/tests/test_validation.py
 src/plone/api/tests/doctests/about.md
 src/plone/api/tests/doctests/content.md
+src/plone/api/tests/doctests/contribute.md
 src/plone/api/tests/doctests/env.md
 src/plone/api/tests/doctests/group.md
 src/plone/api/tests/doctests/portal.md