From b3cafb17f3893990a451265263b631528d0ae80f Mon Sep 17 00:00:00 2001 From: Naren Date: Thu, 24 Sep 2026 16:07:56 +0530 Subject: [PATCH] docs: render docstring cross-references as Markdown, not Sphinx RST The docs site renders docstrings through mkdocstrings with the Google parser, which treats docstring bodies as Markdown. Sphinx roles such as `:class:`Foo`` and `:meth:`bar`` therefore leaked through verbatim onto the published API pages (e.g. /core/entities/), as did the RST literal- block marker `::` and the `.. warning::` / `.. code-block::` directives. Convert them to their Markdown/Google equivalents across all three packages' sources: - `:class:`/`:data:`/`:attr:`/`:mod:` -> inline code span; `~`-prefixed targets keep only the last component, matching Sphinx's rendering. - `:meth:`/`:func:` -> inline code span with `()`, matching Sphinx's default `add_function_parentheses`. - Trailing `::` -> `:` (the indented block already renders as a code block in Markdown; only the stray colon was visible). - `.. warning::` -> a Google `Warning:` section, which griffe parses as an admonition. - `.. code-block:: python` and the `Example::` blocks that ruff's D412 would then flag -> fenced ```python blocks. - The two stray `:param:`/`:return:` fields in `EntityRecord.from_data` -> Google-style `Args:`/`Returns:`. Docstring text only; no behavior changes. `ruff check` and `ruff format --check` pass on every touched file. Co-Authored-By: Claude Opus 5 (1M context) --- .../src/uipath/core/adapters/__init__.py | 2 +- .../src/uipath/core/adapters/evaluator.py | 6 +- .../core/feature_flags/feature_flags.py | 10 +- .../src/uipath/core/governance/__init__.py | 2 +- .../src/uipath/core/governance/config.py | 6 +- .../src/uipath/core/governance/exceptions.py | 12 +- .../src/uipath/core/governance/models.py | 6 +- .../src/uipath/core/governance/providers.py | 12 +- .../platform/action_center/_tasks_service.py | 2 +- .../platform/agenthub/_remote_a2a_service.py | 12 +- .../uipath/platform/agenthub/remote_a2a.py | 4 +- .../uipath/platform/common/_base_service.py | 8 +- .../platform/common/_execution_context.py | 4 +- .../platform/common/_reference_context.py | 14 +- .../platform/entities/_entities_service.py | 270 +++++++++--------- .../platform/entities/_entity_data_service.py | 76 ++--- .../entities/_entity_ontology_service.py | 6 +- .../entities/_entity_schema_service.py | 44 +-- .../src/uipath/platform/entities/entities.py | 21 +- .../platform/errors/_datafabric_error.py | 10 +- .../governance/_governance_provider.py | 26 +- .../governance/_governance_service.py | 58 ++-- .../_live_track_event_dispatcher.py | 26 +- .../uipath/platform/governance/compensate.py | 2 +- .../src/uipath/platform/governance/policy.py | 2 +- .../guardrails/decorators/_actions.py | 6 +- .../platform/guardrails/decorators/_core.py | 12 +- .../guardrails/decorators/_guardrail.py | 8 +- .../platform/guardrails/decorators/_models.py | 2 +- .../guardrails/decorators/_registry.py | 8 +- .../guardrails/decorators/validators/_base.py | 34 +-- .../guardrails/decorators/validators/byo.py | 9 +- .../decorators/validators/custom.py | 10 +- .../decorators/validators/harmful_content.py | 6 +- .../validators/intellectual_property.py | 4 +- .../decorators/validators/llm_as_judge.py | 4 +- .../guardrails/decorators/validators/pii.py | 6 +- .../decorators/validators/prompt_injection.py | 4 +- .../validators/user_prompt_attacks.py | 4 +- .../platform/orchestrator/_assets_service.py | 2 +- .../src/uipath/_cli/_governance/__init__.py | 8 +- .../src/uipath/_cli/_governance/yaml_index.py | 16 +- .../src/uipath/_cli/_governance_bootstrap.py | 8 +- .../uipath/src/uipath/agent/models/agent.py | 2 +- .../eval/evaluators/base_dataset_evaluator.py | 2 +- .../evaluators/dataset_evaluator_factory.py | 8 +- .../uipath/src/uipath/eval/runtime/runtime.py | 2 +- packages/uipath/src/uipath/functions/debug.py | 2 +- .../uipath/src/uipath/functions/factory.py | 2 +- 49 files changed, 408 insertions(+), 402 deletions(-) diff --git a/packages/uipath-core/src/uipath/core/adapters/__init__.py b/packages/uipath-core/src/uipath/core/adapters/__init__.py index c3675b404..1ea8a8fe0 100644 --- a/packages/uipath-core/src/uipath/core/adapters/__init__.py +++ b/packages/uipath-core/src/uipath/core/adapters/__init__.py @@ -9,7 +9,7 @@ Public surface: -- :class:`EvaluatorProtocol` – structural protocol the framework +- `EvaluatorProtocol` – structural protocol the framework plugin expects from any policy evaluator. """ diff --git a/packages/uipath-core/src/uipath/core/adapters/evaluator.py b/packages/uipath-core/src/uipath/core/adapters/evaluator.py index 4f25097c5..ddbbfca3d 100644 --- a/packages/uipath-core/src/uipath/core/adapters/evaluator.py +++ b/packages/uipath-core/src/uipath/core/adapters/evaluator.py @@ -6,7 +6,7 @@ ``uipath-core`` — plugins depend only on this structural protocol so they can be swapped against any of them without code change. -``EvaluatorProtocol`` is a :class:`typing.Protocol` so any class whose +``EvaluatorProtocol`` is a `typing.Protocol` so any class whose methods match the signatures below satisfies the contract without inheritance. """ @@ -22,9 +22,9 @@ class EvaluatorProtocol(Protocol): """Structural protocol a framework plugin expects from a policy evaluator. - Every ``evaluate_*`` method returns an :class:`AuditRecord` — the + Every ``evaluate_*`` method returns an `AuditRecord` — the per-hook audit envelope holding the per-rule - :class:`RuleEvaluation` list, the final action, and the trace / + `RuleEvaluation` list, the final action, and the trace / agent metadata. Callers get a typed result; no downcasting is required. """ diff --git a/packages/uipath-core/src/uipath/core/feature_flags/feature_flags.py b/packages/uipath-core/src/uipath/core/feature_flags/feature_flags.py index f40126916..b7e7d4a54 100644 --- a/packages/uipath-core/src/uipath/core/feature_flags/feature_flags.py +++ b/packages/uipath-core/src/uipath/core/feature_flags/feature_flags.py @@ -1,13 +1,13 @@ """Feature flags configuration for UiPath SDK. A simple, local-only feature flag registry. Flags can be set -programmatically via :meth:`FeatureFlagsManager.configure_flags` or +programmatically via `FeatureFlagsManager.configure_flags()` or supplied via environment variables named ``UIPATH_FEATURE_`` when nothing has been configured programmatically. Programmatic values always take precedence over environment variables. -Example usage:: +Example usage: from uipath.core.feature_flags import FeatureFlags @@ -58,7 +58,7 @@ def _parse_env_value(raw: str) -> Any: class FeatureFlagsManager: """Singleton registry for UiPath feature flags. - Use the module-level :data:`FeatureFlags` instance rather than + Use the module-level `FeatureFlags` instance rather than instantiating this class directly. """ @@ -90,7 +90,7 @@ def get_flag(self, name: str, *, default: Any = None) -> Any: Resolution order: - 1. Value set via :meth:`configure_flags` (highest priority) + 1. Value set via `configure_flags()` (highest priority) 2. ``UIPATH_FEATURE_`` environment variable (fallback when nothing configured) 3. *default* @@ -108,7 +108,7 @@ def get_flag(self, name: str, *, default: Any = None) -> Any: def is_flag_enabled(self, name: str, *, default: bool = False) -> bool: """Check whether a boolean flag is enabled. - Uses the same resolution order as :meth:`get_flag`. + Uses the same resolution order as `get_flag()`. Args: name: The feature flag name. diff --git a/packages/uipath-core/src/uipath/core/governance/__init__.py b/packages/uipath-core/src/uipath/core/governance/__init__.py index 4bf855b82..f87866f8d 100644 --- a/packages/uipath-core/src/uipath/core/governance/__init__.py +++ b/packages/uipath-core/src/uipath/core/governance/__init__.py @@ -2,7 +2,7 @@ Evaluator-agnostic types every governance consumer references — the runtime layer, adapter packages, and customer code that catches -:class:`GovernanceBlockException`. The full runtime / audit / +`GovernanceBlockException`. The full runtime / audit / native-evaluator implementation lives outside this package; this core surface is just the contracts. """ diff --git a/packages/uipath-core/src/uipath/core/governance/config.py b/packages/uipath-core/src/uipath/core/governance/config.py index cbcbd577a..4f000e6e5 100644 --- a/packages/uipath-core/src/uipath/core/governance/config.py +++ b/packages/uipath-core/src/uipath/core/governance/config.py @@ -2,8 +2,8 @@ Process-level feature-flag gate that decides whether the Python governance checker runs at all. The -:class:`uipath.core.governance.EnforcementMode` value type is defined -in :mod:`uipath.core.governance.models`; the per-policy runtime state +`uipath.core.governance.EnforcementMode` value type is defined +in `uipath.core.governance.models`; the per-policy runtime state that selects a mode (backend-supplied via the ``/runtime/policy`` client) lives outside this package. """ @@ -29,7 +29,7 @@ def is_governance_enabled() -> bool: Resolution order: - 1. :meth:`uipath.core.feature_flags.FeatureFlagsManager.is_flag_enabled` - + 1. `uipath.core.feature_flags.FeatureFlagsManager.is_flag_enabled()` - the in-process programmatic registry (typically populated from gitops) and its own ``UIPATH_FEATURE_`` env-var fallback. 2. Default ``False`` (governance disabled). diff --git a/packages/uipath-core/src/uipath/core/governance/exceptions.py b/packages/uipath-core/src/uipath/core/governance/exceptions.py index 48f4b178a..e6e5cbf18 100644 --- a/packages/uipath-core/src/uipath/core/governance/exceptions.py +++ b/packages/uipath-core/src/uipath/core/governance/exceptions.py @@ -41,8 +41,8 @@ class GovernanceBlockException(Exception): This exception indicates that the AI agent's operation was blocked by a configured governance policy, not an unexpected system error. - Prefer the classmethod constructors (:meth:`from_violation`, - :meth:`from_audit_record`) when you have structured context — the + Prefer the classmethod constructors (`from_violation()`, + `from_audit_record()`) when you have structured context — the default constructor is for raw-message use only. """ @@ -60,8 +60,8 @@ def __init__( ) -> None: """Construct from a pre-formatted message and optional structured context. - Most callers should use :meth:`from_violation` or - :meth:`from_audit_record` instead of passing structured context + Most callers should use `from_violation()` or + `from_audit_record()` instead of passing structured context directly. """ self.violation = violation @@ -76,7 +76,7 @@ def __init__( def from_violation( cls, violation: GovernanceViolation ) -> "GovernanceBlockException": - """Build from a structured :class:`GovernanceViolation`.""" + """Build from a structured `GovernanceViolation`.""" return cls( message=_format_violation_message( violation.rule_id, violation.rule_name, violation.detail @@ -88,7 +88,7 @@ def from_violation( @classmethod def from_audit_record(cls, audit_record: AuditRecord) -> "GovernanceBlockException": - """Build from an :class:`AuditRecord` — first matched rule wins.""" + """Build from an `AuditRecord` — first matched rule wins.""" matched_rules = [e for e in audit_record.evaluations if e.matched] if matched_rules: rule = matched_rules[0] diff --git a/packages/uipath-core/src/uipath/core/governance/models.py b/packages/uipath-core/src/uipath/core/governance/models.py index 29dccc121..9678d4744 100644 --- a/packages/uipath-core/src/uipath/core/governance/models.py +++ b/packages/uipath-core/src/uipath/core/governance/models.py @@ -4,11 +4,11 @@ (``Rule``/``Check``/``Condition``) so adapter packages don't inherit the native policy model: -- **Output types** (:class:`Action`, :class:`LifecycleHook`, - :class:`RuleEvaluation`, :class:`AuditRecord`) — cross the adapter +- **Output types** (`Action`, `LifecycleHook`, + `RuleEvaluation`, `AuditRecord`) — cross the adapter boundary at evaluation time: every evaluator implementation (native, AGT, composite, …) produces them, and every adapter consumes them. -- **Configuration value types** (:class:`EnforcementMode`) — describe +- **Configuration value types** (`EnforcementMode`) — describe governance configuration shared by core and its consumers. The per-policy runtime state that selects a mode lives outside this package; only the value type lives here. diff --git a/packages/uipath-core/src/uipath/core/governance/providers.py b/packages/uipath-core/src/uipath/core/governance/providers.py index 5435ad389..ff2a679be 100644 --- a/packages/uipath-core/src/uipath/core/governance/providers.py +++ b/packages/uipath-core/src/uipath/core/governance/providers.py @@ -8,7 +8,7 @@ centralised guardrail and write the per-rule LLMOps audit records. Both have wire formats owned by the ``agenticgovernance_`` ingress. -Defining the contracts here — alongside :class:`EvaluatorProtocol` — +Defining the contracts here — alongside `EvaluatorProtocol` — lets runtime consumers depend on stable protocols and receive a concrete provider via constructor injection. Concrete providers live outside this package; ``uipath-core`` does not import them. @@ -32,9 +32,9 @@ class PolicyContext(BaseModel): Wrapping the selectors in a model keeps the protocol surface stable when the server grows new selector dimensions — adding a field here - doesn't change :meth:`GovernancePolicyProvider.get_policy`. + doesn't change `GovernancePolicyProvider.get_policy()`. - Today carries only :attr:`is_conversational`; future selectors land + Today carries only `is_conversational`; future selectors land here. """ @@ -46,7 +46,7 @@ class PolicyContext(BaseModel): class PolicyResponse(BaseModel): """Parsed governance backend response. - Wire envelope:: + Wire envelope: { "mode": "audit" | "enforce" | "disabled", @@ -150,7 +150,7 @@ class GovernancePolicyProvider(Protocol): variant is the preferred entry point for hosts running on an event loop (the host can overlap policy fetch with the rest of agent setup via ``asyncio.create_task`` and ``await`` the resolved - :class:`PolicyResponse` before constructing the governance + `PolicyResponse` before constructing the governance wrapper). The sync variant is kept for callers outside an event loop (CLI tools, integration tests). @@ -164,7 +164,7 @@ def get_policy(self, context: PolicyContext) -> PolicyResponse: ... async def get_policy_async(self, context: PolicyContext) -> PolicyResponse: - """Async variant of :meth:`get_policy`. + """Async variant of `get_policy()`. Hosts running on an event loop should use this so the fetch doesn't block the loop and can overlap with other startup diff --git a/packages/uipath-platform/src/uipath/platform/action_center/_tasks_service.py b/packages/uipath-platform/src/uipath/platform/action_center/_tasks_service.py index 50bca7d4c..36e2a012e 100644 --- a/packages/uipath-platform/src/uipath/platform/action_center/_tasks_service.py +++ b/packages/uipath-platform/src/uipath/platform/action_center/_tasks_service.py @@ -797,7 +797,7 @@ def create_quickform( ) -> Task: """Create a new QuickForm task synchronously. - See :meth:`create_quickform_async` for parameter docs. + See `create_quickform_async()` for parameter docs. """ spec = _create_quickform_spec( title=title, diff --git a/packages/uipath-platform/src/uipath/platform/agenthub/_remote_a2a_service.py b/packages/uipath-platform/src/uipath/platform/agenthub/_remote_a2a_service.py index 037f4ff7d..d251340cb 100644 --- a/packages/uipath-platform/src/uipath/platform/agenthub/_remote_a2a_service.py +++ b/packages/uipath-platform/src/uipath/platform/agenthub/_remote_a2a_service.py @@ -1,6 +1,6 @@ """Service for managing Remote A2A agents in UiPath AgentHub. -.. warning:: +Warning: This module is experimental and subject to change. The Remote A2A feature is in preview and its API may change in future releases. """ @@ -23,7 +23,7 @@ class RemoteA2aService(FolderContext, BaseService): """Service for managing Remote A2A agents in UiPath AgentHub. - .. warning:: + Warning: This service is experimental and subject to change. """ @@ -46,7 +46,7 @@ def list( ) -> List[RemoteA2aAgent]: """List Remote A2A agents. - .. warning:: + Warning: This method is experimental and subject to change. When called without folder_path, returns all agents across @@ -106,7 +106,7 @@ async def list_async( ) -> List[RemoteA2aAgent]: """Asynchronously list Remote A2A agents. - .. warning:: + Warning: This method is experimental and subject to change. Args: @@ -163,7 +163,7 @@ def retrieve( ) -> RemoteA2aAgent: """Retrieve a Remote A2A agent by its display name or legacy slug. - .. warning:: + Warning: This method is experimental and subject to change. Args: @@ -209,7 +209,7 @@ async def retrieve_async( ) -> RemoteA2aAgent: """Asynchronously retrieve a Remote A2A agent by display name or legacy slug. - .. warning:: + Warning: This method is experimental and subject to change. Args: diff --git a/packages/uipath-platform/src/uipath/platform/agenthub/remote_a2a.py b/packages/uipath-platform/src/uipath/platform/agenthub/remote_a2a.py index c81a7f4b2..41e1766a6 100644 --- a/packages/uipath-platform/src/uipath/platform/agenthub/remote_a2a.py +++ b/packages/uipath-platform/src/uipath/platform/agenthub/remote_a2a.py @@ -1,6 +1,6 @@ """Models for Remote A2A Agents in UiPath AgentHub. -.. warning:: +Warning: This module is experimental and subject to change. The Remote A2A feature is in preview and its API may change in future releases. """ @@ -31,7 +31,7 @@ class RemoteA2aAgentFolder(BaseModel): class RemoteA2aAgent(BaseModel): """Model representing a Remote A2A agent in UiPath AgentHub. - .. warning:: + Warning: This model is experimental and subject to change. """ diff --git a/packages/uipath-platform/src/uipath/platform/common/_base_service.py b/packages/uipath-platform/src/uipath/platform/common/_base_service.py index 8db2a51d1..756c2be67 100644 --- a/packages/uipath-platform/src/uipath/platform/common/_base_service.py +++ b/packages/uipath-platform/src/uipath/platform/common/_base_service.py @@ -71,7 +71,7 @@ def _get_caller_component() -> str: def resolve_trace_id(fallback: str | None = None) -> str | None: """Resolve the current UiPath trace id as a 32-char hex string. - Same lookup chain :func:`_inject_trace_context` uses to compose the + Same lookup chain `_inject_trace_context()` uses to compose the ``x-uipath-traceparent-id`` header, exposed as a public helper so callers can capture the value when they need it in a request body (e.g. governance compensation) or before hopping to a background @@ -79,11 +79,11 @@ def resolve_trace_id(fallback: str | None = None) -> str | None: Resolution order (first hit wins): - 1. :attr:`UiPathConfig.trace_id` (``UIPATH_TRACE_ID`` env var), - normalized via :meth:`_SpanUtils.normalize_trace_id`. This is the + 1. `UiPathConfig.trace_id` (``UIPATH_TRACE_ID`` env var), + normalized via `_SpanUtils.normalize_trace_id()`. This is the canonical agent trace id the LLMOps exporter binds spans to. 2. The LLMOps external span trace id, when a provider is registered - via :meth:`UiPathSpanUtils.register_current_span_provider`. + via `UiPathSpanUtils.register_current_span_provider()`. 3. The current OpenTelemetry span trace id. 4. The caller-supplied ``fallback``. diff --git a/packages/uipath-platform/src/uipath/platform/common/_execution_context.py b/packages/uipath-platform/src/uipath/platform/common/_execution_context.py index 4106afc1e..84306b195 100644 --- a/packages/uipath-platform/src/uipath/platform/common/_execution_context.py +++ b/packages/uipath-platform/src/uipath/platform/common/_execution_context.py @@ -13,7 +13,7 @@ class ExecutionSourceContext: variable and releases it on exit so it stays correctly scoped in concurrent runs. The CLI enters this with ``UiPathRuntimeContext.execution_source`` so platform clients can read it via - :attr:`UiPathExecutionContext.execution_source`. + `UiPathExecutionContext.execution_source`. """ def __init__(self, execution_source: str | None) -> None: @@ -110,6 +110,6 @@ def execution_source(self) -> str | None: Identifies the run context (e.g. ``runtime``/``playground``/``eval``), derived from the CLI command and carried via - :class:`ExecutionSourceContext`. Returns ``None`` when not set. + `ExecutionSourceContext`. Returns ``None`` when not set. """ return _execution_source.get() diff --git a/packages/uipath-platform/src/uipath/platform/common/_reference_context.py b/packages/uipath-platform/src/uipath/platform/common/_reference_context.py index 648d25e69..b1023cfbc 100644 --- a/packages/uipath-platform/src/uipath/platform/common/_reference_context.py +++ b/packages/uipath-platform/src/uipath/platform/common/_reference_context.py @@ -51,7 +51,7 @@ class ReferenceContext: Each mutating call returns a new instance — the original is never modified, preventing sibling spans from sharing context. - Usage:: + Usage: ctx = ReferenceContext.Empty ctx = ctx.add("maestro", process_id, "2.1.0") @@ -105,7 +105,7 @@ def add( version: Optional version string. Returns: - A new :class:`ReferenceContext` with the entry appended. + A new `ReferenceContext` with the entry appended. """ if not service_type or not service_type.strip(): raise ValueError("service_type must be a non-empty string.") @@ -158,7 +158,7 @@ def from_baggage_header(header_value: Optional[str]) -> "ReferenceContext": ``"ref.type=agent;ref.id=;ref.v=1.0,ref.type=maestro;ref.id="`` Returns: - Parsed :class:`ReferenceContext`, or :attr:`ReferenceContext.Empty` + Parsed `ReferenceContext`, or `ReferenceContext.Empty` if the header is absent, empty, or contains no valid ref entries. """ if not header_value or not header_value.strip(): @@ -225,12 +225,12 @@ def to_baggage_header_value(self) -> str: class ReferenceContextAccessor: - """Ambient accessor for the current :class:`ReferenceContext`. + """Ambient accessor for the current `ReferenceContext`. - Backed by :mod:`contextvars` so the value propagates across ``await`` + Backed by `contextvars` so the value propagates across ``await`` boundaries without being threaded through every call signature. - Usage:: + Usage: token = ReferenceContextAccessor.set(ctx) try: @@ -254,7 +254,7 @@ def set( ) -> contextvars.Token[Optional[ReferenceContext]]: """Set the ambient context. Returns a token for restoration. - Pass the token to :meth:`reset` in a ``finally`` block. + Pass the token to `reset()` in a ``finally`` block. """ return cls._current.set(value) diff --git a/packages/uipath-platform/src/uipath/platform/entities/_entities_service.py b/packages/uipath-platform/src/uipath/platform/entities/_entities_service.py index 147aae78f..7e697a55c 100644 --- a/packages/uipath-platform/src/uipath/platform/entities/_entities_service.py +++ b/packages/uipath-platform/src/uipath/platform/entities/_entities_service.py @@ -1,12 +1,12 @@ """Public facade for the Data Fabric entities surface. -:class:`EntitiesService` keeps the existing ``sdk.entities.*`` API flat and +`EntitiesService` keeps the existing ``sdk.entities.*`` API flat and unchanged from a caller's perspective while delegating each operation to the appropriate underlying service: -* :class:`EntitySchemaService` — entity definitions, choice set listings, +* `EntitySchemaService` — entity definitions, choice set listings, create / delete / update-metadata lifecycle. -* :class:`EntityDataService` — record CRUD (single and batch), structured +* `EntityDataService` — record CRUD (single and batch), structured queries, attachments, choice-set values, bulk import, and federated SQL queries. @@ -147,14 +147,14 @@ def retrieve(self, entity_key: str) -> Entity: - storage_size_in_mb: Storage size used by the entity Examples: - Basic usage:: + Basic usage: # Retrieve entity metadata entity = entities_service.retrieve("a1b2c3d4-e5f6-7890-abcd-ef1234567890") print(f"Entity: {entity.display_name}") print(f"Records: {entity.record_count}") - Inspecting entity fields:: + Inspecting entity fields: entity = entities_service.retrieve("a1b2c3d4-e5f6-7890-abcd-ef1234567890") @@ -171,7 +171,7 @@ def retrieve_v3(self, entity_key: str) -> Entity: """Retrieve an entity by key via the v3 API. Experimental v3 surface (serves Federated entities); see - :meth:`retrieve` for parameter and return details. + `retrieve()` for parameter and return details. """ return self._schema.retrieve(entity_key, use_v3=True) @@ -194,14 +194,14 @@ async def retrieve_async(self, entity_key: str) -> Entity: - storage_size_in_mb: Storage size used by the entity Examples: - Basic usage:: + Basic usage: # Retrieve entity metadata entity = await entities_service.retrieve_async("a1b2c3d4-e5f6-7890-abcd-ef1234567890") print(f"Entity: {entity.display_name}") print(f"Records: {entity.record_count}") - Inspecting entity fields:: + Inspecting entity fields: entity = await entities_service.retrieve_async("a1b2c3d4-e5f6-7890-abcd-ef1234567890") @@ -215,7 +215,7 @@ async def retrieve_async(self, entity_key: str) -> Entity: @traced(name="entity_retrieve_v3", run_type="uipath") async def retrieve_v3_async(self, entity_key: str) -> Entity: - """Async variant of :meth:`retrieve_v3`.""" + """Async variant of `retrieve_v3()`.""" return await self._schema.retrieve_async(entity_key, use_v3=True) @deprecated( @@ -244,7 +244,7 @@ def retrieve_by_name_v3( """Retrieve an entity by name via the v3 API. Experimental v3 surface (serves Federated entities); see - :meth:`retrieve_by_name` for parameter and return details. + `retrieve_by_name()` for parameter and return details. """ return self._schema.retrieve_by_name( entity_name, folder_key=folder_key, use_v3=True @@ -275,7 +275,7 @@ async def retrieve_by_name_async( async def retrieve_by_name_v3_async( self, entity_name: str, folder_key: Optional[str] = None ) -> Entity: - """Async variant of :meth:`retrieve_by_name_v3`.""" + """Async variant of `retrieve_by_name_v3()`.""" return await self._schema.retrieve_by_name_async( entity_name, folder_key=folder_key, use_v3=True ) @@ -292,14 +292,14 @@ def list_entities(self) -> List[Entity]: Each entity includes name, display name, fields, record count, and storage information. Examples: - List all entities:: + List all entities: # Get all entities in the Data Service entities = entities_service.list_entities() for entity in entities: print(f"{entity.display_name} ({entity.name})") - Find entities with RBAC enabled:: + Find entities with RBAC enabled: entities = entities_service.list_entities() @@ -309,7 +309,7 @@ def list_entities(self) -> List[Entity]: if e.is_rbac_enabled ] - Summary report:: + Summary report: entities = entities_service.list_entities() @@ -327,7 +327,7 @@ def list_entities_v3(self) -> List[Entity]: """List all entities via the v3 API. Experimental v3 surface (serves Federated entities); see - :meth:`list_entities` for parameter and return details. + `list_entities()` for parameter and return details. """ return self._schema.list_entities(use_v3=True) @@ -343,14 +343,14 @@ async def list_entities_async(self) -> List[Entity]: Each entity includes name, display name, fields, record count, and storage information. Examples: - List all entities:: + List all entities: # Get all entities in the Data Service entities = await entities_service.list_entities_async() for entity in entities: print(f"{entity.display_name} ({entity.name})") - Find entities with RBAC enabled:: + Find entities with RBAC enabled: entities = await entities_service.list_entities_async() @@ -360,7 +360,7 @@ async def list_entities_async(self) -> List[Entity]: if e.is_rbac_enabled ] - Summary report:: + Summary report: entities = await entities_service.list_entities_async() @@ -375,7 +375,7 @@ async def list_entities_async(self) -> List[Entity]: @traced(name="list_entities_v3", run_type="uipath") async def list_entities_v3_async(self) -> List[Entity]: - """Async variant of :meth:`list_entities_v3`.""" + """Async variant of `list_entities_v3()`.""" return await self._schema.list_entities_async(use_v3=True) @traced(name="list_choicesets", run_type="uipath") @@ -386,7 +386,7 @@ def list_choicesets(self) -> List[Entity]: List[Entity]: A list of all choice set entities. Examples: - List all choice sets:: + List all choice sets: choicesets = entities_service.list_choicesets() for cs in choicesets: @@ -436,7 +436,7 @@ def create_entity( type or is out of range. Examples: - Create a simple entity:: + Create a simple entity: from uipath.platform.entities import ( EntityCreateFieldOptions, @@ -478,7 +478,7 @@ def create_entity_v3( """Create an entity via the v3 API (supports Federated entities). Experimental v3 surface (serves Federated entities); see - :meth:`create_entity` for parameter and return details. + `create_entity()` for parameter and return details. """ return self._schema.create_entity(name, fields, options, use_v3=True) @@ -495,7 +495,7 @@ async def create_entity_async( """Asynchronously create a new entity with the given schema. Args: - name (str): Entity name; same validation rules as :meth:`create_entity`. + name (str): Entity name; same validation rules as `create_entity()`. fields (List[EntityCreateFieldOptions]): Field definitions. options (Optional[EntityCreateOptions]): Optional entity-level settings. @@ -506,7 +506,7 @@ async def create_entity_async( ValueError: For client-side validation failures. Examples: - Create a simple entity:: + Create a simple entity: from uipath.platform.entities import ( EntityCreateFieldOptions, @@ -533,7 +533,7 @@ async def create_entity_v3_async( fields: List[EntityCreateFieldOptions], options: Optional[EntityCreateOptions] = None, ) -> str: - """Async variant of :meth:`create_entity_v3`.""" + """Async variant of `create_entity_v3()`.""" return await self._schema.create_entity_async( name, fields, options, use_v3=True ) @@ -549,7 +549,7 @@ def delete_entity(self, entity_id: str) -> None: entity_id (str): The unique identifier of the entity to delete. Examples: - Delete an entity by id:: + Delete an entity by id: entities_service.delete_entity("a1b2c3d4-...") """ @@ -560,7 +560,7 @@ def delete_entity_v3(self, entity_id: str) -> None: """Delete an entity via the v3 API. Experimental v3 surface (serves Federated entities); see - :meth:`delete_entity` for parameter and return details. + `delete_entity()` for parameter and return details. """ self._schema.delete_entity(entity_id, use_v3=True) @@ -575,7 +575,7 @@ async def delete_entity_async(self, entity_id: str) -> None: entity_id (str): The unique identifier of the entity to delete. Examples: - Delete an entity by id:: + Delete an entity by id: await entities_service.delete_entity_async("a1b2c3d4-...") """ @@ -583,7 +583,7 @@ async def delete_entity_async(self, entity_id: str) -> None: @traced(name="entity_delete_v3", run_type="uipath") async def delete_entity_v3_async(self, entity_id: str) -> None: - """Async variant of :meth:`delete_entity_v3`.""" + """Async variant of `delete_entity_v3()`.""" await self._schema.delete_entity_async(entity_id, use_v3=True) @deprecated( @@ -600,14 +600,14 @@ def update_entity_metadata( Args: entity_id (str): The unique identifier of the entity. metadata (EntityMetadataUpdateOptions | Dict[str, Any]): - An :class:`EntityMetadataUpdateOptions` instance or a dict + An `EntityMetadataUpdateOptions` instance or a dict with any of ``display_name``, ``description``, ``is_rbac_enabled``. Dict keys may be snake_case (``display_name``) or camelCase (``displayName``); both serialize correctly to the API. Examples: - Rename and update description:: + Rename and update description: from uipath.platform.entities import EntityMetadataUpdateOptions @@ -619,7 +619,7 @@ def update_entity_metadata( ), ) - From a plain dict:: + From a plain dict: entities_service.update_entity_metadata( "a1b2c3d4-...", @@ -635,7 +635,7 @@ def update_entity_metadata_v3( """Update entity metadata via the v3 API. Experimental v3 surface (serves Federated entities); see - :meth:`update_entity_metadata` for parameter and return details. + `update_entity_metadata()` for parameter and return details. """ self._schema.update_entity_metadata(entity_id, metadata, use_v3=True) @@ -653,12 +653,12 @@ async def update_entity_metadata_async( Args: entity_id (str): The unique identifier of the entity. metadata (EntityMetadataUpdateOptions | Dict[str, Any]): - An :class:`EntityMetadataUpdateOptions` instance or a dict + An `EntityMetadataUpdateOptions` instance or a dict with any of ``display_name``, ``description``, ``is_rbac_enabled``. Examples: - Rename:: + Rename: from uipath.platform.entities import EntityMetadataUpdateOptions @@ -677,7 +677,7 @@ async def update_entity_metadata_async( async def update_entity_metadata_v3_async( self, entity_id: str, metadata: EntityMetadataUpdateOptions | Dict[str, Any] ) -> None: - """Async variant of :meth:`update_entity_metadata_v3`.""" + """Async variant of `update_entity_metadata_v3()`.""" await self._schema.update_entity_metadata_async( entity_id, metadata, use_v3=True ) @@ -701,7 +701,7 @@ def get_choiceset_values( id, name, display_name, and number_id. Examples: - Get all values in a choice set:: + Get all values in a choice set: values = entities_service.get_choiceset_values("choiceset-id") for v in values: @@ -759,7 +759,7 @@ def list_records( - Field names must match the entity's field names (case-sensitive) - The 'Id' field is automatically validated and does not need to be included - Example schema class:: + Example schema class: class CustomerRecord: name: str # Required field @@ -786,21 +786,21 @@ class CustomerRecord: EntityRecordsListResponse: A list-compatible response with ``total_count``, ``has_next_page`` and ``next_cursor`` pagination metadata. Iteration, indexing, and ``len()`` continue to work - like a plain list of :class:`EntityRecord`. + like a plain list of `EntityRecord`. Raises: ValueError: If schema validation fails for any record, including cases where required fields are missing or field types don't match the schema. Examples: - Basic usage without schema:: + Basic usage without schema: # Retrieve all records from an entity records = entities_service.list_records("Customers") for record in records: print(record.id) - With pagination:: + With pagination: # Get first 50 records records = entities_service.list_records("Customers", start=0, limit=50) @@ -810,12 +810,12 @@ class CustomerRecord: "Customers", start=50, limit=50 ) - With foreign-key expansion:: + With foreign-key expansion: records = entities_service.list_records("Customers", expansion_level=1) - To filter, sort, or project, use :meth:`retrieve_records` — this - endpoint only pages:: + To filter, sort, or project, use `retrieve_records()` — this + endpoint only pages: result = entities_service.retrieve_records( "Customers", @@ -831,7 +831,7 @@ class CustomerRecord: ), ) - With schema validation:: + With schema validation: class CustomerRecord: name: str @@ -869,7 +869,7 @@ def list_records_v3( """List entity records via the v3 API. Experimental v3 surface (serves Federated entities); see - :meth:`list_records` for parameter and return details. + `list_records()` for parameter and return details. """ return self._data.list_records( entity_key, @@ -909,7 +909,7 @@ async def list_records_async( - Field names must match the entity's field names (case-sensitive) - The 'Id' field is automatically validated and does not need to be included - Example schema class:: + Example schema class: class CustomerRecord: name: str # Required field @@ -936,21 +936,21 @@ class CustomerRecord: EntityRecordsListResponse: A list-compatible response with ``total_count``, ``has_next_page`` and ``next_cursor`` pagination metadata. Iteration, indexing, and ``len()`` continue to work - like a plain list of :class:`EntityRecord`. + like a plain list of `EntityRecord`. Raises: ValueError: If schema validation fails for any record, including cases where required fields are missing or field types don't match the schema. Examples: - Basic usage without schema:: + Basic usage without schema: # Retrieve all records from an entity records = await entities_service.list_records_async("Customers") for record in records: print(record.id) - With pagination:: + With pagination: # Get first 50 records records = await entities_service.list_records_async("Customers", start=0, limit=50) @@ -960,16 +960,16 @@ class CustomerRecord: "Customers", start=50, limit=50 ) - With foreign-key expansion:: + With foreign-key expansion: records = await entities_service.list_records_async( "Customers", expansion_level=1 ) - To filter, sort, or project, use :meth:`retrieve_records_async` — + To filter, sort, or project, use `retrieve_records_async()` — this endpoint only pages. - With schema validation:: + With schema validation: class CustomerRecord: name: str @@ -1004,7 +1004,7 @@ async def list_records_v3_async( limit: Optional[int] = None, expansion_level: Optional[int] = None, ) -> EntityRecordsListResponse: - """Async variant of :meth:`list_records_v3`.""" + """Async variant of `list_records_v3()`.""" return await self._data.list_records_async( entity_key, schema=schema, @@ -1027,14 +1027,14 @@ def insert_record( """Insert a single record into an entity and return the inserted row. Note: - Unlike :meth:`insert_records` (batch), this single-record endpoint + Unlike `insert_records()` (batch), this single-record endpoint fires Data Fabric trigger events. Use this method when triggers attached to the entity must run. Args: entity_key (str): The unique key/identifier of the entity. data (Any): Record payload — a dict, a Pydantic model, an - :class:`EntityRecord`, or any object exposing ``__dict__``. + `EntityRecord`, or any object exposing ``__dict__``. expansion_level (Optional[int]): Depth of foreign-key expansion in the response (``0`` means no expansion). @@ -1043,7 +1043,7 @@ def insert_record( plus any expanded relationships. Examples: - Insert from a dict:: + Insert from a dict: record = entities_service.insert_record( "Customers", @@ -1051,7 +1051,7 @@ def insert_record( ) print(record.id) - Insert from a Pydantic model:: + Insert from a Pydantic model: class CustomerInput(BaseModel): name: str @@ -1074,7 +1074,7 @@ def insert_record_v3( """Insert a single record via the v3 API. Experimental v3 surface (serves Federated entities); see - :meth:`insert_record` for parameter and return details. + `insert_record()` for parameter and return details. """ return self._data.insert_record( entity_key, data, expansion_level=expansion_level, use_v3=True @@ -1093,14 +1093,14 @@ async def insert_record_async( """Asynchronously insert a single record into an entity. Note: - Unlike :meth:`insert_records_async` (batch), this single-record + Unlike `insert_records_async()` (batch), this single-record endpoint fires Data Fabric trigger events. Use this method when triggers attached to the entity must run. Args: entity_key (str): The unique key/identifier of the entity. data (Any): Record payload — a dict, a Pydantic model, an - :class:`EntityRecord`, or any object exposing ``__dict__``. + `EntityRecord`, or any object exposing ``__dict__``. expansion_level (Optional[int]): Depth of foreign-key expansion in the response (``0`` means no expansion). @@ -1108,7 +1108,7 @@ async def insert_record_async( EntityRecord: The inserted record with its server-assigned ``Id``. Examples: - Insert from a dict:: + Insert from a dict: record = await entities_service.insert_record_async( "Customers", @@ -1124,7 +1124,7 @@ async def insert_record_async( async def insert_record_v3_async( self, entity_key: str, data: Any, expansion_level: Optional[int] = None ) -> EntityRecord: - """Async variant of :meth:`insert_record_v3`.""" + """Async variant of `insert_record_v3()`.""" return await self._data.insert_record_async( entity_key, data, expansion_level=expansion_level, use_v3=True ) @@ -1149,12 +1149,12 @@ def get_record( EntityRecord: The record, with optional expanded relationships. Examples: - Basic usage:: + Basic usage: record = entities_service.get_record("Customers", "rec-1") print(record.id, record.name) - With FK expansion:: + With FK expansion: # Inline the related Company record on the returned Customer record = entities_service.get_record( @@ -1172,7 +1172,7 @@ def get_record_v3( """Fetch a single record by id via the v3 API. Experimental v3 surface (serves Federated entities); see - :meth:`get_record` for parameter and return details. + `get_record()` for parameter and return details. """ return self._data.get_record( entity_key, record_id, expansion_level=expansion_level, use_v3=True @@ -1200,7 +1200,7 @@ async def get_record_async( EntityRecord: The record. Examples: - Basic usage:: + Basic usage: record = await entities_service.get_record_async("Customers", "rec-1") print(record.id, record.name) @@ -1213,7 +1213,7 @@ async def get_record_async( async def get_record_v3_async( self, entity_key: str, record_id: str, expansion_level: Optional[int] = None ) -> EntityRecord: - """Async variant of :meth:`get_record_v3`.""" + """Async variant of `get_record_v3()`.""" return await self._data.get_record_async( entity_key, record_id, expansion_level=expansion_level, use_v3=True ) @@ -1232,7 +1232,7 @@ def update_record( """Update a single record by id and return the updated row. Note: - Unlike :meth:`update_records` (batch), this single-record endpoint + Unlike `update_records()` (batch), this single-record endpoint fires Data Fabric trigger events. Use this method when triggers attached to the entity must run. @@ -1249,7 +1249,7 @@ def update_record( EntityRecord: The updated record. Examples: - Partial update from a dict:: + Partial update from a dict: record = entities_service.update_record( "Customers", @@ -1257,7 +1257,7 @@ def update_record( {"email": "alice.new@example.com"}, ) - Clear a field by passing an explicit ``None``:: + Clear a field by passing an explicit ``None``: # Note: unset fields are omitted; explicit None values are sent. record = entities_service.update_record( @@ -1281,7 +1281,7 @@ def update_record_v3( """Update a single record by id via the v3 API. Experimental v3 surface (serves Federated entities); see - :meth:`update_record` for parameter and return details. + `update_record()` for parameter and return details. """ return self._data.update_record( entity_key, record_id, data, expansion_level=expansion_level, use_v3=True @@ -1301,7 +1301,7 @@ async def update_record_async( """Asynchronously update a single record by id. Note: - Unlike :meth:`update_records_async` (batch), this single-record + Unlike `update_records_async()` (batch), this single-record endpoint fires Data Fabric trigger events. Args: @@ -1315,7 +1315,7 @@ async def update_record_async( EntityRecord: The updated record. Examples: - Partial update:: + Partial update: record = await entities_service.update_record_async( "Customers", @@ -1335,7 +1335,7 @@ async def update_record_v3_async( data: Any, expansion_level: Optional[int] = None, ) -> EntityRecord: - """Async variant of :meth:`update_record_v3`.""" + """Async variant of `update_record_v3()`.""" return await self._data.update_record_async( entity_key, record_id, data, expansion_level=expansion_level, use_v3=True ) @@ -1348,7 +1348,7 @@ def delete_record(self, entity_key: str, record_id: str) -> None: """Delete a single record by id. Note: - Unlike :meth:`delete_records` (batch), this single-record endpoint + Unlike `delete_records()` (batch), this single-record endpoint fires Data Fabric trigger events. Use this method when triggers attached to the entity must run on delete. @@ -1357,7 +1357,7 @@ def delete_record(self, entity_key: str, record_id: str) -> None: record_id (str): The unique identifier of the record to delete. Examples: - Delete by id:: + Delete by id: entities_service.delete_record("Customers", "rec-1") """ @@ -1368,7 +1368,7 @@ def delete_record_v3(self, entity_key: str, record_id: str) -> None: """Delete a single record by id via the v3 API. Experimental v3 surface (serves Federated entities); see - :meth:`delete_record` for parameter and return details. + `delete_record()` for parameter and return details. """ self._data.delete_record(entity_key, record_id, use_v3=True) @@ -1380,7 +1380,7 @@ async def delete_record_async(self, entity_key: str, record_id: str) -> None: """Asynchronously delete a single record by id. Note: - Unlike :meth:`delete_records_async` (batch), this single-record + Unlike `delete_records_async()` (batch), this single-record endpoint fires Data Fabric trigger events. Args: @@ -1388,7 +1388,7 @@ async def delete_record_async(self, entity_key: str, record_id: str) -> None: record_id (str): The unique identifier of the record to delete. Examples: - Delete by id:: + Delete by id: await entities_service.delete_record_async("Customers", "rec-1") """ @@ -1396,7 +1396,7 @@ async def delete_record_async(self, entity_key: str, record_id: str) -> None: @traced(name="entity_delete_record_v3", run_type="uipath") async def delete_record_v3_async(self, entity_key: str, record_id: str) -> None: - """Async variant of :meth:`delete_record_v3`.""" + """Async variant of `delete_record_v3()`.""" await self._data.delete_record_async(entity_key, record_id, use_v3=True) async def get_ontology_file_async( @@ -1439,7 +1439,7 @@ def insert_records( Args: entity_key (str): The unique key/identifier of the entity. records (List[Any]): List of records to insert. Each record may be - a dict, a Pydantic model, an :class:`EntityRecord`, or any + a dict, a Pydantic model, an `EntityRecord`, or any object exposing ``__dict__``. schema (Optional[Type[Any]]): Optional schema class for validation. When provided, validates that each record in the response matches the schema structure. @@ -1452,11 +1452,11 @@ def insert_records( Returns: EntityRecordsBatchResponse: Response containing successful and failed record operations. - - success_records: List of successfully inserted :class:`EntityRecord` objects - - failure_records: List of :class:`FailureRecord` describing per-record errors + - success_records: List of successfully inserted `EntityRecord` objects + - failure_records: List of `FailureRecord` describing per-record errors Examples: - Insert records without schema:: + Insert records without schema: class Customer: def __init__(self, name, email, age): @@ -1477,7 +1477,7 @@ def __init__(self, name, email, age): print(f"Inserted: {len(response.success_records)}") print(f"Failed: {len(response.failure_records)}") - Insert with FK expansion and fail-fast:: + Insert with FK expansion and fail-fast: response = entities_service.insert_records( "Orders", @@ -1486,7 +1486,7 @@ def __init__(self, name, email, age): fail_on_first=True, # abort the batch at the first error ) - Insert with schema validation:: + Insert with schema validation: class CustomerSchema: name: str @@ -1531,7 +1531,7 @@ def insert_records_v3( """Batch-insert records via the v3 API. Experimental v3 surface (serves Federated entities); see - :meth:`insert_records` for parameter and return details. + `insert_records()` for parameter and return details. """ return self._data.insert_records( entity_key, @@ -1559,7 +1559,7 @@ async def insert_records_async( Args: entity_key (str): The unique key/identifier of the entity. records (List[Any]): List of records to insert. Each record may be - a dict, a Pydantic model, an :class:`EntityRecord`, or any + a dict, a Pydantic model, an `EntityRecord`, or any object exposing ``__dict__``. schema (Optional[Type[Any]]): Optional schema class for validation. When provided, validates that each record in the response matches the schema structure. @@ -1572,11 +1572,11 @@ async def insert_records_async( Returns: EntityRecordsBatchResponse: Response containing successful and failed record operations. - - success_records: List of successfully inserted :class:`EntityRecord` objects - - failure_records: List of :class:`FailureRecord` describing per-record errors + - success_records: List of successfully inserted `EntityRecord` objects + - failure_records: List of `FailureRecord` describing per-record errors Examples: - Insert records without schema:: + Insert records without schema: class Customer: def __init__(self, name, email, age): @@ -1597,7 +1597,7 @@ def __init__(self, name, email, age): print(f"Inserted: {len(response.success_records)}") print(f"Failed: {len(response.failure_records)}") - Insert with schema validation:: + Insert with schema validation: class CustomerSchema: name: str @@ -1639,7 +1639,7 @@ async def insert_records_v3_async( expansion_level: Optional[int] = None, fail_on_first: Optional[bool] = None, ) -> EntityRecordsBatchResponse: - """Async variant of :meth:`insert_records_v3`.""" + """Async variant of `insert_records_v3()`.""" return await self._data.insert_records_async( entity_key, records, @@ -1667,7 +1667,7 @@ def update_records( entity_key (str): The unique key/identifier of the entity. records (List[Any]): List of records to update. Each record must include its ``Id`` field. A record may be a dict, a Pydantic - model, an :class:`EntityRecord`, or any object exposing + model, an `EntityRecord`, or any object exposing ``__dict__``. schema (Optional[Type[Any]]): Optional schema class for validation. When provided, validates that each record in the request and response matches the schema structure. @@ -1680,11 +1680,11 @@ def update_records( Returns: EntityRecordsBatchResponse: Response containing successful and failed record operations. - - success_records: List of successfully updated :class:`EntityRecord` objects - - failure_records: List of :class:`FailureRecord` describing per-record errors + - success_records: List of successfully updated `EntityRecord` objects + - failure_records: List of `FailureRecord` describing per-record errors Examples: - Update records:: + Update records: # First, retrieve records to update records = entities_service.list_records("a1b2c3d4-e5f6-7890-abcd-ef1234567890") @@ -1703,7 +1703,7 @@ def update_records( print(f"Updated: {len(response.success_records)}") print(f"Failed: {len(response.failure_records)}") - Update with schema validation:: + Update with schema validation: class CustomerSchema: name: str @@ -1750,7 +1750,7 @@ def update_records_v3( """Batch-update records via the v3 API. Experimental v3 surface (serves Federated entities); see - :meth:`update_records` for parameter and return details. + `update_records()` for parameter and return details. """ return self._data.update_records( entity_key, @@ -1779,7 +1779,7 @@ async def update_records_async( entity_key (str): The unique key/identifier of the entity. records (List[Any]): List of records to update. Each record must include its ``Id`` field. A record may be a dict, a Pydantic - model, an :class:`EntityRecord`, or any object exposing + model, an `EntityRecord`, or any object exposing ``__dict__``. schema (Optional[Type[Any]]): Optional schema class for validation. When provided, validates that each record in the request and response matches the schema structure. @@ -1792,11 +1792,11 @@ async def update_records_async( Returns: EntityRecordsBatchResponse: Response containing successful and failed record operations. - - success_records: List of successfully updated :class:`EntityRecord` objects - - failure_records: List of :class:`FailureRecord` describing per-record errors + - success_records: List of successfully updated `EntityRecord` objects + - failure_records: List of `FailureRecord` describing per-record errors Examples: - Update records:: + Update records: # First, retrieve records to update records = await entities_service.list_records_async("a1b2c3d4-e5f6-7890-abcd-ef1234567890") @@ -1815,7 +1815,7 @@ async def update_records_async( print(f"Updated: {len(response.success_records)}") print(f"Failed: {len(response.failure_records)}") - Update with schema validation:: + Update with schema validation: class CustomerSchema: name: str @@ -1859,7 +1859,7 @@ async def update_records_v3_async( expansion_level: Optional[int] = None, fail_on_first: Optional[bool] = None, ) -> EntityRecordsBatchResponse: - """Async variant of :meth:`update_records_v3`.""" + """Async variant of `update_records_v3()`.""" return await self._data.update_records_async( entity_key, records, @@ -1891,11 +1891,11 @@ def delete_records( Returns: EntityRecordsBatchResponse: Response containing successful and failed record operations. - - success_records: List of successfully deleted :class:`EntityRecord` objects - - failure_records: List of :class:`FailureRecord` describing per-record errors + - success_records: List of successfully deleted `EntityRecord` objects + - failure_records: List of `FailureRecord` describing per-record errors Examples: - Delete specific records by ID:: + Delete specific records by ID: # Delete records by their IDs record_ids = [ @@ -1911,7 +1911,7 @@ def delete_records( print(f"Deleted: {len(response.success_records)}") print(f"Failed: {len(response.failure_records)}") - Delete records matching a condition:: + Delete records matching a condition: # Get all records records = entities_service.list_records("a1b2c3d4-e5f6-7890-abcd-ef1234567890") @@ -1943,7 +1943,7 @@ def delete_records_v3( """Batch-delete records via the v3 API. Experimental v3 surface (serves Federated entities); see - :meth:`delete_records` for parameter and return details. + `delete_records()` for parameter and return details. """ return self._data.delete_records( entity_key, record_ids, fail_on_first=fail_on_first, use_v3=True @@ -1971,11 +1971,11 @@ async def delete_records_async( Returns: EntityRecordsBatchResponse: Response containing successful and failed record operations. - - success_records: List of successfully deleted :class:`EntityRecord` objects - - failure_records: List of :class:`FailureRecord` describing per-record errors + - success_records: List of successfully deleted `EntityRecord` objects + - failure_records: List of `FailureRecord` describing per-record errors Examples: - Delete specific records by ID:: + Delete specific records by ID: # Delete records by their IDs record_ids = [ @@ -1991,7 +1991,7 @@ async def delete_records_async( print(f"Deleted: {len(response.success_records)}") print(f"Failed: {len(response.failure_records)}") - Delete records matching a condition:: + Delete records matching a condition: # Get all records records = await entities_service.list_records_async("a1b2c3d4-e5f6-7890-abcd-ef1234567890") @@ -2020,7 +2020,7 @@ async def delete_records_v3_async( record_ids: List[str], fail_on_first: Optional[bool] = None, ) -> EntityRecordsBatchResponse: - """Async variant of :meth:`delete_records_v3`.""" + """Async variant of `delete_records_v3()`.""" return await self._data.delete_records_async( entity_key, record_ids, fail_on_first=fail_on_first, use_v3=True ) @@ -2079,14 +2079,14 @@ def retrieve_records( Returns: RetrieveEntityRecordsResponse: A response with ``items``, ``total_count``, ``has_next_page``, and ``next_cursor``. - ``items`` is a list of :class:`EntityRecord` for plain - queries, or :class:`AggregateRow` when ``aggregates``, + ``items`` is a list of `EntityRecord` for plain + queries, or `AggregateRow` when ``aggregates``, ``group_by``, or ``binnings`` are used. ``next_cursor`` is populated only when the backend returns one; otherwise paginate by passing the next ``start``. Examples: - Filter + sort + projection:: + Filter + sort + projection: from uipath.platform.entities import ( EntityQueryFilter, @@ -2117,7 +2117,7 @@ def retrieve_records( ) print(f"Found {result.total_count} customers") - Aggregates and group-by (counts per status):: + Aggregates and group-by (counts per status): from uipath.platform.entities import ( EntityAggregate, @@ -2173,7 +2173,7 @@ def retrieve_records_v3( """Run a structured record query via the v3 API. Experimental v3 surface (serves Federated entities); see - :meth:`retrieve_records` for parameter and return details. + `retrieve_records()` for parameter and return details. """ return self._data.retrieve_records( entity_key, @@ -2244,7 +2244,7 @@ async def retrieve_records_async( ``total_count``, ``has_next_page``, and ``next_cursor``. Examples: - Filter + sort + pagination:: + Filter + sort + pagination: from uipath.platform.entities import ( EntityQueryFilter, @@ -2299,7 +2299,7 @@ async def retrieve_records_v3_async( start: Optional[int] = None, limit: Optional[int] = None, ) -> RetrieveEntityRecordsResponse: - """Async variant of :meth:`retrieve_records_v3`.""" + """Async variant of `retrieve_records_v3()`.""" return await self._data.retrieve_records_async( entity_key, filter_group=filter_group, @@ -2433,7 +2433,7 @@ def upload_attachment( record), or an empty dict when the response has no body. Examples: - Upload from raw bytes:: + Upload from raw bytes: with open("contract.pdf", "rb") as f: data = f.read() @@ -2441,7 +2441,7 @@ def upload_attachment( "Customers", "rec-1", "Contract", file=data ) - Upload from a path on disk:: + Upload from a path on disk: entities_service.upload_attachment( "Customers", "rec-1", "Contract", file_path="./contract.pdf" @@ -2487,7 +2487,7 @@ async def upload_attachment_async( Dict[str, Any]: The decoded JSON response. Examples: - Upload from a path on disk:: + Upload from a path on disk: await entities_service.upload_attachment_async( "Customers", "rec-1", "Contract", file_path="./contract.pdf" @@ -2518,7 +2518,7 @@ def download_attachment( bytes: The raw file content. Examples: - Save the downloaded bytes to disk:: + Save the downloaded bytes to disk: content = entities_service.download_attachment( "Customers", "rec-1", "Contract" @@ -2544,7 +2544,7 @@ async def download_attachment_async( bytes: The raw file content. Examples: - Save the downloaded bytes to disk:: + Save the downloaded bytes to disk: content = await entities_service.download_attachment_async( "Customers", "rec-1", "Contract" @@ -2579,7 +2579,7 @@ def delete_attachment( record), or an empty dict when the response has no body. Examples: - Clear an attachment:: + Clear an attachment: entities_service.delete_attachment( "Customers", "rec-1", "Contract" @@ -2610,7 +2610,7 @@ async def delete_attachment_async( Dict[str, Any]: The decoded JSON response. Examples: - Clear an attachment:: + Clear an attachment: await entities_service.delete_attachment_async( "Customers", "rec-1", "Contract" @@ -2646,7 +2646,7 @@ def import_records( failed validation. Examples: - Import from a path on disk:: + Import from a path on disk: result = entities_service.import_records( "Customers", file_path="./customers.csv" @@ -2682,7 +2682,7 @@ async def import_records_async( ``error_file_link`` for failed rows. Examples: - Import from a path on disk:: + Import from a path on disk: result = await entities_service.import_records_async( "Customers", file_path="./customers.csv" @@ -2707,7 +2707,7 @@ def validate_entity_batch( ) -> EntityRecordsBatchResponse: """Parse a batch response, optionally validating success records against ``schema``. - Failure records are returned as :class:`FailureRecord` instances and + Failure records are returned as `FailureRecord` instances and are not validated against the user schema. """ return self._data.validate_entity_batch(batch_response, schema=schema) @@ -2799,7 +2799,7 @@ def resolve_entity_set_v3( ) -> EntitySetResolution: """Resolve an agent entity set via the v3 API (serves Federated entities). - Experimental v3 surface; behaves like :meth:`resolve_entity_set` but + Experimental v3 surface; behaves like `resolve_entity_set()` but fetches entity metadata from ``datafabric_/api/v3/entities`` so Federated entities resolve with their external field definitions. """ @@ -2835,7 +2835,7 @@ async def resolve_entity_set_v3_async( self, items: List[DataFabricEntityItem], ) -> EntitySetResolution: - """Async variant of :meth:`resolve_entity_set_v3`.""" + """Async variant of `resolve_entity_set_v3()`.""" async def _resolve_folder_path(folder_path: str) -> Optional[str]: if self._folders_service is None: diff --git a/packages/uipath-platform/src/uipath/platform/entities/_entity_data_service.py b/packages/uipath-platform/src/uipath/platform/entities/_entity_data_service.py index 61f29a3e0..ace8718e8 100644 --- a/packages/uipath-platform/src/uipath/platform/entities/_entity_data_service.py +++ b/packages/uipath-platform/src/uipath/platform/entities/_entity_data_service.py @@ -2,8 +2,8 @@ Handles record CRUD (single and batch), structured queries, attachments, choice-set value lookup, bulk import, and federated SQL queries. Schema -definitions are managed by :class:`EntitySchemaService` and exposed alongside -data operations through :class:`EntitiesService`. +definitions are managed by `EntitySchemaService` and exposed alongside +data operations through `EntitiesService`. """ import json as json_module @@ -125,7 +125,7 @@ def get_choiceset_values( start: Optional[int] = None, limit: Optional[int] = None, ) -> List[ChoiceSetValue]: - """Internal implementation; see :meth:`EntitiesService.get_choiceset_values`.""" + """Internal implementation; see `EntitiesService.get_choiceset_values()`.""" spec = self._get_choiceset_values_spec(choiceset_id, start=start, limit=limit) response = self.request( spec.method, spec.endpoint, params=spec.params, json=spec.json @@ -138,7 +138,7 @@ async def get_choiceset_values_async( start: Optional[int] = None, limit: Optional[int] = None, ) -> List[ChoiceSetValue]: - """Async variant of :meth:`get_choiceset_values`.""" + """Async variant of `get_choiceset_values()`.""" spec = self._get_choiceset_values_spec(choiceset_id, start=start, limit=limit) response = await self.request_async( spec.method, spec.endpoint, params=spec.params, json=spec.json @@ -158,7 +158,7 @@ def list_records( expansion_level: Optional[int] = None, use_v3: bool = False, ) -> EntityRecordsListResponse: - """Internal implementation; see :meth:`EntitiesService.list_records`.""" + """Internal implementation; see `EntitiesService.list_records()`.""" spec = self._list_records_spec( entity_key, start=start, @@ -178,7 +178,7 @@ async def list_records_async( expansion_level: Optional[int] = None, use_v3: bool = False, ) -> EntityRecordsListResponse: - """Async variant of :meth:`list_records`.""" + """Async variant of `list_records()`.""" spec = self._list_records_spec( entity_key, start=start, @@ -202,7 +202,7 @@ def insert_record( expansion_level: Optional[int] = None, use_v3: bool = False, ) -> EntityRecord: - """Internal implementation; see :meth:`EntitiesService.insert_record`.""" + """Internal implementation; see `EntitiesService.insert_record()`.""" spec = self._insert_record_spec( entity_key, data, expansion_level, use_v3=use_v3 ) @@ -218,7 +218,7 @@ async def insert_record_async( expansion_level: Optional[int] = None, use_v3: bool = False, ) -> EntityRecord: - """Async variant of :meth:`insert_record`.""" + """Async variant of `insert_record()`.""" spec = self._insert_record_spec( entity_key, data, expansion_level, use_v3=use_v3 ) @@ -248,7 +248,7 @@ async def get_record_async( expansion_level: Optional[int] = None, use_v3: bool = False, ) -> EntityRecord: - """Async variant of :meth:`get_record`.""" + """Async variant of `get_record()`.""" spec = self._get_record_spec( entity_key, record_id, expansion_level, use_v3=use_v3 ) @@ -265,7 +265,7 @@ def update_record( expansion_level: Optional[int] = None, use_v3: bool = False, ) -> EntityRecord: - """Internal implementation; see :meth:`EntitiesService.update_record`.""" + """Internal implementation; see `EntitiesService.update_record()`.""" spec = self._update_record_spec( entity_key, record_id, data, expansion_level, use_v3=use_v3 ) @@ -282,7 +282,7 @@ async def update_record_async( expansion_level: Optional[int] = None, use_v3: bool = False, ) -> EntityRecord: - """Async variant of :meth:`update_record`.""" + """Async variant of `update_record()`.""" spec = self._update_record_spec( entity_key, record_id, data, expansion_level, use_v3=use_v3 ) @@ -301,7 +301,7 @@ def delete_record( async def delete_record_async( self, entity_key: str, record_id: str, use_v3: bool = False ) -> None: - """Async variant of :meth:`delete_record`.""" + """Async variant of `delete_record()`.""" spec = self._delete_record_spec(entity_key, record_id, use_v3=use_v3) await self.request_async(spec.method, spec.endpoint) @@ -318,7 +318,7 @@ def insert_records( fail_on_first: Optional[bool] = None, use_v3: bool = False, ) -> EntityRecordsBatchResponse: - """Internal implementation; see :meth:`EntitiesService.insert_records`.""" + """Internal implementation; see `EntitiesService.insert_records()`.""" spec = self._insert_batch_spec( entity_key, records, @@ -344,7 +344,7 @@ async def insert_records_async( fail_on_first: Optional[bool] = None, use_v3: bool = False, ) -> EntityRecordsBatchResponse: - """Async variant of :meth:`insert_records`.""" + """Async variant of `insert_records()`.""" spec = self._insert_batch_spec( entity_key, records, @@ -372,7 +372,7 @@ def update_records( fail_on_first: Optional[bool] = None, use_v3: bool = False, ) -> EntityRecordsBatchResponse: - """Internal implementation; see :meth:`EntitiesService.update_records`.""" + """Internal implementation; see `EntitiesService.update_records()`.""" normalized = [self._record_to_dict(record) for record in records] if schema is not None: for record in normalized: @@ -403,7 +403,7 @@ async def update_records_async( fail_on_first: Optional[bool] = None, use_v3: bool = False, ) -> EntityRecordsBatchResponse: - """Async variant of :meth:`update_records`.""" + """Async variant of `update_records()`.""" normalized = [self._record_to_dict(record) for record in records] if schema is not None: for record in normalized: @@ -454,7 +454,7 @@ async def delete_records_async( fail_on_first: Optional[bool] = None, use_v3: bool = False, ) -> EntityRecordsBatchResponse: - """Async variant of :meth:`delete_records`.""" + """Async variant of `delete_records()`.""" spec = self._delete_batch_spec( entity_key, record_ids, fail_on_first=fail_on_first, use_v3=use_v3 ) @@ -489,7 +489,7 @@ def retrieve_records( limit: Optional[int] = None, use_v3: bool = False, ) -> RetrieveEntityRecordsResponse: - """Internal implementation; see :meth:`EntitiesService.retrieve_records`.""" + """Internal implementation; see `EntitiesService.retrieve_records()`.""" spec = self._retrieve_records_spec( entity_key, filter_group=filter_group, @@ -526,7 +526,7 @@ async def retrieve_records_async( limit: Optional[int] = None, use_v3: bool = False, ) -> RetrieveEntityRecordsResponse: - """Async variant of :meth:`retrieve_records`.""" + """Async variant of `retrieve_records()`.""" spec = self._retrieve_records_spec( entity_key, filter_group=filter_group, @@ -557,7 +557,7 @@ def query_entity_records( relationships_as_scalar: bool = False, resolve_choice_sets: bool = False, ) -> List[Dict[str, Any]]: - """Internal implementation; see :meth:`EntitiesService.query_entity_records`.""" + """Internal implementation; see `EntitiesService.query_entity_records()`.""" return self._query_entities_for_records( sql_query, relationships_as_scalar, resolve_choice_sets ) @@ -568,7 +568,7 @@ async def query_entity_records_async( relationships_as_scalar: bool = False, resolve_choice_sets: bool = False, ) -> List[Dict[str, Any]]: - """Async variant of :meth:`query_entity_records`.""" + """Async variant of `query_entity_records()`.""" return await self._query_entities_for_records_async( sql_query, relationships_as_scalar, resolve_choice_sets ) @@ -586,7 +586,7 @@ def upload_attachment( file_path: Optional[str] = None, expansion_level: Optional[int] = None, ) -> Dict[str, Any]: - """Internal implementation; see :meth:`EntitiesService.upload_attachment`.""" + """Internal implementation; see `EntitiesService.upload_attachment()`.""" spec = self._attachment_endpoint( entity_id, record_id, field_name, expansion_level ) @@ -608,7 +608,7 @@ async def upload_attachment_async( file_path: Optional[str] = None, expansion_level: Optional[int] = None, ) -> Dict[str, Any]: - """Async variant of :meth:`upload_attachment`.""" + """Async variant of `upload_attachment()`.""" spec = self._attachment_endpoint( entity_id, record_id, field_name, expansion_level ) @@ -624,7 +624,7 @@ async def upload_attachment_async( def download_attachment( self, entity_id: str, record_id: str, field_name: str ) -> bytes: - """Internal implementation; see :meth:`EntitiesService.download_attachment`.""" + """Internal implementation; see `EntitiesService.download_attachment()`.""" spec = self._attachment_endpoint(entity_id, record_id, field_name) response = self.request("GET", spec.endpoint) return response.content @@ -632,7 +632,7 @@ def download_attachment( async def download_attachment_async( self, entity_id: str, record_id: str, field_name: str ) -> bytes: - """Async variant of :meth:`download_attachment`.""" + """Async variant of `download_attachment()`.""" spec = self._attachment_endpoint(entity_id, record_id, field_name) response = await self.request_async("GET", spec.endpoint) return response.content @@ -644,7 +644,7 @@ def delete_attachment( field_name: str, expansion_level: Optional[int] = None, ) -> Dict[str, Any]: - """Internal implementation; see :meth:`EntitiesService.delete_attachment`.""" + """Internal implementation; see `EntitiesService.delete_attachment()`.""" spec = self._attachment_endpoint( entity_id, record_id, field_name, expansion_level ) @@ -658,7 +658,7 @@ async def delete_attachment_async( field_name: str, expansion_level: Optional[int] = None, ) -> Dict[str, Any]: - """Async variant of :meth:`delete_attachment`.""" + """Async variant of `delete_attachment()`.""" spec = self._attachment_endpoint( entity_id, record_id, field_name, expansion_level ) @@ -675,7 +675,7 @@ def import_records( file: Optional[FileContent] = None, file_path: Optional[str] = None, ) -> EntityImportRecordsResponse: - """Internal implementation; see :meth:`EntitiesService.import_records`.""" + """Internal implementation; see `EntitiesService.import_records()`.""" spec = self._import_records_spec(entity_id) with self._open_file(file, file_path) as handle: response = self.request(spec.method, spec.endpoint, files={"file": handle}) @@ -687,7 +687,7 @@ async def import_records_async( file: Optional[FileContent] = None, file_path: Optional[str] = None, ) -> EntityImportRecordsResponse: - """Async variant of :meth:`import_records`.""" + """Async variant of `import_records()`.""" spec = self._import_records_spec(entity_id) with self._open_file(file, file_path) as handle: response = await self.request_async( @@ -704,7 +704,7 @@ def validate_entity_batch( batch_response: Response, schema: Optional[Type[Any]] = None, ) -> EntityRecordsBatchResponse: - """Internal implementation; see :meth:`EntitiesService.validate_entity_batch`.""" + """Internal implementation; see `EntitiesService.validate_entity_batch()`.""" parsed = EntityRecordsBatchResponse.model_validate(batch_response.json()) validated_successful_records = [] @@ -767,7 +767,7 @@ def _list_records_spec( The endpoint implements only ``start``, ``limit`` and ``expansionLevel``. OData-style ``$filter`` / ``$orderby`` / ``$select`` / ``$expand`` params are accepted and silently ignored by the backend, so they are not sent — - use :meth:`retrieve_records` (``POST .../query``) to filter or sort. + use `retrieve_records()` (``POST .../query``) to filter or sort. """ params: Dict[str, Any] = {} if start is not None: @@ -1104,7 +1104,7 @@ def _open_file(file: Optional[FileContent], file_path: Optional[str]) -> Any: def _record_to_dict(record: Any) -> Dict[str, Any]: """Normalize an input record to a plain dict. - Accepts dicts, Pydantic ``BaseModel`` (including :class:`EntityRecord`), + Accepts dicts, Pydantic ``BaseModel`` (including `EntityRecord`), or any object exposing ``__dict__``. Explicit ``None`` values are preserved so callers can clear fields by setting them to ``None`` on a model instance — only unset fields (whose Pydantic default applies) are @@ -1128,7 +1128,7 @@ def _build_records_list_response( start: Optional[int], limit: Optional[int], ) -> EntityRecordsListResponse: - """Build an :class:`EntityRecordsListResponse` from a list-records body.""" + """Build an `EntityRecordsListResponse` from a list-records body.""" body = response.json() or {} records_data = body.get("value", []) total_count = int( @@ -1158,11 +1158,11 @@ def _parse_query_response( start: Optional[int] = None, limit: Optional[int] = None, ) -> RetrieveEntityRecordsResponse: - """Parse a query response into :class:`RetrieveEntityRecordsResponse`. + """Parse a query response into `RetrieveEntityRecordsResponse`. - Rows that include an ``Id`` field are parsed as :class:`EntityRecord`; + Rows that include an ``Id`` field are parsed as `EntityRecord`; rows that don't (aggregate / group-by / binning results) are parsed as - :class:`AggregateRow`. ``has_next_page`` is derived from + `AggregateRow`. ``has_next_page`` is derived from ``start + len(items) < total_count`` whenever ``limit`` is supplied; ``next_cursor`` is populated only when the backend returns one, otherwise the caller paginates by passing the next ``start``. @@ -1227,7 +1227,7 @@ async def _request_or_extract_batch_async( self, async_call: Any, ) -> Response | EntityRecordsBatchResponse: - """Async variant of :meth:`_request_or_extract_batch`.""" + """Async variant of `_request_or_extract_batch()`.""" try: return await async_call() except EnrichedException as exc: @@ -1277,7 +1277,7 @@ def _validate_sql_query(self, sql_query: str) -> None: Raises: DataFabricSqlValidationError: The statement violates the - entity-query subset. Its :class:`DataFabricError` category + entity-query subset. Its `DataFabricError` category distinguishes a mechanically fixable statement (``BAD_SQL``) from one whose shape the subset cannot express at all (``UNSUPPORTED_CONSTRUCT``), so a retry loop can stop instead diff --git a/packages/uipath-platform/src/uipath/platform/entities/_entity_ontology_service.py b/packages/uipath-platform/src/uipath/platform/entities/_entity_ontology_service.py index a92589f60..48a649c2e 100644 --- a/packages/uipath-platform/src/uipath/platform/entities/_entity_ontology_service.py +++ b/packages/uipath-platform/src/uipath/platform/entities/_entity_ontology_service.py @@ -2,8 +2,8 @@ Handles retrieval of ontology component files (OWL schema, R2RML mapping, and other typed files). Entity schema and record operations are managed by -:class:`EntitySchemaService` / :class:`EntityDataService` and exposed alongside -ontology operations through :class:`EntitiesService`. +`EntitySchemaService` / `EntityDataService` and exposed alongside +ontology operations through `EntitiesService`. """ from typing import Any, Dict, Optional @@ -60,7 +60,7 @@ async def get_file_async( file_type: str = "owl", folder_key: Optional[str] = None, ) -> Dict[str, Any]: - """Internal implementation; see :meth:`EntitiesService.get_ontology_file_async`.""" + """Internal implementation; see `EntitiesService.get_ontology_file_async()`.""" spec = self._ontology_file_spec(ontology_name, file_type, folder_key) response = await self.request_async( spec.method, spec.endpoint, headers=spec.headers diff --git a/packages/uipath-platform/src/uipath/platform/entities/_entity_schema_service.py b/packages/uipath-platform/src/uipath/platform/entities/_entity_schema_service.py index d3fc43c57..b49be540e 100644 --- a/packages/uipath-platform/src/uipath/platform/entities/_entity_schema_service.py +++ b/packages/uipath-platform/src/uipath/platform/entities/_entity_schema_service.py @@ -3,7 +3,7 @@ Handles entity definitions, choice set listings, and the create / delete / update-metadata lifecycle that targets the backend ``EntityController``. Record CRUD, queries, attachments, and bulk import live on -:class:`EntityDataService` and are mediated by :class:`EntitiesService`. +`EntityDataService` and are mediated by `EntitiesService`. """ import re @@ -85,13 +85,13 @@ def __init__( self._folders_service = folders_service def retrieve(self, entity_key: str, use_v3: bool = False) -> Entity: - """Internal implementation; see :meth:`EntitiesService.retrieve`.""" + """Internal implementation; see `EntitiesService.retrieve()`.""" spec = self._retrieve_spec(entity_key, use_v3=use_v3) response = self.request(spec.method, spec.endpoint) return Entity.model_validate(response.json()) async def retrieve_async(self, entity_key: str, use_v3: bool = False) -> Entity: - """Async variant of :meth:`retrieve`.""" + """Async variant of `retrieve()`.""" spec = self._retrieve_spec(entity_key, use_v3=use_v3) response = await self.request_async(spec.method, spec.endpoint) return Entity.model_validate(response.json()) @@ -102,7 +102,7 @@ def retrieve_by_name( folder_key: Optional[str] = None, use_v3: bool = False, ) -> Entity: - """Internal implementation; see :meth:`EntitiesService.retrieve_by_name`.""" + """Internal implementation; see `EntitiesService.retrieve_by_name()`.""" spec = self._retrieve_by_name_spec(entity_name, use_v3=use_v3) headers = self._folder_key_headers(folder_key) response = self.request(spec.method, spec.endpoint, headers=headers) @@ -114,34 +114,34 @@ async def retrieve_by_name_async( folder_key: Optional[str] = None, use_v3: bool = False, ) -> Entity: - """Async variant of :meth:`retrieve_by_name`.""" + """Async variant of `retrieve_by_name()`.""" spec = self._retrieve_by_name_spec(entity_name, use_v3=use_v3) headers = self._folder_key_headers(folder_key) response = await self.request_async(spec.method, spec.endpoint, headers=headers) return Entity.model_validate(response.json()) def list_entities(self, use_v3: bool = False) -> List[Entity]: - """Internal implementation; see :meth:`EntitiesService.list_entities`.""" + """Internal implementation; see `EntitiesService.list_entities()`.""" spec = self._list_entities_spec(use_v3=use_v3) response = self.request(spec.method, spec.endpoint) entities_data = response.json() return [Entity.model_validate(entity) for entity in entities_data] async def list_entities_async(self, use_v3: bool = False) -> List[Entity]: - """Async variant of :meth:`list_entities`.""" + """Async variant of `list_entities()`.""" spec = self._list_entities_spec(use_v3=use_v3) response = await self.request_async(spec.method, spec.endpoint) entities_data = response.json() return [Entity.model_validate(entity) for entity in entities_data] def list_choicesets(self) -> List[Entity]: - """Internal implementation; see :meth:`EntitiesService.list_choicesets`.""" + """Internal implementation; see `EntitiesService.list_choicesets()`.""" spec = self._list_choicesets_spec() response = self.request(spec.method, spec.endpoint) return [Entity.model_validate(item) for item in response.json()] async def list_choicesets_async(self) -> List[Entity]: - """Async variant of :meth:`list_choicesets`.""" + """Async variant of `list_choicesets()`.""" spec = self._list_choicesets_spec() response = await self.request_async(spec.method, spec.endpoint) return [Entity.model_validate(item) for item in response.json()] @@ -153,7 +153,7 @@ def create_entity( options: Optional[EntityCreateOptions] = None, use_v3: bool = False, ) -> str: - """Internal implementation; see :meth:`EntitiesService.create_entity`.""" + """Internal implementation; see `EntitiesService.create_entity()`.""" spec = self._create_entity_spec(name, fields, options, use_v3=use_v3) response = self.request(spec.method, spec.endpoint, json=spec.json) return self._extract_entity_id(response) @@ -165,7 +165,7 @@ async def create_entity_async( options: Optional[EntityCreateOptions] = None, use_v3: bool = False, ) -> str: - """Async variant of :meth:`create_entity`.""" + """Async variant of `create_entity()`.""" spec = self._create_entity_spec(name, fields, options, use_v3=use_v3) response = await self.request_async(spec.method, spec.endpoint, json=spec.json) return self._extract_entity_id(response) @@ -176,7 +176,7 @@ def delete_entity(self, entity_id: str, use_v3: bool = False) -> None: self.request(spec.method, spec.endpoint) async def delete_entity_async(self, entity_id: str, use_v3: bool = False) -> None: - """Async variant of :meth:`delete_entity`.""" + """Async variant of `delete_entity()`.""" spec = self._delete_entity_spec(entity_id, use_v3=use_v3) await self.request_async(spec.method, spec.endpoint) @@ -186,7 +186,7 @@ def update_entity_metadata( metadata: EntityMetadataUpdateOptions | Dict[str, Any], use_v3: bool = False, ) -> None: - """Internal implementation; see :meth:`EntitiesService.update_entity_metadata`.""" + """Internal implementation; see `EntitiesService.update_entity_metadata()`.""" spec = self._update_entity_metadata_spec(entity_id, metadata, use_v3=use_v3) self.request(spec.method, spec.endpoint, json=spec.json) @@ -196,7 +196,7 @@ async def update_entity_metadata_async( metadata: EntityMetadataUpdateOptions | Dict[str, Any], use_v3: bool = False, ) -> None: - """Async variant of :meth:`update_entity_metadata`.""" + """Async variant of `update_entity_metadata()`.""" spec = self._update_entity_metadata_spec(entity_id, metadata, use_v3=use_v3) await self.request_async(spec.method, spec.endpoint, json=spec.json) @@ -357,7 +357,7 @@ def _build_external_sources_payload( Each source's internal columns run through the same field pipeline as native fields (so ``fieldDefinition`` is identical to a native field), paired with its external mapping and source connection/object details. - Dict inputs are validated through :class:`EntityCreateExternalSource`. + Dict inputs are validated through `EntityCreateExternalSource`. """ if not sources: return [] @@ -395,7 +395,7 @@ def _build_external_fields_payload( Produces ``{fieldDefinition, externalFieldMappingDetail}`` per field — ``fieldDefinition`` is the native field payload, ``externalFieldMappingDetail`` - the source mapping (``directionType`` numeric, per :class:`DataDirectionType`). + the source mapping (``directionType`` numeric, per `DataDirectionType`). """ if not fields: return [] @@ -425,7 +425,7 @@ def _update_entity_metadata_spec( ) -> RequestSpec: """Build the PATCH spec for updating entity metadata. - Dict inputs are validated through :class:`EntityMetadataUpdateOptions` + Dict inputs are validated through `EntityMetadataUpdateOptions` so snake_case keys (``display_name``) and camelCase keys (``displayName``) both serialise to the API field names the backend expects. @@ -445,11 +445,11 @@ def _build_schema_field_payload( ) -> Dict[str, Any]: """Build the API field payload for a single field on create-entity. - Maps :class:`EntityFieldDataType` to the backend's ``sqlType.name`` and + Maps `EntityFieldDataType` to the backend's ``sqlType.name`` and ``fieldDisplayType`` (e.g. ``STRING`` becomes ``NVARCHAR`` / ``Basic``). Caller-supplied constraints are validated against - :data:`ENTITY_FIELD_CONSTRAINT_SPEC`; unsupplied per-type constraints - fall back to :data:`ENTITY_FIELD_CONSTRAINT_DEFAULTS` so the field is + `ENTITY_FIELD_CONSTRAINT_SPEC`; unsupplied per-type constraints + fall back to `ENTITY_FIELD_CONSTRAINT_DEFAULTS` so the field is persisted fully and remains editable later. """ ftype = field.type or EntityFieldDataType.STRING @@ -572,7 +572,7 @@ def _validate_name(name: str, context: str) -> None: stay consistent with the UI's entity / field creation forms). Field names additionally cannot collide with the system-reserved field - names in :data:`RESERVED_FIELD_NAMES`; the reserved-name check runs + names in `RESERVED_FIELD_NAMES`; the reserved-name check runs first so that short reserved names produce a more informative error. """ if context == "field": @@ -600,7 +600,7 @@ def _validate_field_constraints( Rejects constraints that ``ftype`` does not accept (e.g. ``decimal_precision`` on ``STRING``), values outside the inclusive - range declared in :data:`ENTITY_FIELD_CONSTRAINT_SPEC`, and + range declared in `ENTITY_FIELD_CONSTRAINT_SPEC`, and ``min_value`` greater than or equal to ``max_value`` when both are supplied. Also enforces type-dependent required references: ``CHOICE_SET_SINGLE`` and ``CHOICE_SET_MULTIPLE`` need diff --git a/packages/uipath-platform/src/uipath/platform/entities/entities.py b/packages/uipath-platform/src/uipath/platform/entities/entities.py index eacec20b1..b00754380 100644 --- a/packages/uipath-platform/src/uipath/platform/entities/entities.py +++ b/packages/uipath-platform/src/uipath/platform/entities/entities.py @@ -104,7 +104,7 @@ class EntityClass(str, Enum): class EntityClassId(IntEnum): - """Internal numeric discriminator for :class:`EntityClass` on the wire.""" + """Internal numeric discriminator for `EntityClass` on the wire.""" Native = 9 Federated = 10 @@ -114,7 +114,7 @@ class EntityClassId(IntEnum): EntityClass.Native: EntityClassId.Native, EntityClass.Federated: EntityClassId.Federated, } -"""Maps a public :class:`EntityClass` to its wire :class:`EntityClassId`.""" +"""Maps a public `EntityClass` to its wire `EntityClassId`.""" class EntityFieldMetadata(BaseModel): @@ -325,9 +325,12 @@ def from_data( ) -> "EntityRecord": """Create an EntityRecord instance by validating raw data and optionally instantiating a custom model. - :param data: Raw data dictionary for the entity. - :param model: Optional user-defined class for validation. - :return: EntityRecord instance + Args: + data: Raw data dictionary for the entity. + model: Optional user-defined class for validation. + + Returns: + EntityRecord instance. """ # Validate the "Id" field is mandatory and must be a string id_value = data.get("Id", None) @@ -640,12 +643,12 @@ class AggregateRow(BaseModel): class RetrieveEntityRecordsResponse(BaseModel): - """Response from :meth:`EntitiesService.retrieve_records`. + """Response from `EntitiesService.retrieve_records()`. - For plain queries, ``items`` is a list of :class:`EntityRecord`. When the + For plain queries, ``items`` is a list of `EntityRecord`. When the query uses ``aggregates``, ``group_by``, or ``binnings``, the backend returns rows without an ``Id`` field; those rows are parsed as - :class:`AggregateRow` instances. + `AggregateRow` instances. """ model_config = ConfigDict(validate_by_name=True, validate_by_alias=True) @@ -893,7 +896,7 @@ class EntityCreateExternalObject(BaseModel): class EntityCreateExternalFieldMapping(BaseModel): """Maps an internal column to a field on the external source. - ``direction_type`` is numeric on the wire (see :class:`DataDirectionType`). + ``direction_type`` is numeric on the wire (see `DataDirectionType`). """ model_config = ConfigDict(validate_by_name=True, validate_by_alias=True) diff --git a/packages/uipath-platform/src/uipath/platform/errors/_datafabric_error.py b/packages/uipath-platform/src/uipath/platform/errors/_datafabric_error.py index 989cc41f6..0f723583f 100644 --- a/packages/uipath-platform/src/uipath/platform/errors/_datafabric_error.py +++ b/packages/uipath-platform/src/uipath/platform/errors/_datafabric_error.py @@ -63,7 +63,7 @@ def is_bad_sql(self) -> bool: def is_unsupported_construct(self) -> bool: """True when the entity-query subset cannot express this query shape. - Distinct from :attr:`is_bad_sql`: a bad statement can be fixed by + Distinct from `is_bad_sql`: a bad statement can be fixed by rewriting the SQL, whereas an unsupported construct means retrying a variant of the same approach will fail again. """ @@ -155,10 +155,10 @@ class DataFabricSqlValidationError(ValueError): """A SQL statement rejected by client-side entity-query validation. A thin carrier: the classification callers act on is the - :class:`DataFabricError` on :attr:`error`, the same type server-side - failures produce. Remains a :class:`ValueError` subclass so existing + `DataFabricError` on `error`, the same type server-side + failures produce. Remains a `ValueError` subclass so existing callers catching ``ValueError`` are unaffected; reach the structured form - with :meth:`DataFabricError.from_exception`. + with `DataFabricError.from_exception()`. """ def __init__(self, message: str, *, code: str) -> None: @@ -167,7 +167,7 @@ def __init__(self, message: str, *, code: str) -> None: Args: message: Human-readable rejection reason. code: Stable code for this rejection, classified into a - :class:`DataFabricErrorCategory` by the shared code table. + `DataFabricErrorCategory` by the shared code table. """ super().__init__(message) self.error = DataFabricError.from_validation(code=code, message=message) diff --git a/packages/uipath-platform/src/uipath/platform/governance/_governance_provider.py b/packages/uipath-platform/src/uipath/platform/governance/_governance_provider.py index 1b336ff0e..c3120830c 100644 --- a/packages/uipath-platform/src/uipath/platform/governance/_governance_provider.py +++ b/packages/uipath-platform/src/uipath/platform/governance/_governance_provider.py @@ -1,11 +1,11 @@ """Platform-backed implementation of the core governance provider protocols. -Thin adapter around :class:`GovernanceService` that exposes only the +Thin adapter around `GovernanceService` that exposes only the methods required by -:class:`uipath.core.governance.GovernancePolicyProvider` and -:class:`uipath.core.governance.GovernanceCompensationProvider`. +`uipath.core.governance.GovernancePolicyProvider` and +`uipath.core.governance.GovernanceCompensationProvider`. -Wrap an existing :class:`GovernanceService` (e.g. +Wrap an existing `GovernanceService` (e.g. ``UiPathPlatformGovernanceProvider(service=UiPath().governance)``) or pass ``config``/``execution_context`` to construct one inline. """ @@ -25,12 +25,12 @@ class UiPathPlatformGovernanceProvider: """Platform-backed governance provider. Implements both - :class:`uipath.core.governance.GovernancePolicyProvider` and - :class:`uipath.core.governance.GovernanceCompensationProvider` by - delegating to :class:`GovernanceService`. + `uipath.core.governance.GovernancePolicyProvider` and + `uipath.core.governance.GovernanceCompensationProvider` by + delegating to `GovernanceService`. Args: - service: Existing :class:`GovernanceService` to delegate to. + service: Existing `GovernanceService` to delegate to. Useful for tests and for sharing an SDK service across consumers. When omitted, a fresh service is built from the ``config`` and ``execution_context`` kwargs. @@ -59,7 +59,7 @@ def __init__( @property def service(self) -> GovernanceService: - """The underlying :class:`GovernanceService` instance.""" + """The underlying `GovernanceService` instance.""" return self._service # ── GovernancePolicyProvider ───────────────────────────────────── @@ -69,7 +69,7 @@ def get_policy(self, context: PolicyContext) -> PolicyResponse: return self._service.get_policy(context) async def get_policy_async(self, context: PolicyContext) -> PolicyResponse: - """Async variant of :meth:`get_policy`.""" + """Async variant of `get_policy()`.""" return await self._service.get_policy_async(context) # ── GovernanceCompensationProvider ─────────────────────────────── @@ -79,7 +79,7 @@ def compensate(self, request: GovernRequest) -> None: self._service._compensate(request) async def compensate_async(self, request: GovernRequest) -> None: - """Async variant of :meth:`compensate`.""" + """Async variant of `compensate()`.""" await self._service._compensate_async(request) # ── Custom telemetry events ────────────────────────────────────── @@ -93,7 +93,7 @@ def track_event( ) -> None: """Record a custom telemetry event — delegates to ``GovernanceService``. - See :meth:`GovernanceService._track_event` for parameter + See `GovernanceService._track_event()` for parameter semantics — in particular, the ``operation_id`` → trace-id fallback. """ @@ -108,7 +108,7 @@ async def track_event_async( data: dict[str, Any] | None = None, operation_id: str | None = None, ) -> None: - """Async variant of :meth:`track_event`.""" + """Async variant of `track_event()`.""" await self._service._track_event_async( event_name=event_name, data=data, operation_id=operation_id ) diff --git a/packages/uipath-platform/src/uipath/platform/governance/_governance_service.py b/packages/uipath-platform/src/uipath/platform/governance/_governance_service.py index 3546517c7..6e50fa442 100644 --- a/packages/uipath-platform/src/uipath/platform/governance/_governance_service.py +++ b/packages/uipath-platform/src/uipath/platform/governance/_governance_service.py @@ -3,20 +3,20 @@ Wraps the governance backend endpoints UiPath exposes: - ``GET /{org}/agenticgovernance_/api/v1/runtime/policy`` — fetch the - tenant-managed policy pack (see :meth:`GovernanceService.retrieve_policy`). + tenant-managed policy pack (see `GovernanceService.retrieve_policy()`). - ``POST /{org}/agenticgovernance_/api/v1/runtime/govern`` — compensating governance call fired when a ``guardrail_fallback`` rule matches - (see :meth:`GovernanceService.compensate`). + (see `GovernanceService.compensate()`). A third backend endpoint — ``POST /{org}/agenticgovernance_/api/v1/runtime/log`` — emits custom telemetry events to App Insights. It's reached only through the internal ``_track_event`` helper, which the runtime adapter -(:class:`UiPathPlatformGovernanceProvider`) calls; not part of the +(`UiPathPlatformGovernanceProvider`) calls; not part of the client-facing service surface. -Org/tenant scoping is read from :class:`UiPathConfig`; auth, retries, -trace context, and error enrichment come from :class:`BaseService`. +Org/tenant scoping is read from `UiPathConfig`; auth, retries, +trace context, and error enrichment come from `BaseService`. """ from typing import Any, Optional @@ -57,13 +57,13 @@ class GovernanceService(BaseService): Exposes two endpoints: - - :meth:`retrieve_policy` — GET the tenant-managed policy pack. - - :meth:`compensate` — POST a compensating ``/runtime/govern`` call + - `retrieve_policy()` — GET the tenant-managed policy pack. + - `compensate()` — POST a compensating ``/runtime/govern`` call so the server can run a disabled centralized guardrail and write the per-rule LLMOps audit records itself. - Org and tenant scoping come from :attr:`UiPathConfig.organization_id` - and :attr:`UiPathConfig.tenant_id`; the tenant travels in the + Org and tenant scoping come from `UiPathConfig.organization_id` + and `UiPathConfig.tenant_id`; the tenant travels in the ``x-uipath-internal-tenantid`` header (the URL is org-scoped only). !!! info "Version Availability" @@ -117,7 +117,7 @@ async def retrieve_policy_async( ) -> PolicyResponse: """Asynchronously fetch the governance policy pack. - See :meth:`retrieve_policy` for parameter and return semantics. + See `retrieve_policy()` for parameter and return semantics. """ url, headers = self._build_org_scoped_request(POLICY_API_PATH) params = self._policy_params(is_conversational) @@ -129,17 +129,17 @@ async def retrieve_policy_async( # ── Policy provider adapter (GovernancePolicyProvider protocol) ─ def get_policy(self, context: PolicyContext) -> PolicyResponse: - """Fetch the policy pack — :class:`GovernancePolicyProvider` adapter. + """Fetch the policy pack — `GovernancePolicyProvider` adapter. - Thin wrapper over :meth:`retrieve_policy` that accepts the + Thin wrapper over `retrieve_policy()` that accepts the context model the core protocol uses. Lets the runtime consume - governance through :class:`uipath.core.governance.GovernancePolicyProvider` + governance through `uipath.core.governance.GovernancePolicyProvider` without importing this module. """ return self.retrieve_policy(is_conversational=context.is_conversational) async def get_policy_async(self, context: PolicyContext) -> PolicyResponse: - """Async variant of :meth:`get_policy`.""" + """Async variant of `get_policy()`.""" return await self.retrieve_policy_async( is_conversational=context.is_conversational ) @@ -173,7 +173,7 @@ def compensate( Job-context fields (``folder_key`` / ``job_key`` / ``process_key`` / ``reference_id`` / ``agent_version``) are - auto-populated from :class:`UiPathConfig` when omitted. + auto-populated from `UiPathConfig` when omitted. Caller-supplied values — including the empty string — take precedence. @@ -187,7 +187,7 @@ def compensate( centralized guardrail. trace_id: Canonical 32-char hex trace id. Optional — when ``None`` (default) the service resolves the value - itself at call time via :func:`resolve_trace_id`. + itself at call time via `resolve_trace_id()`. Callers that already hold a resolved id (typically captured on the hook thread before a background-pool hop) pass it in to win over the auto-resolve. @@ -208,7 +208,7 @@ def compensate( Threading: OpenTelemetry context is thread-local; callers that background-pool the compensation call must capture the - canonical trace id (via :func:`resolve_trace_id`) on the + canonical trace id (via `resolve_trace_id()`) on the hook thread and pass it in explicitly — the auto-resolve on the worker thread will see a detached context. """ @@ -249,7 +249,7 @@ async def compensate_async( ) -> None: """Asynchronously POST a compensating ``/runtime/govern`` call. - See :meth:`compensate` for parameter semantics. + See `compensate()` for parameter semantics. """ await self._compensate_async( GovernRequest( @@ -273,16 +273,16 @@ async def compensate_async( @traced(name="governance_compensate", run_type="uipath") def _compensate(self, request: GovernRequest) -> None: - """Fire a compensation call from a pre-built :class:`GovernRequest`. + """Fire a compensation call from a pre-built `GovernRequest`. Internal helper used by the provider adapter - (:class:`uipath.platform.governance.UiPathPlatformGovernanceProvider`) - to satisfy :class:`uipath.core.governance.GovernanceCompensationProvider` + (`uipath.platform.governance.UiPathPlatformGovernanceProvider`) + to satisfy `uipath.core.governance.GovernanceCompensationProvider` without unpacking the request. The public ergonomic counterpart - is :meth:`compensate`. + is `compensate()`. When ``request.trace_id`` is ``None`` the service resolves the - canonical trace id itself via :func:`resolve_trace_id` — same + canonical trace id itself via `resolve_trace_id()` — same fallback ``track_event`` uses. Callers that have a resolved value still pass it in; callers that don't (e.g. the runtime layer, which intentionally stays env-free) leave it ``None`` @@ -295,7 +295,7 @@ def _compensate(self, request: GovernRequest) -> None: @traced(name="governance_compensate", run_type="uipath") async def _compensate_async(self, request: GovernRequest) -> None: - """Async variant of :meth:`_compensate`. + """Async variant of `_compensate()`. Same ``trace_id`` self-resolution behavior as the sync variant. """ @@ -306,7 +306,7 @@ async def _compensate_async(self, request: GovernRequest) -> None: @staticmethod def _resolve_request_trace_id(request: GovernRequest) -> GovernRequest: - """Fill ``request.trace_id`` from :func:`resolve_trace_id` when absent. + """Fill ``request.trace_id`` from `resolve_trace_id()` when absent. Caller-supplied values (including ``""``) win — the runtime captures on the hook thread (via ``contextvars.copy_context`` @@ -324,7 +324,7 @@ def _resolve_request_trace_id(request: GovernRequest) -> GovernRequest: # # ``_track_event`` / ``_track_event_async`` are intentionally # underscore-prefixed: they exist for the runtime adapter - # (:class:`UiPathPlatformGovernanceProvider`) to fire telemetry + # (`UiPathPlatformGovernanceProvider`) to fire telemetry # events through the platform's HTTP stack, not as a client-facing # SDK call. Keeping them off the public surface keeps the auto- # generated docs (``mkdocs`` + ``mkdocstrings``) focused on the @@ -341,7 +341,7 @@ def _track_event( """POST a custom telemetry event to ``/runtime/log``. Internal seam — the runtime adapter - (:class:`UiPathPlatformGovernanceProvider`) calls this to emit + (`UiPathPlatformGovernanceProvider`) calls this to emit governance audit events through the platform's HTTP stack. The server forwards the event to App Insights as a ``customEvents`` row; account / tenant / organization are @@ -355,7 +355,7 @@ def _track_event( values are dropped server-side. operation_id: Optional correlation id forwarded as the ``x-uipath-operation-id`` header. When omitted, falls - back to :func:`resolve_trace_id` so events emitted from + back to `resolve_trace_id()` so events emitted from the same agent trace share an ``operation_Id`` and are queryable together in KQL. When neither is available, the header is omitted and App Insights generates its @@ -384,7 +384,7 @@ async def _track_event_async( data: dict[str, Any] | None = None, operation_id: str | None = None, ) -> None: - """Async variant of :meth:`_track_event`. Internal seam.""" + """Async variant of `_track_event()`. Internal seam.""" self._validate_event_name(event_name) url, headers = self._build_org_scoped_request(LOG_API_PATH) resolved_op_id = operation_id or resolve_trace_id() diff --git a/packages/uipath-platform/src/uipath/platform/governance/_live_track_event_dispatcher.py b/packages/uipath-platform/src/uipath/platform/governance/_live_track_event_dispatcher.py index 432fd91c5..a10a2bc5e 100644 --- a/packages/uipath-platform/src/uipath/platform/governance/_live_track_event_dispatcher.py +++ b/packages/uipath-platform/src/uipath/platform/governance/_live_track_event_dispatcher.py @@ -1,11 +1,11 @@ """Non-blocking dispatcher for governance track-event telemetry. -Wraps :meth:`UiPathPlatformGovernanceProvider.track_event_async` on a +Wraps `UiPathPlatformGovernanceProvider.track_event_async()` on a private background ``asyncio`` event loop so sync callers can fire telemetry events without blocking on the underlying ``POST /runtime/log`` HTTP round-trip. -:meth:`LiveTrackEventDispatcher.dispatch` is a sync fire-and-forget +`LiveTrackEventDispatcher.dispatch()` is a sync fire-and-forget method that mirrors the kwargs of ``track_event_async``. Internally it schedules the async HTTP call onto a dedicated background loop, so the calling thread never blocks on network I/O and the underlying HTTP call @@ -59,16 +59,16 @@ class LiveTrackEventDispatcher: platform's ``/runtime/log`` HTTP call — and the HTTP call itself is awaited (not run on a sync thread pool). - .. code-block:: python - - provider = UiPathPlatformGovernanceProvider(config=..., execution_context=...) - dispatcher = LiveTrackEventDispatcher(provider) - dispatcher.dispatch(event_name="agent.started") - # ... - dispatcher.shutdown() # at process exit + ```python + provider = UiPathPlatformGovernanceProvider(config=..., execution_context=...) + dispatcher = LiveTrackEventDispatcher(provider) + dispatcher.dispatch(event_name="agent.started") + # ... + dispatcher.shutdown() # at process exit + ``` ``dispatch`` has the same kwargs as - :meth:`UiPathPlatformGovernanceProvider.track_event_async` so it is + `UiPathPlatformGovernanceProvider.track_event_async()` so it is a drop-in sync callable for anywhere the async method would go. """ @@ -154,13 +154,13 @@ def dispatch( """Schedule a track-event call on the background loop — returns immediately. The kwargs mirror - :meth:`UiPathPlatformGovernanceProvider.track_event_async` so + `UiPathPlatformGovernanceProvider.track_event_async()` so this method is a drop-in sync callable for the async provider method. Failure modes — all silent, never raised to the caller: - - **Post-shutdown**: dispatch after :meth:`shutdown` returns + - **Post-shutdown**: dispatch after `shutdown()` returns silently; the provider is not called. - **Saturated in-flight cap**: when ``max_inflight`` coroutines are already scheduled, the call is dropped with a warning. @@ -235,7 +235,7 @@ def _on_future_done(self, future: concurrent.futures.Future[None]) -> None: doesn't warn "exception was never retrieved" at GC time. ``concurrent.futures.Future.exception()`` *raises* ``CancelledError`` when the future was cancelled (the observe- - without-raise semantics apply only to :class:`asyncio.Future`, + without-raise semantics apply only to `asyncio.Future`, not this ``concurrent.futures`` type), so the observation is wrapped in a targeted catch. The accounting — semaphore release and pending-set discard — runs in ``finally`` so success, diff --git a/packages/uipath-platform/src/uipath/platform/governance/compensate.py b/packages/uipath-platform/src/uipath/platform/governance/compensate.py index bad4845f9..1f1bcde73 100644 --- a/packages/uipath-platform/src/uipath/platform/governance/compensate.py +++ b/packages/uipath-platform/src/uipath/platform/governance/compensate.py @@ -1,4 +1,4 @@ -"""Re-exports of compensation models from :mod:`uipath.core.governance`. +"""Re-exports of compensation models from `uipath.core.governance`. The wire-shape models live in ``uipath-core`` so the runtime can depend on the protocol contract without importing ``uipath-platform``. This module diff --git a/packages/uipath-platform/src/uipath/platform/governance/policy.py b/packages/uipath-platform/src/uipath/platform/governance/policy.py index 27de1c9e7..fe020cc90 100644 --- a/packages/uipath-platform/src/uipath/platform/governance/policy.py +++ b/packages/uipath-platform/src/uipath/platform/governance/policy.py @@ -1,4 +1,4 @@ -"""Re-exports of governance policy models from :mod:`uipath.core.governance`. +"""Re-exports of governance policy models from `uipath.core.governance`. The wire-shape models live in ``uipath-core`` so the runtime can depend on the protocol contract without importing ``uipath-platform``. This module diff --git a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_actions.py b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_actions.py index 8e6489797..8018cf425 100644 --- a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_actions.py +++ b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_actions.py @@ -15,7 +15,7 @@ class LoggingSeverityLevel(int, Enum): - """Logging severity level for :class:`LogAction`.""" + """Logging severity level for `LogAction`.""" ERROR = logging.ERROR INFO = logging.INFO @@ -55,7 +55,7 @@ def handle_validation_result( @dataclass class BlockAction(GuardrailAction): - """Block execution by raising :class:`GuardrailBlockException`. + """Block execution by raising `GuardrailBlockException`. Framework adapters catch ``GuardrailBlockException`` at the wrapper boundary and convert it to their own runtime error type. @@ -74,7 +74,7 @@ def handle_validation_result( data: str | dict[str, Any], guardrail_name: str, ) -> str | dict[str, Any] | None: - """Raise :class:`GuardrailBlockException` when validation fails.""" + """Raise `GuardrailBlockException` when validation fails.""" if result.result == GuardrailValidationResultType.VALIDATION_FAILED: title = self.title or f"Guardrail [{guardrail_name}] blocked execution" detail = self.detail or result.reason or "Guardrail validation failed" diff --git a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_core.py b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_core.py index ca168a1e0..665937abc 100644 --- a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_core.py +++ b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_core.py @@ -23,8 +23,8 @@ class GuardrailExclude: """Marker to exclude a parameter from guardrail input serialization. - Use with :data:`typing.Annotated` to prevent a specific function parameter - from being collected into the guardrail evaluation payload:: + Use with `typing.Annotated` to prevent a specific function parameter + from being collected into the guardrail evaluation payload: async def process( text: str, @@ -63,11 +63,11 @@ def _make_evaluator( """Return a unified evaluation callable. Delegates to ``validator.run()`` which each validator subclass implements - (:class:`BuiltInGuardrailValidator` hits the UiPath API; - :class:`CustomGuardrailValidator` runs a local Python rule). + (`BuiltInGuardrailValidator` hits the UiPath API; + `CustomGuardrailValidator` runs a local Python rule). Args: - validator: :class:`GuardrailValidatorBase` instance. + validator: `GuardrailValidatorBase` instance. name: Guardrail name — forwarded to ``validator.run()`` on each call. description: Optional description — forwarded to ``validator.run()``. enabled_for_evals: Whether active in evaluation scenarios. @@ -95,7 +95,7 @@ def _eval( def _get_excluded_params(func: Any) -> set[str]: - """Return parameter names annotated with :class:`GuardrailExclude`. + """Return parameter names annotated with `GuardrailExclude`. Args: func: Callable to inspect. diff --git a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_guardrail.py b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_guardrail.py index d61b41c0d..41d4ecfd0 100644 --- a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_guardrail.py +++ b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_guardrail.py @@ -159,7 +159,7 @@ def guardrail( When applied to a plain function or async function, the decorator collects function parameters (PRE) and return value (POST) and evaluates them against - the guardrail. Use :class:`~._core.GuardrailExclude` to opt individual + the guardrail. Use `GuardrailExclude` to opt individual parameters out of serialization. When applied to a factory function whose return value is recognised by a @@ -170,8 +170,8 @@ def guardrail( Args: func: Callable to decorate. Supplied directly when used without parentheses. - validator: :class:`~.validators.GuardrailValidatorBase` defining what to check. - action: :class:`~._models.GuardrailAction` defining how to respond on violation. + validator: `GuardrailValidatorBase` defining what to check. + action: `GuardrailAction` defining how to respond on violation. name: Human-readable name for this guardrail instance. description: Optional description passed to API-based guardrails. stage: When to evaluate — ``PRE``, ``POST``, or ``PRE_AND_POST``. @@ -185,7 +185,7 @@ def guardrail( Raises: ValueError: If *action* is invalid, or the validator does not support the requested stage. - GuardrailBlockException: Raised at runtime by :class:`~._actions.BlockAction` + GuardrailBlockException: Raised at runtime by `BlockAction` when a violation is detected. """ if action is None: diff --git a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_models.py b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_models.py index 8d86fbf39..d5010d7db 100644 --- a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_models.py +++ b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_models.py @@ -48,7 +48,7 @@ class GuardrailAction(ABC): Subclass this to implement custom behaviour on validation failure, such as logging, blocking, or content sanitisation. Built-in implementations are - :class:`LogAction` and :class:`BlockAction`. + `LogAction` and `BlockAction`. """ @abstractmethod diff --git a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_registry.py b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_registry.py index c4b7773b5..c55a09594 100644 --- a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_registry.py +++ b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/_registry.py @@ -11,9 +11,9 @@ class GuardrailTargetAdapter(Protocol): """Protocol for framework-specific guardrail adapters. - Implement this protocol to teach :func:`guardrail` how to handle objects + Implement this protocol to teach `guardrail()` how to handle objects from a particular framework. Register instances via - :func:`register_guardrail_adapter`. + `register_guardrail_adapter()`. """ def recognize(self, target: Any) -> bool: @@ -39,7 +39,7 @@ def wrap( Args: target: Object to wrap. - evaluator: Unified evaluation callable from :func:`_make_evaluator`. + evaluator: Unified evaluation callable from `_make_evaluator()`. action: Action to invoke on validation failure. name: Human-readable guardrail name. stage: When to evaluate (PRE, POST, or PRE_AND_POST). @@ -60,7 +60,7 @@ def register_guardrail_adapter(adapter: GuardrailTargetAdapter) -> None: Later-registered adapters are tried first. Args: - adapter: An instance implementing :class:`GuardrailTargetAdapter`. + adapter: An instance implementing `GuardrailTargetAdapter`. """ _adapters.insert(0, adapter) diff --git a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/_base.py b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/_base.py index a9eaf5afd..fd7970db9 100644 --- a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/_base.py +++ b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/_base.py @@ -14,21 +14,21 @@ class GuardrailValidatorBase: """Root base class for guardrail validators. Concrete validators should subclass either - :class:`BuiltInGuardrailValidator` (for UiPath API-backed validation) - or :class:`CustomGuardrailValidator` (for in-process Python validation). + `BuiltInGuardrailValidator` (for UiPath API-backed validation) + or `CustomGuardrailValidator` (for in-process Python validation). """ supported_stages: ClassVar[list[GuardrailExecutionStage]] = [] """Stages this validator supports. Empty list means all stages are allowed.""" def validate_stage(self, stage: GuardrailExecutionStage) -> None: - """Raise ``ValueError`` if *stage* is not in :attr:`supported_stages`. + """Raise ``ValueError`` if *stage* is not in `supported_stages`. Args: stage: Requested execution stage. Raises: - ValueError: If :attr:`supported_stages` is non-empty and *stage* is absent. + ValueError: If `supported_stages` is non-empty and *stage* is absent. """ if self.supported_stages and stage not in self.supported_stages: raise ValueError( @@ -49,8 +49,8 @@ def run( """Execute the guardrail evaluation. Called by the ``@guardrail`` decorator at each function invocation. - Subclasses override this via :class:`BuiltInGuardrailValidator` or - :class:`CustomGuardrailValidator`. + Subclasses override this via `BuiltInGuardrailValidator` or + `CustomGuardrailValidator`. Raises: NotImplementedError: Always — subclass one of the two ABCs instead. @@ -64,11 +64,11 @@ def run( class BuiltInGuardrailValidator(GuardrailValidatorBase, ABC): """Base for validators that delegate to the UiPath Guardrails API. - Subclass this and implement :meth:`get_built_in_guardrail` to create an + Subclass this and implement `get_built_in_guardrail()` to create an API-backed guardrail validator (e.g. PII detection, prompt injection). - Example:: - + Example: + ```python class MyValidator(BuiltInGuardrailValidator): def get_built_in_guardrail(self, name, description, enabled_for_evals): return BuiltInValidatorGuardrail( @@ -76,6 +76,7 @@ def get_built_in_guardrail(self, name, description, enabled_for_evals): name=name, ... ) + ``` """ @abstractmethod @@ -93,7 +94,7 @@ def get_built_in_guardrail( enabled_for_evals: Whether active in evaluation scenarios. Returns: - :class:`BuiltInValidatorGuardrail` ready to be sent to the API. + `BuiltInValidatorGuardrail` ready to be sent to the API. """ ... @@ -123,11 +124,11 @@ def run( class CustomGuardrailValidator(GuardrailValidatorBase, ABC): """Base for validators that run entirely in-process. - Subclass this and implement :meth:`evaluate` to create a local guardrail + Subclass this and implement `evaluate()` to create a local guardrail validator that requires no UiPath API call. - Example:: - + Example: + ```python class ProfanityValidator(CustomGuardrailValidator): BANNED = {"badword"} @@ -139,6 +140,7 @@ def evaluate(self, data, stage, input_data, output_data): reason="Profanity detected", ) return GuardrailValidationResult(result=GuardrailValidationResultType.PASSED) + ``` """ @abstractmethod @@ -152,7 +154,7 @@ def evaluate( """Perform local validation without a UiPath API call. Return a result with ``VALIDATION_FAILED`` to **trigger** the guardrail - (causing the configured :class:`~uipath.platform.guardrails.decorators.GuardrailAction` + (causing the configured `GuardrailAction` to fire), or ``PASSED`` to let execution continue unchanged. Args: @@ -162,7 +164,7 @@ def evaluate( output_data: Normalised function output dict, or ``None`` at PRE stage. Returns: - :class:`~uipath.core.guardrails.GuardrailValidationResult` — + `GuardrailValidationResult` — return ``VALIDATION_FAILED`` to activate the guardrail, ``PASSED`` to allow execution to continue. """ @@ -178,5 +180,5 @@ def run( input_data: "dict[str, Any] | None", output_data: "dict[str, Any] | None", ) -> GuardrailValidationResult: - """Delegate to :meth:`evaluate`.""" + """Delegate to `evaluate()`.""" return self.evaluate(data, stage, input_data, output_data) diff --git a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/byo.py b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/byo.py index 425a84654..4eee1f36e 100644 --- a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/byo.py +++ b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/byo.py @@ -27,8 +27,8 @@ class ByoValidator(BuiltInGuardrailValidator): Supported at all stages — BYO validator capabilities are connector-defined and cannot be known statically, so no stage restriction is applied here. - Example:: - + Example: + ```python from uipath.platform.guardrails.decorators import ( BlockAction, ByoValidator, @@ -40,6 +40,7 @@ class ByoValidator(BuiltInGuardrailValidator): @guardrail(validator=byog_harmful_content, action=BlockAction()) def summarize(text: str) -> str: ... + ``` Args: validator_name: The BYOG configuration's validator name @@ -70,7 +71,7 @@ def get_built_in_guardrail( description: str | None, enabled_for_evals: bool, ) -> BuiltInValidatorGuardrail: - """Build a BYOG :class:`BuiltInValidatorGuardrail`. + """Build a BYOG `BuiltInValidatorGuardrail`. Args: name: Name for the guardrail. @@ -78,7 +79,7 @@ def get_built_in_guardrail( enabled_for_evals: Whether active in evaluation scenarios. Returns: - Configured :class:`BuiltInValidatorGuardrail` referencing the BYOG + Configured `BuiltInValidatorGuardrail` referencing the BYOG configuration via ``byoValidatorName``. """ return BuiltInValidatorGuardrail( diff --git a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/custom.py b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/custom.py index df6549600..ad093443c 100644 --- a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/custom.py +++ b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/custom.py @@ -14,7 +14,7 @@ RuleFunction = ( Callable[[dict[str, Any]], bool] | Callable[[dict[str, Any], dict[str, Any]], bool] ) -"""Type alias for custom rule functions passed to :class:`CustomValidator`. +"""Type alias for custom rule functions passed to `CustomValidator`. The rule must return ``True`` to **trigger** the guardrail (i.e. signal a violation that causes the configured action to fire), or ``False`` to let @@ -23,7 +23,7 @@ It accepts either one parameter (the input or output dict) or two parameters (input dict, output dict — POST stage only). -Examples:: +Examples: # Triggered when "donkey" appears in the joke argument CustomValidator(lambda args: "donkey" in args.get("joke", "").lower()) @@ -44,11 +44,11 @@ class CustomValidator(CustomGuardrailValidator): The *rule* is called with the collected parameter dict (PRE stage) or the serialised return-value dict (POST stage). It must return ``True`` to **activate** the guardrail — i.e. to signal a violation and invoke the - configured :class:`~uipath.platform.guardrails.decorators.GuardrailAction`. + configured `GuardrailAction`. Return ``False`` (or any falsy value) to let execution continue unchanged. Args: - rule: A :data:`RuleFunction` that returns ``True`` to trigger the + rule: A `RuleFunction` that returns ``True`` to trigger the guardrail. Must accept 1 or 2 parameters. Raises: @@ -86,7 +86,7 @@ def evaluate( output_data: Collected function output dict, or ``None`` at PRE stage. Returns: - :class:`~uipath.core.guardrails.GuardrailValidationResult` — + `GuardrailValidationResult` — ``VALIDATION_FAILED`` when the rule returns ``True`` (guardrail triggered), ``PASSED`` otherwise. """ diff --git a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/harmful_content.py b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/harmful_content.py index d186341d7..f88500339 100644 --- a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/harmful_content.py +++ b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/harmful_content.py @@ -19,7 +19,7 @@ class HarmfulContentValidator(BuiltInGuardrailValidator): Supported at all stages (PRE, POST, PRE_AND_POST). Args: - entities: One or more :class:`~uipath.platform.guardrails.decorators.HarmfulContentEntity` + entities: One or more `HarmfulContentEntity` instances specifying which harmful content categories to detect and their severity thresholds. @@ -39,7 +39,7 @@ def get_built_in_guardrail( description: str | None, enabled_for_evals: bool, ) -> BuiltInValidatorGuardrail: - """Build a harmful content :class:`BuiltInValidatorGuardrail`. + """Build a harmful content `BuiltInValidatorGuardrail`. Args: name: Name for the guardrail. @@ -47,7 +47,7 @@ def get_built_in_guardrail( enabled_for_evals: Whether active in evaluation scenarios. Returns: - Configured :class:`BuiltInValidatorGuardrail` for harmful content detection. + Configured `BuiltInValidatorGuardrail` for harmful content detection. """ entity_names = [entity.name for entity in self.entities] entity_thresholds: dict[str, Any] = { diff --git a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/intellectual_property.py b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/intellectual_property.py index 8a18e6a37..90227a851 100644 --- a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/intellectual_property.py +++ b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/intellectual_property.py @@ -39,7 +39,7 @@ def get_built_in_guardrail( description: str | None, enabled_for_evals: bool, ) -> BuiltInValidatorGuardrail: - """Build an intellectual property :class:`BuiltInValidatorGuardrail`. + """Build an intellectual property `BuiltInValidatorGuardrail`. Args: name: Name for the guardrail. @@ -47,7 +47,7 @@ def get_built_in_guardrail( enabled_for_evals: Whether active in evaluation scenarios. Returns: - Configured :class:`BuiltInValidatorGuardrail` for IP detection. + Configured `BuiltInValidatorGuardrail` for IP detection. """ return BuiltInValidatorGuardrail( id=str(uuid4()), diff --git a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/llm_as_judge.py b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/llm_as_judge.py index f639a6ef3..42772d76a 100644 --- a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/llm_as_judge.py +++ b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/llm_as_judge.py @@ -102,7 +102,7 @@ def get_built_in_guardrail( description: str | None, enabled_for_evals: bool, ) -> BuiltInValidatorGuardrail: - """Build an LLM-as-judge :class:`BuiltInValidatorGuardrail`. + """Build an LLM-as-judge `BuiltInValidatorGuardrail`. Args: name: Name for the guardrail. @@ -110,7 +110,7 @@ def get_built_in_guardrail( enabled_for_evals: Whether active in evaluation scenarios. Returns: - Configured :class:`BuiltInValidatorGuardrail` for llm_as_judge. + Configured `BuiltInValidatorGuardrail` for llm_as_judge. """ validator_parameters: list[Any] = [ TextParameterValue( diff --git a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/pii.py b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/pii.py index 64d0a47aa..a270fcda5 100644 --- a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/pii.py +++ b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/pii.py @@ -19,7 +19,7 @@ class PIIValidator(BuiltInGuardrailValidator): Supported at all stages. Args: - entities: One or more :class:`~uipath.platform.guardrails.decorators.PIIDetectionEntity` + entities: One or more `PIIDetectionEntity` instances specifying which PII types to detect and their confidence thresholds. Raises: @@ -38,7 +38,7 @@ def get_built_in_guardrail( description: str | None, enabled_for_evals: bool, ) -> BuiltInValidatorGuardrail: - """Build a PII detection :class:`BuiltInValidatorGuardrail`. + """Build a PII detection `BuiltInValidatorGuardrail`. Args: name: Name for the guardrail. @@ -46,7 +46,7 @@ def get_built_in_guardrail( enabled_for_evals: Whether active in evaluation scenarios. Returns: - Configured :class:`BuiltInValidatorGuardrail` for PII detection. + Configured `BuiltInValidatorGuardrail` for PII detection. """ entity_names = [entity.name for entity in self.entities] entity_thresholds: dict[str, Any] = { diff --git a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/prompt_injection.py b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/prompt_injection.py index b0943b396..bd45f4264 100644 --- a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/prompt_injection.py +++ b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/prompt_injection.py @@ -37,7 +37,7 @@ def get_built_in_guardrail( description: str | None, enabled_for_evals: bool, ) -> BuiltInValidatorGuardrail: - """Build a prompt injection :class:`BuiltInValidatorGuardrail`. + """Build a prompt injection `BuiltInValidatorGuardrail`. Args: name: Name for the guardrail. @@ -45,7 +45,7 @@ def get_built_in_guardrail( enabled_for_evals: Whether active in evaluation scenarios. Returns: - Configured :class:`BuiltInValidatorGuardrail` for prompt injection. + Configured `BuiltInValidatorGuardrail` for prompt injection. """ return BuiltInValidatorGuardrail( id=str(uuid4()), diff --git a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/user_prompt_attacks.py b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/user_prompt_attacks.py index 7275acc25..9abdd27c5 100644 --- a/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/user_prompt_attacks.py +++ b/packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/user_prompt_attacks.py @@ -23,7 +23,7 @@ def get_built_in_guardrail( description: str | None, enabled_for_evals: bool, ) -> BuiltInValidatorGuardrail: - """Build a user prompt attacks :class:`BuiltInValidatorGuardrail`. + """Build a user prompt attacks `BuiltInValidatorGuardrail`. Args: name: Name for the guardrail. @@ -31,7 +31,7 @@ def get_built_in_guardrail( enabled_for_evals: Whether active in evaluation scenarios. Returns: - Configured :class:`BuiltInValidatorGuardrail` for user prompt attacks. + Configured `BuiltInValidatorGuardrail` for user prompt attacks. """ return BuiltInValidatorGuardrail( id=str(uuid4()), diff --git a/packages/uipath-platform/src/uipath/platform/orchestrator/_assets_service.py b/packages/uipath-platform/src/uipath/platform/orchestrator/_assets_service.py index 2e673fb7c..02df7f67b 100644 --- a/packages/uipath-platform/src/uipath/platform/orchestrator/_assets_service.py +++ b/packages/uipath-platform/src/uipath/platform/orchestrator/_assets_service.py @@ -317,7 +317,7 @@ async def _resolve_robot_key_async( folder_key: Optional[str] = None, folder_path: Optional[str] = None, ) -> Optional[str]: - """Async variant of :meth:`_resolve_robot_key`.""" + """Async variant of `_resolve_robot_key()`.""" try: robot_key = self._execution_context.robot_key except ValueError: diff --git a/packages/uipath/src/uipath/_cli/_governance/__init__.py b/packages/uipath/src/uipath/_cli/_governance/__init__.py index fc49b92a1..b47f52f9b 100644 --- a/packages/uipath/src/uipath/_cli/_governance/__init__.py +++ b/packages/uipath/src/uipath/_cli/_governance/__init__.py @@ -1,14 +1,14 @@ """CLI-side governance helpers. Host-only glue that turns provider responses into inputs the runtime -consumes. Owns the YAML → :class:`PolicyIndex` compiler (the runtime +consumes. Owns the YAML → `PolicyIndex` compiler (the runtime layer stays format-agnostic and only accepts a compiled index). Public helpers: -- :func:`build_policy_index_from_yaml` — parse a YAML policy pack (as - returned by :meth:`GovernancePolicyProvider.get_policy_async`) into - a :class:`uipath.runtime.governance.native.PolicyIndex`. +- `build_policy_index_from_yaml()` — parse a YAML policy pack (as + returned by `GovernancePolicyProvider.get_policy_async()`) into + a `uipath.runtime.governance.native.PolicyIndex`. """ from .yaml_index import build_policy_index_from_yaml diff --git a/packages/uipath/src/uipath/_cli/_governance/yaml_index.py b/packages/uipath/src/uipath/_cli/_governance/yaml_index.py index 4da02a276..c3c7abb3d 100644 --- a/packages/uipath/src/uipath/_cli/_governance/yaml_index.py +++ b/packages/uipath/src/uipath/_cli/_governance/yaml_index.py @@ -1,4 +1,4 @@ -"""YAML → :class:`PolicyIndex` compiler. +"""YAML → `PolicyIndex` compiler. Lives CLI-side so the runtime layer never has to depend on ``pyyaml`` or know about the wire policy format — the runtime consumes compiled @@ -56,11 +56,11 @@ def build_policy_index_from_yaml(yaml_text: str) -> PolicyIndex: - """Parse YAML policy packs into a :class:`PolicyIndex`. + """Parse YAML policy packs into a `PolicyIndex`. Unknown check types and malformed rules are skipped with a debug log (partial packs preferred over failing the whole load); malformed - YAML at the document level raises :class:`yaml.YAMLError`. + YAML at the document level raises `yaml.YAMLError`. """ index = PolicyIndex() documents = list(yaml.safe_load_all(yaml_text)) @@ -189,8 +189,8 @@ def _build_checks( # Per-check-type condition builders # # Each returns ``(conditions, default_message)`` given the YAML entry for -# one check. The main :func:`_build_check` picks the right builder from -# :data:`_CHECK_BUILDERS` and layers action / logic / message resolution +# one check. The main `_build_check()` picks the right builder from +# `_CHECK_BUILDERS` and layers action / logic / message resolution # on top — keeping the dispatch flat instead of one giant if/elif chain. # --------------------------------------------------------------------------- @@ -361,7 +361,7 @@ def _gt_conditions_from_keys( # check_type → builder. ``guardrail_fallback`` is handled inline in -# :func:`_build_check` because it needs the rule-level flags. +# `_build_check()` because it needs the rule-level flags. _CHECK_BUILDERS: dict[str, Callable[[dict[str, Any]], tuple[list[Condition], str]]] = { "regex": _build_regex_conditions, "budget": _build_budget_conditions, @@ -462,10 +462,10 @@ def _build_check( """Build one Check from a YAML check entry. Delegates per-check-type condition-building to the small helpers - above (dispatched via :data:`_CHECK_BUILDERS`); the ``guardrail_fallback`` + above (dispatched via `_CHECK_BUILDERS`); the ``guardrail_fallback`` branch is inline because it needs the rule-level ``mapped_to_uipath`` / ``policy_enabled`` flags threaded in from - :func:`_build_rule`. Unknown check types are skipped. + `_build_rule()`. Unknown check types are skipped. """ raw_conditions = data.get("conditions") has_explicit_conditions = _has_explicit_conditions(raw_conditions) diff --git a/packages/uipath/src/uipath/_cli/_governance_bootstrap.py b/packages/uipath/src/uipath/_cli/_governance_bootstrap.py index 675b42721..3f51b98eb 100644 --- a/packages/uipath/src/uipath/_cli/_governance_bootstrap.py +++ b/packages/uipath/src/uipath/_cli/_governance_bootstrap.py @@ -1,7 +1,7 @@ """Shared host-side governance bootstrap for ``uipath run`` / ``uipath debug``. Framework and agent-type labels are forwarded from -:class:`UiPathRuntimeFactorySettings` — each factory advertises its +`UiPathRuntimeFactorySettings` — each factory advertises its own; the CLI never classifies the runtime. """ @@ -46,7 +46,7 @@ class GovernanceBootstrap: """Governance wiring for one CLI run. ``dispose`` is idempotent, never raises, and drains the track-event - dispatcher; call it from a ``finally``. An :mod:`atexit` fallback + dispatcher; call it from a ``finally``. An `atexit` fallback covers the case where the caller misses it. """ @@ -82,13 +82,13 @@ async def resolve_governance( """Fetch policy + build the governance stack, or ``None`` when disabled. ``agent_framework`` and ``agent_type`` are forwarded from - :class:`UiPathRuntimeFactorySettings` and stamped on every audit + `UiPathRuntimeFactorySettings` and stamped on every audit event; ``None`` becomes ``"unknown"``. ``is_conversational`` is derived by the caller from runtime context (``bool(ctx.conversation_id)``): ``True`` for a run inside a CAS conversation, ``False`` otherwise. The value is forwarded verbatim - to :class:`PolicyContext` so the backend can select the + to `PolicyContext` so the backend can select the conversational or autonomous policy view. """ if not is_governance_enabled(): diff --git a/packages/uipath/src/uipath/agent/models/agent.py b/packages/uipath/src/uipath/agent/models/agent.py index 2561fadd9..303a35c4d 100644 --- a/packages/uipath/src/uipath/agent/models/agent.py +++ b/packages/uipath/src/uipath/agent/models/agent.py @@ -494,7 +494,7 @@ class DynamicToolsMode(str, CaseInsensitiveEnum): Deprecated: kept for backwards compatibility with older ``agent.json`` files that still serialize the ``dynamicTools`` field. New code should use - :class:`ToolsConfiguration` (see ``AgentMcpResourceConfig.tools_configuration``). + `ToolsConfiguration` (see ``AgentMcpResourceConfig.tools_configuration``). """ NONE = "none" diff --git a/packages/uipath/src/uipath/eval/evaluators/base_dataset_evaluator.py b/packages/uipath/src/uipath/eval/evaluators/base_dataset_evaluator.py index 5f302b076..0b47fa9e2 100644 --- a/packages/uipath/src/uipath/eval/evaluators/base_dataset_evaluator.py +++ b/packages/uipath/src/uipath/eval/evaluators/base_dataset_evaluator.py @@ -22,7 +22,7 @@ class BaseDatasetEvaluator(ABC): """Abstract base for dataset-level evaluators. - Constructed from an :class:`AggregatorSpec`, the source evaluator's name, + Constructed from an `AggregatorSpec`, the source evaluator's name, and the class vocabulary of the parent per-datapoint evaluator. Classes live on the evaluator config (not the spec) — every aggregator on the same evaluator operates on the same vocabulary. diff --git a/packages/uipath/src/uipath/eval/evaluators/dataset_evaluator_factory.py b/packages/uipath/src/uipath/eval/evaluators/dataset_evaluator_factory.py index d30a5748b..ba4eca50d 100644 --- a/packages/uipath/src/uipath/eval/evaluators/dataset_evaluator_factory.py +++ b/packages/uipath/src/uipath/eval/evaluators/dataset_evaluator_factory.py @@ -1,9 +1,9 @@ """Factory that instantiates dataset-level evaluators from aggregator specs. -Dataset evaluators are built from a self-contained :class:`AggregatorSpec` +Dataset evaluators are built from a self-contained `AggregatorSpec` embedded in a per-datapoint classification evaluator's config, plus the source evaluator's name (supplied by the runtime when walking those configs). All -three aggregator types share a single :class:`ClassificationDatasetEvaluator` +three aggregator types share a single `ClassificationDatasetEvaluator` implementation that dispatches on ``spec.type`` internally. """ @@ -23,7 +23,7 @@ def build_dataset_evaluator( """Build a dataset evaluator instance from an aggregator spec. Args: - spec: A validated :class:`AggregatorSpec` (precision / recall / fscore). + spec: A validated `AggregatorSpec` (precision / recall / fscore). source_evaluator: Name of the per-datapoint evaluator whose results this aggregator consumes. classes: The class vocabulary from the parent evaluator's config. Shared @@ -52,7 +52,7 @@ def dataset_result_key( ``{source}::{type}``, extended with ``.{averaging}`` (and ``.fb{f_value}`` for fscore) when the same type appears more than once on one source. - Callers must dedupe via :func:`unique_aggregator_specs` first — after that, + Callers must dedupe via `unique_aggregator_specs()` first — after that, duplicate types always differ in averaging or f_value. """ key = f"{source_evaluator}::{spec.type}" diff --git a/packages/uipath/src/uipath/eval/runtime/runtime.py b/packages/uipath/src/uipath/eval/runtime/runtime.py index 7e2826d34..ff69d300c 100644 --- a/packages/uipath/src/uipath/eval/runtime/runtime.py +++ b/packages/uipath/src/uipath/eval/runtime/runtime.py @@ -243,7 +243,7 @@ def compute_dataset_evaluator_results( set. Their configs may carry ``aggregators`` lists. Returns: - Dict keyed by :func:`dataset_result_key` (same scheme as the platform + Dict keyed by `dataset_result_key()` (same scheme as the platform worker), with each value's ``details`` dumped to the camelCase wire shape. Exact-duplicate specs are deduped; aggregators whose source produced no results still emit a zeroed result. diff --git a/packages/uipath/src/uipath/functions/debug.py b/packages/uipath/src/uipath/functions/debug.py index a79835e3d..c464e83e8 100644 --- a/packages/uipath/src/uipath/functions/debug.py +++ b/packages/uipath/src/uipath/functions/debug.py @@ -138,7 +138,7 @@ def __init__( def _parse_breakpoints(self, breakpoints: list[str]) -> None: """Parse breakpoint strings into *file → line-numbers* mappings. - Supported formats:: + Supported formats: "42" → line 42 in the entrypoint file "main.py:42" → line 42 in main.py (resolved relative to cwd) diff --git a/packages/uipath/src/uipath/functions/factory.py b/packages/uipath/src/uipath/functions/factory.py index 3ef7f5b37..5bbde24d9 100644 --- a/packages/uipath/src/uipath/functions/factory.py +++ b/packages/uipath/src/uipath/functions/factory.py @@ -18,7 +18,7 @@ logger = logging.getLogger(__name__) # Wire labels this factory advertises via -# :class:`UiPathRuntimeFactorySettings`. The runtime does not enumerate +# `UiPathRuntimeFactorySettings`. The runtime does not enumerate # valid values -- each factory owns its own vocabulary and hosts # forward them verbatim to telemetry / audit consumers. _AGENT_TYPE_CODED = "uipath_coded"