Add get_package_share_path method

ament_index_python/ament_index_python/__init__.py

@@ -15,6 +15,7 @@
 from .constants import RESOURCE_INDEX_SUBFOLDER
 from .packages import get_package_prefix
 from .packages import get_package_share_directory
+from .packages import get_package_share_path
 from .packages import get_packages_with_prefixes
 from .packages import PackageNotFoundError
 from .resources import get_resource
@@ -26,6 +27,7 @@
 __all__ = [
     'get_package_prefix',
     'get_package_share_directory',
+    'get_package_share_path',
     'get_packages_with_prefixes',
     'get_resource',
     'get_resources',

ament_index_python/ament_index_python/packages.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 import os
+import pathlib
 
 from .resources import get_resource
 from .resources import get_resources
@@ -67,3 +68,20 @@ def get_package_share_directory(package_name):
     :raises: :exc:`PackageNotFoundError` if the package is not found
     """
     return os.path.join(get_package_prefix(package_name), 'share', package_name)
+
+
+def get_package_share_path(package_name):
+    """
+    Return the share directory of the given package as a pathlib.Path.
+
+    For example, if you install the package 'foo' into
+    '/home/user/ros2_ws/install' and you called this function with 'foo' as the
+    argument, then it will return a path representing '/home/user/ros2_ws/install/share/foo'
+    and then you could use it to construct the path to a shared file with
+    `get_package_share_path('foo') / 'urdf/robot.urdf'`
+
+    :param str package_name: name of the package to locate
+    :returns: share directory of the package as a pathlib.Path
+    :raises: :exc:`PackageNotFoundError` if the package is not found
+    """
+    return pathlib.Path(get_package_share_directory(package_name))

ament_index_python/test/test_ament_index_python.py

@@ -17,6 +17,7 @@
 
 from ament_index_python import get_package_prefix
 from ament_index_python import get_package_share_directory
+from ament_index_python import get_package_share_path
 from ament_index_python import get_packages_with_prefixes
 from ament_index_python import get_resource
 from ament_index_python import get_resource_types
@@ -166,6 +167,25 @@ def get_package_share_directory_test(package_name, expect_prefix):
         get_package_share_directory('does_not_exist')
 
 
+def test_get_package_share_path():
+    set_ament_prefix_path(['prefix1', 'prefix2'])
+
+    def get_package_share_path_test(package_name, expect_prefix):
+        my_path = get_package_share_path(package_name)
+        assert len(my_path.parts) >= 3
+        assert my_path.parts[-1] == package_name, f"Expected package name '{package_name}'"
+        assert my_path.parts[-2] == 'share', "Expected 'share'"
+        assert my_path.parts[-3] == expect_prefix, f"Expected '{expect_prefix}'"
+
+    get_package_share_path_test('foo', 'prefix1')
+    # found in both prefix1 and prefix2, but prefix1 is ahead on the APP
+    get_package_share_path_test('bar', 'prefix1')
+    get_package_share_path_test('baz', 'prefix2')
+
+    with pytest.raises(PackageNotFoundError):
+        get_package_share_path('does_not_exist')
+
+
 def test_get_resource_types():
     set_ament_prefix_path([])
     with pytest.raises(EnvironmentError):