Adding change log and function comments

CHANGES.rst

@@ -7,7 +7,14 @@ Changes
 `Unreleased <https://github.com/Ouranosinc/cowbird/tree/master>`_ (latest)
 ------------------------------------------------------------------------------------
 
-* Nothing yet.
+* Add optional key ``field`` and ``regex`` to be used in the ``sync_permissions`` section found in the config.
+  This allow to sync permission using a field other than ``resource_full_name`` when creating the nametype path
+  from the segment ``ex.: /field1::type1/field2::type2``. This adds the support of using ``resource_display_name``.
+* The ``regex`` is used to extract the desired information from the ``nametype_path`` that should be used to do an
+  exact match. This new search overrides the default way of matching each segment with the ``nametype path``. 
+  In the case where a ``regex`` is found in the target segment, the data will be formed using the same ``resource_type``
+  for every match in the same segment. Similary, as using ``- name: "**"`` in the config to match multiple segment,
+  it is possible to use a ``regex`` to match multiple directory in the same segment with ``regex: '(?<=:).*\/?(?=\/)' ``
 
 `2.1.0 <https://github.com/Ouranosinc/cowbird/tree/2.1.0>`_ (2023-09-18)
 ------------------------------------------------------------------------------------

cowbird/permissions_synchronizer.py

@@ -212,7 +212,10 @@ def _generate_regex_from_segments(res_segments: List[ConfigSegment]) -> Tuple[st
     @staticmethod
     def _generate_nametype_path_from_segments(res_segments: List[ConfigSegment], src_resource_tree: ResourceTree) -> str:
         """
-        Generate nametype path (ex.: /name1::type1/name2::type2 where name can be a key from src_resource_tree ).
+        Generate nametype path (ex.: /name1::type1/name2::type2 where name can be a field found in ResourceSegment).
+
+        :param res_segments: list of segments
+        :param src_resource_tree: Resource tree associated with the permission to synchronize
         """
         resource_nametype_path = ""
         index = 0
@@ -244,8 +247,7 @@ def _find_matching_res(self, permission: Permission, src_resource_tree: Resource
         segment is ignored in the length.
 
         :param permission: Permission of the service associated with the input resource.
-        :param resource_nametype_path: Full resource path name, which includes the type of each segment
-                                       (ex.: /name1::type1/name2::type2)
+        :param ResourceTree: Resource tree associated with the permission to synchronize
         """
 
         service_type = permission.service_type
@@ -267,6 +269,15 @@ def _find_matching_res(self, permission: Permission, src_resource_tree: Resource
             # An error would be raised because 2 matches of the same length would be found.
             # - /**/file
             # - /file
+            #
+            # In the case where a regex is used, the behavior is changed to search for the exact match in the res_segments.
+            # The lengh of the match is used to favor a more specific match.
+            # Example:
+            # 1:
+            # - //dir1/dir2//
+            # - //dir1/dir2//dir3// # We favor this path if it matches since it is more specific.
+            # note: It is possible to have multiple dir in the same segment when using a custom regex that extract a display_name
+            # containing a path to a target resource.
 
             matched_length_by_res = {}
             matched_groups_by_res = {}
@@ -312,6 +323,8 @@ def _create_res_data(target_segments: List[ConfigSegment],
         """
         Creates resource data, by replacing any tokens found in the segment names to their actual corresponding values.
         This data includes the name and type of each segments of a full resource path.
+        In the case where a regex is found in the target segment, the data will be formed using the same resource_type
+        for every match in the current segment.
 
         :param target_segments: List containing the name and type info of each segment of the target resource path.
         :param input_matched_groups:

cowbird/typedefs.py

@@ -147,7 +147,7 @@
     Dict[
         str,
         # FIXME: replace by a more specific type provided by Magpie directly if eventually implemented
-        #   Only partial fields are provided below (resource_name/resource_type),
+        #   Only partial fields are provided below (resource_name/resource_type/resource_display_name),
         #   because those are the only ones used for now in Cowbird's sync operation.
         #   This actually contains more details such as the resource ID, permission names, etc.
         #   (see the response body of 'GET /magpie/resources/{resource_id}' for exact content).