ds_protocol_graphql_py_lib ========================== .. py:module:: ds_protocol_graphql_py_lib .. autoapi-nested-parse:: **File:** ``__init__.py`` **Region:** ``ds-protocol-graphql-py-lib`` Description ----------- A Python package from the ds-protocol-graphql-py-lib library. .. rubric:: Example .. code-block:: python from ds_protocol_graphql_py_lib import __version__ print(f"Package version: {__version__}") Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/ds_protocol_graphql_py_lib/dataset/index /autoapi/ds_protocol_graphql_py_lib/enums/index /autoapi/ds_protocol_graphql_py_lib/serde/index Attributes ---------- .. autoapisummary:: ds_protocol_graphql_py_lib.__version__ Classes ------- .. autoapisummary:: ds_protocol_graphql_py_lib.GraphqlDeserializer ds_protocol_graphql_py_lib.GraphqlDataset ds_protocol_graphql_py_lib.GraphqlDatasetSettings Package Contents ---------------- .. py:class:: GraphqlDeserializer Bases: :py:obj:`ds_resource_plugin_py_lib.common.serde.deserialize.PandasDeserializer` Deserializer for GraphQL API responses. Handles various GraphQL response patterns: - Direct arrays: {"data": {"users": [...]}} - Relay connections: {"data": {"users": {"edges": [{"node": {...}}]}}} - Single objects: {"data": {"user": {...}}} - Introspection queries: {"data": {"__type": {"fields": [...]}}} .. py:method:: deserialize_graphql(data: Any) -> pandas.DataFrame Deserialize GraphQL response to pandas DataFrame. :param data: GraphQL response dict or raw data :returns: DataFrame containing the extracted data .. py:method:: _parse_graphql_data(data: Any) -> pandas.DataFrame Parse GraphQL data structure into DataFrame. Handles nested structures and various GraphQL response patterns. :param data: The data portion of the GraphQL response :returns: DataFrame with the extracted data .. py:method:: _handle_nested_dict(nested_value: dict[str, Any]) -> pandas.DataFrame Handle nested dict - determine if it's a pure array container or single object. :param nested_value: The nested dictionary to analyze :returns: DataFrame with appropriate data extraction .. py:method:: _extract_relay_nodes(data: dict[str, Any]) -> pandas.DataFrame Extract nodes from Relay-style pagination structure. :param data: Dict containing "edges" key with Relay pagination structure :returns: DataFrame with nodes extracted from edges .. py:class:: GraphqlDataset Bases: :py:obj:`ds_resource_plugin_py_lib.common.resource.dataset.TabularDataset`\ [\ :py:obj:`ds_protocol_http_py_lib.dataset.http.HttpLinkedServiceType`\ , :py:obj:`GraphqlDatasetSettingsType`\ , :py:obj:`ds_resource_plugin_py_lib.common.serde.serialize.PandasSerializer`\ , :py:obj:`ds_protocol_graphql_py_lib.serde.deserializer.GraphqlDeserializer`\ ], :py:obj:`Generic`\ [\ :py:obj:`ds_protocol_http_py_lib.dataset.http.HttpLinkedServiceType`\ , :py:obj:`GraphqlDatasetSettingsType`\ ] Represent Graphql dataset. .. py:attribute:: settings :type: GraphqlDatasetSettingsType .. py:attribute:: linked_service :type: ds_protocol_http_py_lib.dataset.http.HttpLinkedServiceType .. py:attribute:: deserializer :type: ds_protocol_graphql_py_lib.serde.deserializer.GraphqlDeserializer | None .. py:property:: type :type: ds_protocol_graphql_py_lib.enums.ResourceType Get the type of the dataset. .. py:property:: supports_checkpoint :type: bool Indicate whether this provider supports incremental loads via checkpointing. GraphQL provider does not yet support checkpoint-based incremental loads. All reads are full loads. :returns: False, indicating checkpointing is not supported. .. py:method:: read() -> None Read Graphql dataset. Sends a GraphQL query to the endpoint with the query, variables, and operation name specified in settings.read. Populates self.output with the result as a DataFrame. Handles various GraphQL response patterns via GraphqlDeserializer: - Direct arrays: {"data": {"users": [...]}} - Relay connections: {"data": {"users": {"edges": [{"node": {...}}]}}} - Single objects: {"data": {"user": {...}}} :returns: None. The result is stored in self.output as a DataFrame. :raises ConnectionError: If the linked service connection is not initialized. :raises ReadError: If read settings are not provided or if the GraphQL query fails. .. py:method:: _check_for_graphql_read_error(response_data: dict[str, Any]) -> None :staticmethod: .. py:method:: create() -> None Create new rows in the GraphQL endpoint using mutations. Sends all rows in a single atomic GraphQL mutation request. Populates self.output with the created rows. :returns: None. The result is stored in self.output as a DataFrame. :raises ConnectionError: If the linked service connection is not initialized. :raises CreateError: If create settings are not provided or if the GraphQL mutation fails. .. py:method:: update() -> None Update entity using Graphql. .. py:method:: upsert() -> None Upsert entity using Graphql. .. py:method:: delete() -> None Delete specific rows from the GraphQL endpoint using mutations. Sends all rows in a single atomic GraphQL mutation request. Populates self.output with the deleted rows. :returns: None. The result is stored in self.output as a DataFrame. :raises ConnectionError: If the linked service connection is not initialized. :raises DeleteError: If delete settings are not provided, if identity columns are missing, or if the GraphQL mutation fails. .. py:method:: purge() -> NoReturn Purge entity using Graphql. .. py:method:: rename() -> NoReturn Rename entity using Graphql. .. py:method:: list() -> None Discover available resources in the GraphQL schema via introspection. Executes a GraphQL introspection query to fetch all available queries and their arguments from the schema. Populates self.output with a DataFrame containing resource metadata (name, type, description, etc.). :returns: None. The result is stored in self.output as a DataFrame. :raises ConnectionError: If the linked service connection is not initialized. :raises ListError: If the GraphQL introspection query fails. .. py:method:: close() -> None Just to satisfy the contract - GraphQL dataset does not maintain persistent connections that require cleanup. :returns: None .. py:method:: _validate_create_settings() -> None Validate create settings are properly configured. :returns: if settings are valid. :rtype: None :raises CreateError: If any required create settings are missing or invalid. .. py:class:: GraphqlDatasetSettings Bases: :py:obj:`ds_resource_plugin_py_lib.common.resource.dataset.DatasetSettings` The object containing the settings of the dataset. .. py:attribute:: url :type: str The URL of the GraphQL endpoint to connect to. This is the base URL where the GraphQL API is hosted. .. py:attribute:: primary_keys :type: list[str] | None :value: None Optional list of column names that serve as primary keys for the dataset. This can be used for operations that require unique identification of rows. .. py:attribute:: headers :type: dict[str, str] | None :value: None Optional HTTP headers to include in requests to the GraphQL endpoint, such as authentication tokens or content type. .. py:attribute:: read :type: GraphqlReadSettings | None :value: None Settings for read operations. .. py:attribute:: delete :type: GraphqlDeleteSettings | None :value: None Settings for delete operations. .. py:attribute:: create :type: GraphqlCreateSettings | None :value: None Settings for create operations. .. py:data:: __version__