ds_protocol_http_py_lib.dataset.http
====================================

.. py:module:: ds_protocol_http_py_lib.dataset.http

.. autoapi-nested-parse::

   **File:** ``http.py``
   **Region:** ``ds_protocol_http_py_lib/dataset/http``

   HTTP Dataset

   This module implements a dataset for HTTP APIs.

   .. rubric:: Example

   >>> from ds_protocol_http_py_lib.enums import AuthType
   >>> from ds_protocol_http_py_lib.linked_service import OAuth2AuthSettings
   >>> dataset = HttpDataset(
   ...     deserializer=PandasDeserializer(format=DatasetStorageFormatType.JSON),
   ...     serializer=PandasSerializer(format=DatasetStorageFormatType.JSON),
   ...     settings=HttpDatasetSettings(
   ...         url="https://api.example.com/data",
   ...         method=HttpMethod.GET,
   ...     ),
   ...     linked_service=HttpLinkedService(
   ...         settings=HttpLinkedServiceSettings(
   ...             host="api.example.com",
   ...             auth_type=AuthType.OAUTH2,
   ...             oauth2=OAuth2AuthSettings(
   ...                 token_endpoint="https://auth.example.com/token",
   ...                 client_id="my-client",
   ...                 client_secret="secret",
   ...             ),
   ...         ),
   ...     ),
   ... )
   >>> dataset.read()
   >>> data = dataset.output



Attributes
----------

.. autoapisummary::

   ds_protocol_http_py_lib.dataset.http.logger
   ds_protocol_http_py_lib.dataset.http.HttpDatasetSettingsType
   ds_protocol_http_py_lib.dataset.http.HttpLinkedServiceType


Classes
-------

.. autoapisummary::

   ds_protocol_http_py_lib.dataset.http.HttpDatasetSettings
   ds_protocol_http_py_lib.dataset.http.HttpDataset


Module Contents
---------------

.. py:data:: logger

.. py:class:: HttpDatasetSettings

   Bases: :py:obj:`ds_resource_plugin_py_lib.common.resource.dataset.DatasetSettings`


   Settings for HTTP dataset.


   .. py:attribute:: method
      :type:  ds_protocol_http_py_lib.enums.HttpMethod

      The HTTP method to use.


   .. py:attribute:: url
      :type:  str

      The URL to send the request to.


   .. py:attribute:: data
      :type:  Any | None
      :value: None


      The data to send with the request.


   .. py:attribute:: json
      :type:  dict[str, Any] | None
      :value: None


      The JSON data to send with the request.


   .. py:attribute:: params
      :type:  dict[str, Any] | None
      :value: None


      The parameters to send with the request.


   .. py:attribute:: files
      :type:  list[ds_protocol_http_py_lib.models.Files] | None
      :value: None


      The multipart files to send with the request.


   .. py:attribute:: headers
      :type:  dict[str, Any] | None
      :value: None


      The headers to send with the request.


   .. py:attribute:: path_params
      :type:  dict[str, Any] | None
      :value: None


      Path parameters to interpolate into the URL template using {param} syntax.

      .. rubric:: Example

      url="https://api.example.com/documents/{document_guid}/original"
      path_params={"document_guid": "abc123"}
      # → https://api.example.com/documents/abc123/original


.. py:data:: HttpDatasetSettingsType

.. py:data:: HttpLinkedServiceType

.. py:class:: HttpDataset

   Bases: :py:obj:`ds_resource_plugin_py_lib.common.resource.dataset.TabularDataset`\ [\ :py:obj:`HttpLinkedServiceType`\ , :py:obj:`HttpDatasetSettingsType`\ , :py:obj:`ds_resource_plugin_py_lib.common.serde.serialize.PandasSerializer`\ , :py:obj:`ds_resource_plugin_py_lib.common.serde.deserialize.PandasDeserializer`\ ], :py:obj:`Generic`\ [\ :py:obj:`HttpLinkedServiceType`\ , :py:obj:`HttpDatasetSettingsType`\ ]


   Tabular dataset object which identifies data within a data store,
   such as table/csv/json/parquet/parquetdataset/ and other documents.

   The input of the dataset is a pandas DataFrame.
   The output of the dataset is a pandas DataFrame.


   .. py:attribute:: linked_service
      :type:  HttpLinkedServiceType


   .. py:attribute:: settings
      :type:  HttpDatasetSettingsType


   .. py:attribute:: serializer
      :type:  ds_resource_plugin_py_lib.common.serde.serialize.PandasSerializer | None


   .. py:attribute:: deserializer
      :type:  ds_resource_plugin_py_lib.common.serde.deserialize.PandasDeserializer | None


   .. py:property:: type
      :type: ds_protocol_http_py_lib.enums.ResourceType


      Get the type of the dataset.


   .. py:method:: _resolve_url() -> str

      Resolve the URL by substituting any path parameters.



   .. py:method:: create() -> None

      Create data at the specified endpoint.

      :param kwargs: Additional keyword arguments to pass to the request.

      :raises AuthenticationError: If the authentication fails.
      :raises AuthorizationError: If the authorization fails.
      :raises ConnectionError: If the connection fails.
      :raises CreateError: If the create error occurs.



   .. py:method:: read() -> None

      Read data from the specified endpoint.

      :param kwargs: Additional keyword arguments to pass to the request.

      :raises AuthenticationError: If the authentication fails.
      :raises AuthorizationError: If the authorization fails.
      :raises ConnectionError: If the connection fails.
      :raises ReadError: If the read error occurs.



   .. py:method:: delete() -> NoReturn

      Delete entity using http.



   .. py:method:: update() -> NoReturn

      Update entity using http.



   .. py:method:: rename() -> NoReturn

      Rename entity using http.



   .. py:method:: upsert() -> NoReturn

      Upsert entity using http.



   .. py:method:: purge() -> NoReturn

      Purge entity using http.



   .. py:method:: list() -> NoReturn

      List entity using http.



   .. py:method:: _map_files(files: collections.abc.Sequence[ds_protocol_http_py_lib.models.Files] | None) -> Any

      Convert typed `Files` descriptors into `requests` compatible `files=...`.

      `HttpDatasetSettings.files` is expected to already be deserialized
      into the correct typed model, so this method focuses purely on the
      `requests` shape conversion.



   .. py:method:: close() -> None

      Close the dataset.