Feature/port scheduling and magic entity resolution (#398)

* Add get_port and schedule_port functions

- Add get_port(identifier, identifier_type) for retrieving ports by ID or name
- Add schedule_port(port, scheduled) following schedule_processor pattern
- Register PortEntity in config.py for filter_obj support
- Add comprehensive tests for both functions

* fix(canvas): Set controller name in initial creation request

Previously create_controller() set the name in a separate update call
after creation, but returned the stale object from the initial call.
This caused component.name to show the type name instead of the custom
name.

Now sets name directly in the ControllerServiceDTO during creation,
matching the pattern used by create_processor(). Also defaults to
short type name if no name provided (e.g., 'JsonTreeReader').

* WIP: Add scheduling state consolidation utilities

Utilities implemented in nipyapi/utils.py:
- resolve_schedule_state(): Standardized bool/string to state normalization
- resolve_entity(): Entity resolution accepting ID, name, or object
  (to be used in next phase)

Scheduling functions consolidated in canvas.py:
- schedule_processor: Uses resolve_schedule_state()
- schedule_port: Uses resolve_schedule_state()
- schedule_controller: Uses resolve_schedule_state(), now accepts string
  states ('ENABLED', 'DISABLED') in addition to bool
- schedule_all_controllers: Same extension
- schedule_components: Now accepts string states ('RUNNING', 'STOPPED')

Breaking change: Invalid scheduled values now raise ValueError instead
of AssertionError. This is a more appropriate exception type.

Tests expanded for new string state acceptance in controller scheduling.
All 660 tests pass.

* feat: Add resolve_entity utility for consistent entity resolution across modules

- Add resolve_entity() and resolve_schedule_state() utilities in utils.py
- Refactor 17 canvas.py functions to accept object, ID, or name
- Refactor 9 versioning.py functions with consistent entity resolution
- Refactor 5 parameters.py functions with consistent entity resolution
- Add schedule_port() and get_port() functions to canvas.py
- Add greedy parameter to get_controller()
- Remove deprecated get_variable_registry/update_variable_registry
- Consolidate verification request pattern with _run_verification_request helper
- Make location optional in create_process_group and create_funnel
- Add PortEntity to registered_filters in config.py
- Optimize fix_state_flow fixture to module scope
- Update tests for new ValueError exceptions and expanded functionality

Closes #396

* Add Raises sections to entity resolution function docstrings

* docs: Clarify test comment about ValueError from resolve_entity validation (#399)

* Initial plan

* docs: Clarify test comment about ValueError from resolve_entity validation

Co-authored-by: Chaffelson <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: Chaffelson <[email protected]>

---------

Co-authored-by: Copilot <[email protected]>
Co-authored-by: Chaffelson <[email protected]>

Author: Chaffelson

nipyapi/canvas.py

@@ -69,6 +69,7 @@
     "UserEntity": {"identity": ["component", "identity"], "id": ["id"]},
     "TemplateEntity": {"id": ["id"], "name": ["template", "name"]},
     "ControllerServiceEntity": {"id": ["id"], "name": ["component", "name"]},
+    "PortEntity": {"id": ["id"], "name": ["status", "name"]},
     "ParameterContextEntity": {"id": ["id"], "name": ["component", "name"]},
     "ReportingTaskEntity": {"id": ["id"], "name": ["component", "name"]},
     # Git-based Flow Registry types (GitHub, GitLab, Bitbucket, Azure DevOps)

nipyapi/config.py

@@ -178,19 +178,34 @@ def _update_complete(context_id, request_id):
     return get_parameter_context(context.id, identifier_type="id")
 
 
-def delete_parameter_context(context, refresh=True):
+def delete_parameter_context(context, refresh=True, greedy=True, identifier_type="auto"):
     """
     Removes a Parameter Context
 
     Args:
-        context (ParameterContextEntity): Parameter Context to be deleted
+        context (ParameterContextEntity or str): Parameter Context to be deleted,
+            as a ParameterContextEntity object, context ID, or context name.
         refresh (bool): Whether to refresh the Context before Deletion
+        greedy (bool): For name lookup, True for partial match, False for exact.
+        identifier_type (str): How to interpret string identifier:
+            "auto" (default) detects UUID vs name, "id" or "name" to force.
 
     Returns:
         :class:`~nipyapi.nifi.models.ParameterContextEntity`: The removed Parameter Context
+
+    Raises:
+        TypeError: If context is not a string or ParameterContextEntity.
+        ValueError: If parameter context not found or multiple matches found.
     """
     enforce_min_ver("1.10.0")
-    assert isinstance(context, nipyapi.nifi.ParameterContextEntity)
+    context = nipyapi.utils.resolve_entity(
+        context,
+        get_parameter_context,
+        nipyapi.nifi.ParameterContextEntity,
+        strict=True,
+        greedy=greedy,
+        identifier_type=identifier_type,
+    )
     handle = nipyapi.nifi.ParameterContextsApi()
     if refresh:
         context = handle.get_parameter_context(context.id)
@@ -218,51 +233,102 @@ def prepare_parameter(name, value, description=None, sensitive=False):
     return out
 
 
-def delete_parameter_from_context(context, parameter_name):
+def delete_parameter_from_context(context, parameter_name, greedy=True, identifier_type="auto"):
     """
     Delete a specific Parameter from a Parameter Context
+
     Args:
-        context (ParameterContextEntity): The Parameter Context to Update
+        context (ParameterContextEntity or str): The Parameter Context to Update,
+            as a ParameterContextEntity object, context ID, or context name.
         parameter_name (str): The Parameter to delete
+        greedy (bool): For name lookup, True for partial match, False for exact.
+        identifier_type (str): How to interpret string identifier:
+            "auto" (default) detects UUID vs name, "id" or "name" to force.
 
     Returns:
         :class:`~nipyapi.nifi.models.ParameterContextEntity`: The updated Parameter Context
+
+    Raises:
+        TypeError: If context is not a string or ParameterContextEntity.
+        ValueError: If parameter context not found or multiple matches found.
     """
     enforce_min_ver("1.10.0")
+    context = nipyapi.utils.resolve_entity(
+        context,
+        get_parameter_context,
+        nipyapi.nifi.ParameterContextEntity,
+        strict=True,
+        greedy=greedy,
+        identifier_type=identifier_type,
+    )
     context.component.parameters = [ParameterEntity(parameter=ParameterDTO(name=parameter_name))]
     return update_parameter_context(context=context)
 
 
-def upsert_parameter_to_context(context, parameter):
+def upsert_parameter_to_context(context, parameter, greedy=True, identifier_type="auto"):
     """
     Insert or Update Parameter within a Parameter Context
 
     Args:
-        context (ParameterContextEntity): The Parameter Context to Modify
-        parameter(ParameterEntity): The ParameterEntity to insert or update
+        context (ParameterContextEntity or str): The Parameter Context to Modify,
+            as a ParameterContextEntity object, context ID, or context name.
+        parameter (ParameterEntity): The ParameterEntity to insert or update
+        greedy (bool): For name lookup, True for partial match, False for exact.
+        identifier_type (str): How to interpret string identifier:
+            "auto" (default) detects UUID vs name, "id" or "name" to force.
 
     Returns:
         :class:`~nipyapi.nifi.models.ParameterContextEntity`: The updated Parameter Context
+
+    Raises:
+        TypeError: If context is not a string or ParameterContextEntity.
+        ValueError: If parameter context not found or multiple matches found.
     """
     enforce_min_ver("1.10.0")
+    context = nipyapi.utils.resolve_entity(
+        context,
+        get_parameter_context,
+        nipyapi.nifi.ParameterContextEntity,
+        strict=True,
+        greedy=greedy,
+        identifier_type=identifier_type,
+    )
     context.component.parameters = [parameter]
     return update_parameter_context(context=context)
 
 
-def assign_context_to_process_group(pg, context_id, cascade=False):
+def assign_context_to_process_group(
+    pg, context_id, cascade=False, greedy=True, identifier_type="auto"
+):
     """
     Assigns a given Parameter Context to a specific Process Group
     Optionally cascades down to direct children Process Groups
 
     Args:
-        pg (ProcessGroupEntity): The Process Group to target
+        pg (ProcessGroupEntity or str): The Process Group to target,
+            as a ProcessGroupEntity object, process group ID, or name.
         context_id (str): The ID of the Parameter Context
         cascade (bool): Cascade Parameter Context down to child Process Groups?
+        greedy (bool): For name lookup, True for partial match, False for exact.
+        identifier_type (str): How to interpret string identifier:
+            "auto" (default) detects UUID vs name, "id" or "name" to force.
 
     Returns:
         :class:`~nipyapi.nifi.models.ProcessGroupEntity`: The updated Process Group
+
+    Raises:
+        TypeError: If pg is not a string or ProcessGroupEntity.
+        ValueError: If process group not found or multiple matches found.
     """
     assert isinstance(context_id, str)
+    pg = nipyapi.utils.resolve_entity(
+        pg,
+        nipyapi.canvas.get_process_group,
+        nipyapi.nifi.ProcessGroupEntity,
+        strict=True,
+        greedy=greedy,
+        identifier_type=identifier_type,
+    )
     if cascade:
         # Update the specified Process Group & all children
         child_pgs = nipyapi.canvas.list_all_process_groups(pg_id=pg.id)
@@ -275,16 +341,32 @@ def assign_context_to_process_group(pg, context_id, cascade=False):
     )
 
 
-def remove_context_from_process_group(pg):
+def remove_context_from_process_group(pg, greedy=True, identifier_type="auto"):
     """
     Clears any Parameter Context from the given Process Group
 
     Args:
-        pg (ProcessGroupEntity): The Process Group to target
+        pg (ProcessGroupEntity or str): The Process Group to target,
+            as a ProcessGroupEntity object, process group ID, or name.
+        greedy (bool): For name lookup, True for partial match, False for exact.
+        identifier_type (str): How to interpret string identifier:
+            "auto" (default) detects UUID vs name, "id" or "name" to force.
 
     Returns:
         :class:`~nipyapi.nifi.models.ProcessGroupEntity`: The updated Process Group
-    """
+
+    Raises:
+        TypeError: If pg is not a string or ProcessGroupEntity.
+        ValueError: If process group not found or multiple matches found.
+    """
+    pg = nipyapi.utils.resolve_entity(
+        pg,
+        nipyapi.canvas.get_process_group,
+        nipyapi.nifi.ProcessGroupEntity,
+        strict=True,
+        greedy=greedy,
+        identifier_type=identifier_type,
+    )
     return nipyapi.canvas.update_process_group(pg=pg, update={"parameter_context": {"id": None}})