From 4419f72a181f7f64bead66df96bf60e120b54957 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20H=C3=B6ffner?= Date: Wed, 17 Jul 2024 19:44:04 +0200 Subject: [PATCH] Update Docs Occurrences of requests.Response Replace all occurrences of requests.Reponse with httpx.Response. Also do some minor documentation updates, including some formatting and removal of example texts. Include :special-members: for the API interface, as the auth-parameter will be documented in the __init__ method, and the docs of the context manager for async were not published yet. Additionally, remove the intersphinx reference to requests. Unfortunately, httpx does not have an inventory file (see also [1]) [1]: https://github.com/encode/httpx/discussions/3091 Closes #198. --- pyDataverse/api.py | 162 +++++++++--------- pyDataverse/docs/source/conf.py | 1 - pyDataverse/docs/source/index.rst | 2 +- .../docs/source/user/advanced-usage.rst | 2 +- pyDataverse/docs/source/user/basic-usage.rst | 4 +- 5 files changed, 82 insertions(+), 89 deletions(-) diff --git a/pyDataverse/api.py b/pyDataverse/api.py index efd3186..2bd25dc 100644 --- a/pyDataverse/api.py +++ b/pyDataverse/api.py @@ -51,11 +51,11 @@ def __init__( ---------- base_url : str Base url for Dataverse api. - api_token : str + api_token : str | None Api token for Dataverse api. Examples - ------- + -------- Create an Api connection:: >>> from pyDataverse.api import Api @@ -115,8 +115,8 @@ def get_request(self, url, params=None, auth=False): Returns ------- - class:`requests.Response` - Response object of requests library. + httpx.Response + Response object of httpx library. """ params = {} @@ -150,16 +150,16 @@ def post_request(self, url, data=None, auth=False, params=None, files=None): Metadata as a json-formatted string. Defaults to `None`. auth : bool Should an api token be sent in the request. Defaults to `False`. - files: dict - e. g. files = {'file': open('sample_file.txt','rb')} + files : dict + e.g. :code:`files={'file': open('sample_file.txt','rb')}` params : dict Dictionary of parameters to be passed with the request. - Defaults to `None`. + Defaults to :code:`None`. Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ params = {} @@ -204,8 +204,8 @@ def put_request(self, url, data=None, auth=False, params=None): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ params = {} @@ -246,8 +246,8 @@ def delete_request(self, url, auth=False, params=None): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ params = {} @@ -281,7 +281,7 @@ def _sync_request( **kwargs: Additional keyword arguments to be passed to the method. Returns: - requests.Response: The response object returned by the request. + httpx.Response: The response object returned by the request. Raises: ApiAuthorizationError: If the response status code is 401 (Authorization error). @@ -393,12 +393,6 @@ async def __aexit__(self, exc_type, exc_value, traceback): class DataAccessApi(Api): """Class to access Dataverse's Data Access API. - Examples - ------- - Examples should be written in doctest format, and - should illustrate how to use the function/class. - >>> - Attributes ---------- base_url_api_data_access : type @@ -460,8 +454,8 @@ def get_datafile( Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ is_first_param = True @@ -506,8 +500,8 @@ def get_datafiles(self, identifier, data_format=None, auth=False): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/datafiles/{1}".format(self.base_url_api_data_access, identifier) @@ -547,8 +541,8 @@ def get_datafile_bundle(self, identifier, file_metadata_id=None, auth=False): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/datafile/bundle/{1}".format( @@ -794,8 +788,8 @@ def get_dataverse(self, identifier, auth=False): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/dataverses/{1}".format(self.base_url_api_native, identifier) @@ -835,8 +829,8 @@ def create_dataverse( Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ metadata_dict = json.loads(metadata) @@ -887,8 +881,8 @@ def publish_dataverse(self, identifier, auth=True): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/dataverses/{1}/actions/:publish".format( @@ -935,8 +929,8 @@ def delete_dataverse(self, identifier, auth=True): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/dataverses/{1}".format(self.base_url_api_native, identifier) @@ -991,8 +985,8 @@ def get_dataverse_roles(self, identifier: str, auth: bool = False) -> Response: Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/dataverses/{1}/roles".format(self.base_url_api_native, identifier) @@ -1011,8 +1005,8 @@ def get_dataverse_contents(self, identifier, auth=True): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/dataverses/{1}/contents".format(self.base_url_api_native, identifier) @@ -1035,8 +1029,8 @@ def get_dataverse_assignments(self, identifier, auth=False): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/dataverses/{1}/assignments".format( @@ -1061,8 +1055,8 @@ def get_dataverse_facets(self, identifier, auth=False): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/dataverses/{1}/facets".format(self.base_url_api_native, identifier) @@ -1123,8 +1117,8 @@ def get_dataset(self, identifier, version=":latest", auth=True, is_pid=True): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ if is_pid: @@ -1162,8 +1156,8 @@ def get_dataset_versions(self, identifier, auth=True, is_pid=True): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ if is_pid: @@ -1203,8 +1197,8 @@ def get_dataset_version(self, identifier, version, auth=True, is_pid=True): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ if is_pid: @@ -1237,8 +1231,8 @@ def get_dataset_export(self, pid, export_format, auth=False): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/datasets/export?exporter={1}&persistentId={2}".format( @@ -1311,8 +1305,8 @@ def create_dataset(self, dataverse, metadata, pid=None, publish=False, auth=True Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ if pid: @@ -1399,8 +1393,8 @@ def edit_dataset_metadata( Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. Examples ------- @@ -1561,8 +1555,8 @@ def publish_dataset(self, pid, release_type="minor", auth=True): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/datasets/:persistentId/actions/:publish".format( @@ -1601,8 +1595,8 @@ def get_dataset_lock(self, pid): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/datasets/:persistentId/locks/?persistentId={1}".format( @@ -1645,8 +1639,8 @@ def delete_dataset(self, identifier, is_pid=True, auth=True): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ if is_pid: @@ -1737,8 +1731,8 @@ def get_datafiles_metadata(self, pid, version=":latest", auth=True): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ base_str = "{0}/datasets/:persistentId/versions/".format( @@ -1940,8 +1934,8 @@ def get_info_version(self, auth=False): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/info/version".format(self.base_url_api_native) @@ -1961,8 +1955,8 @@ def get_info_server(self, auth=False): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/info/server".format(self.base_url_api_native) @@ -1982,8 +1976,8 @@ def get_info_api_terms_of_use(self, auth=False): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/info/apiTermsOfUse".format(self.base_url_api_native) @@ -2002,8 +1996,8 @@ def get_metadatablocks(self, auth=False): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/metadatablocks".format(self.base_url_api_native) @@ -2028,8 +2022,8 @@ def get_metadatablock(self, identifier, auth=False): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/metadatablocks/{1}".format(self.base_url_api_native, identifier) @@ -2046,8 +2040,8 @@ def get_user_api_token_expiration_date(self, auth=False): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/users/token".format(self.base_url_api_native) @@ -2064,8 +2058,8 @@ def recreate_user_api_token(self): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/users/token/recreate".format(self.base_url_api_native) @@ -2082,8 +2076,8 @@ def delete_user_api_token(self): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/users/token".format(self.base_url_api_native) @@ -2107,8 +2101,8 @@ def create_role(self, dataverse_id): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/roles?dvo={1}".format(self.base_url_api_native, dataverse_id) @@ -2132,8 +2126,8 @@ def show_role(self, role_id, auth=False): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/roles/{1}".format(self.base_url_api_native, role_id) @@ -2151,8 +2145,8 @@ def delete_role(self, role_id): Returns ------- - requests.Response - Response object of requests library. + httpx.Response + Response object of httpx library. """ url = "{0}/roles/{1}".format(self.base_url_api_native, role_id) diff --git a/pyDataverse/docs/source/conf.py b/pyDataverse/docs/source/conf.py index a207fdc..c7a2ecd 100644 --- a/pyDataverse/docs/source/conf.py +++ b/pyDataverse/docs/source/conf.py @@ -200,5 +200,4 @@ intersphinx_mapping = { "python": ("https://docs.python.org/3", None), - "requests": ("https://requests.readthedocs.io/en/master", None), } diff --git a/pyDataverse/docs/source/index.rst b/pyDataverse/docs/source/index.rst index f31e2e3..208735c 100644 --- a/pyDataverse/docs/source/index.rst +++ b/pyDataverse/docs/source/index.rst @@ -121,7 +121,7 @@ Dataset through the API with :meth:`create_dataset() `. This returns, as all API functions do, a -:class:`requests.Response ` object, with the +:class:`httpx.Response ` object, with the DOI inside ``data``. Replace following variables with your own instance data diff --git a/pyDataverse/docs/source/user/advanced-usage.rst b/pyDataverse/docs/source/user/advanced-usage.rst index 769ce1a..43620fe 100644 --- a/pyDataverse/docs/source/user/advanced-usage.rst +++ b/pyDataverse/docs/source/user/advanced-usage.rst @@ -166,7 +166,7 @@ Note: The Dataverse collection assigned to ``dv_alias`` must be published in ord Dataset with pid 'doi:10.5072/FK2/WVMDFE' created. The API requests always return a -:class:`requests.Response ` object, which can then be used +:class:`httpx.Response ` object, which can then be used to extract the data. Next, we'll do the same for the :class:`list ` of diff --git a/pyDataverse/docs/source/user/basic-usage.rst b/pyDataverse/docs/source/user/basic-usage.rst index b1d1807..340db7a 100644 --- a/pyDataverse/docs/source/user/basic-usage.rst +++ b/pyDataverse/docs/source/user/basic-usage.rst @@ -63,8 +63,8 @@ if the API connection works and to retrieve the version of your Dataverse instan >>> resp.status_code 200 -All API requests return a :class:`requests.Response ` object, which -can then be used (e. g. :meth:`json() `). +All API requests return a :class:`httpx.Response ` object, which +can then be used (e. g. :meth:`json() `). .. _user_basic-usage_create-dataverse: