ds_provider_xledger_py_lib.utils ================================ .. py:module:: ds_provider_xledger_py_lib.utils .. autoapi-nested-parse:: **File:** ``__init__.py`` **Region:** ``ds_provider_xledger_py_lib/utils`` Description ----------- Utility helpers for provider internals. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/ds_provider_xledger_py_lib/utils/dataframe/index /autoapi/ds_provider_xledger_py_lib/utils/graphql/index /autoapi/ds_provider_xledger_py_lib/utils/introspection/index /autoapi/ds_provider_xledger_py_lib/utils/query_builder/index /autoapi/ds_provider_xledger_py_lib/utils/rules/index Classes ------- .. autoapisummary:: ds_provider_xledger_py_lib.utils.EntryPointMetaData ds_provider_xledger_py_lib.utils.IntrospectionService ds_provider_xledger_py_lib.utils.MetaData ds_provider_xledger_py_lib.utils.GraphQLErrorRuleBook ds_provider_xledger_py_lib.utils.Rule Functions --------- .. autoapisummary:: ds_provider_xledger_py_lib.utils.raise_for_graphql_errors ds_provider_xledger_py_lib.utils.build_mutation ds_provider_xledger_py_lib.utils.build_query ds_provider_xledger_py_lib.utils.build_variables Package Contents ---------------- .. py:function:: raise_for_graphql_errors(*, body: Any) -> dict[str, Any] Raise typed DS exceptions for GraphQL payload errors. GraphQL servers may return HTTP 200 while reporting failures under an ``errors`` field in the response payload. :param body: The GraphQL response body to inspect. :returns: The original GraphQL response body when no error is present. .. py:class:: EntryPointMetaData Container for all loaded operations for one entrypoint. .. py:attribute:: entrypoint :type: str .. py:attribute:: operations :type: dict[ds_provider_xledger_py_lib.enums.OperationType, MetaData] .. py:method:: get(*, operation: ds_provider_xledger_py_lib.enums.OperationType) -> MetaData Return metadata for a specific operation. :param operation: Operation to resolve. :returns: Metadata for the requested operation. :raises NotSupportedError: If metadata for the operation is unavailable. .. py:property:: read :type: MetaData | None Metadata for read operation, when available. .. py:property:: create :type: MetaData | None Metadata for create operation, when available. .. py:property:: update :type: MetaData | None Metadata for update operation, when available. .. py:property:: delete :type: MetaData | None Metadata for delete operation, when available. .. py:class:: IntrospectionService Load and cache entrypoint metadata for dataset lifecycle reuse. .. py:attribute:: entrypoint :type: str .. py:attribute:: _metadata :type: EntryPointMetaData | None :value: None .. py:property:: metadata :type: EntryPointMetaData Loaded entrypoint metadata. :returns: Cached metadata snapshot for the configured entrypoint. .. py:method:: load() -> EntryPointMetaData Load metadata snapshot if needed and return cached value. :returns: Cached metadata snapshot for the configured entrypoint. .. py:method:: load_metadata(*, operation: ds_provider_xledger_py_lib.enums.OperationType) -> MetaData Return metadata for a single operation. :param operation: Operation to resolve. :returns: Metadata for the requested operation. .. py:class:: MetaData Bases: :py:obj:`ds_common_serde_py_lib.serializable.Serializable` Operation-level metadata plus packaged GraphQL query template. .. py:attribute:: name :type: str .. py:attribute:: type :type: str .. py:attribute:: description :type: str .. py:attribute:: fields :type: list[MetaField] .. py:attribute:: query :type: str .. py:attribute:: supportPagination :type: bool :value: False .. py:function:: build_mutation(*, metadata: ds_provider_xledger_py_lib.utils.introspection.MetaData, variables: dict[str, Any], return_fields: list[str] | None = None) -> str Build a rendered GraphQL mutation for write operations. :param metadata: Operation metadata. :param variables: Resolved variables required by the mutation template. :param return_fields: Optional explicit fields to return. :returns: GraphQL mutation text. .. py:function:: build_query(*, metadata: ds_provider_xledger_py_lib.utils.introspection.MetaData, **kwargs: Any) -> str Build a rendered GraphQL query for read operations. :param metadata: Operation metadata. :param \*\*kwargs: Query keyword arguments. ``fields`` controls selection set. :returns: GraphQL query text. .. py:function:: build_variables(*, obj: pandas.DataFrame, operation: ds_provider_xledger_py_lib.enums.OperationType, metadata: ds_provider_xledger_py_lib.utils.introspection.MetaData) -> dict[str, Any] Build GraphQL variables payload for an operation. :param obj: Input dataframe. :param operation: Dataset operation type. :param metadata: Loaded operation metadata. :returns: Variables dictionary matching the query template. .. py:class:: GraphQLErrorRuleBook Registry for GraphQL-to-provider exception mapping rules. .. py:attribute:: _rules :type: tuple[Rule, Ellipsis] .. py:method:: resolve(*, code: str, extension_code: str, error_message: str) -> ResolvedRule | None :classmethod: Resolve a GraphQL error to a mapped provider exception. :param code: The error code to resolve. :param extension_code: The extension code to resolve. :param error_message: The error message to resolve. :returns: The resolved rule. .. py:method:: _match_source(*, rule: Rule, message_lower: str, code: str, extension_code: str) -> str | None :staticmethod: Return the source used to match the provided rule. :param rule: The rule to match. :param message_lower: The lowercased error message to match. :param code: The error code to match. :param extension_code: The extension code to match. :returns: A source label when the current error matches the provided rule. .. py:class:: Rule Bases: :py:obj:`NamedTuple` Simple rule for mapping GraphQL errors to provider exceptions. .. py:attribute:: exc_cls :type: type[Exception] .. py:attribute:: code :type: str | None :value: None .. py:attribute:: extension_code :type: str | None :value: None .. py:attribute:: message_keywords :type: tuple[str, Ellipsis] :value: () .. py:attribute:: default_message :type: str | None :value: None