PyLinks 0.0.0.dev47__tar.gz → 0.0.0.dev49__tar.gz

{pylinks-0.0.0.dev47 → pylinks-0.0.0.dev49}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: PyLinks
-Version: 0.0.0.dev47
+Version: 0.0.0.dev49
 Requires-Python: >=3.10
 Requires-Dist: requests<3,>=2.31.0
-Requires-Dist: ExceptionMan==0.0.0.dev34
-Requires-Dist: MDit==0.0.0.dev34
+Requires-Dist: ExceptionMan==0.0.0.dev36
+Requires-Dist: MDit==0.0.0.dev36

{pylinks-0.0.0.dev47 → pylinks-0.0.0.dev49}/pyproject.toml

@@ -17,12 +17,12 @@ namespaces = true
 # ----------------------------------------- Project Metadata -------------------------------------
 #
 [project]
-version = "0.0.0.dev47"
+version = "0.0.0.dev49"
 name = "PyLinks"
 dependencies = [
     "requests >= 2.31.0, < 3",
-    "ExceptionMan == 0.0.0.dev34",
-    "MDit == 0.0.0.dev34",
+    "ExceptionMan == 0.0.0.dev36",
+    "MDit == 0.0.0.dev36",
 ]
 requires-python = ">=3.10"
 

{pylinks-0.0.0.dev47 → pylinks-0.0.0.dev49}/src/PyLinks.egg-info/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: PyLinks
-Version: 0.0.0.dev47
+Version: 0.0.0.dev49
 Requires-Python: >=3.10
 Requires-Dist: requests<3,>=2.31.0
-Requires-Dist: ExceptionMan==0.0.0.dev34
-Requires-Dist: MDit==0.0.0.dev34
+Requires-Dist: ExceptionMan==0.0.0.dev36
+Requires-Dist: MDit==0.0.0.dev36

pylinks-0.0.0.dev49/src/PyLinks.egg-info/requires.txt

@@ -0,0 +1,3 @@
+requests<3,>=2.31.0
+ExceptionMan==0.0.0.dev36
+MDit==0.0.0.dev36

{pylinks-0.0.0.dev47 → pylinks-0.0.0.dev49}/src/pylinks/api/github.py

@@ -1,5 +1,6 @@
 # Standard libraries
-from typing import Optional, Literal
+from __future__ import annotations as _annotations
+from typing import TYPE_CHECKING as _TYPE_CHECKING
 from pathlib import Path
 import re
 import mimetypes
@@ -7,6 +8,9 @@ import mimetypes
 # Non-standard libraries
 import pylinks as _pylinks
 
+if _TYPE_CHECKING:
+    from typing import Optional, Literal, Any
+
 
 class GitHub:
     """GitHub API
@@ -38,13 +42,22 @@ class GitHub:
     def graphql_query(
         self,
         query: str,
+        variables: dict[str, tuple[Any, str, bool]] | None = None,
         extra_headers: dict | None = None,
     ) -> dict:
         headers = self._headers | extra_headers if extra_headers else self._headers
+        if variables:
+            args = ", ".join(
+                f"${name}:{typ}{"!" if required else ""}" for name, (_, typ, required) in variables.items()
+            )
+            sig = f"query({args})"
+        else:
+            sig = "query"
         response = _pylinks.http.graphql_query(
             url=self._endpoint["api"] / "graphql",
-            query=f"{{{query}}}",
+            query=f"{sig} {{{query}}}",
             headers=headers,
+            variables={name: value for name, (value, _, _) in variables.items()} if variables else None
         )
         return response
 
@@ -169,10 +182,12 @@ class Repo:
     def _graphql_query(
         self,
         payload: str,
+        variables: dict[str, tuple[Any, str, bool]] | None = None,
         extra_headers: dict | None = None,
     ) -> dict:
         return self._github.graphql_query(
             query=f'repository(name: "{self._name}", owner: "{self._username}") {{{payload}}}',
+            variables=variables,
             extra_headers=extra_headers,
         )["repository"]
 
@@ -620,6 +635,8 @@ class Repo:
         self,
         number: int,
         count: int = 0,
+        cursor_before: str | None = None,
+        cursor_after: str | None = None,
         sort: Literal["first", "last"] = "last",
     ) -> list[dict]:
         """
@@ -640,20 +657,52 @@ class Repo:
         ----------
         - [GitHub API Docs](https://docs.github.com/en/rest/pulls/commits?apiVersion=2022-11-28#list-commits-on-a-pull-request)
         """
-        payload = f"pullRequest(number: {number})"
-        commits = "{{commits()"
-
-        commits = []
-        page = 1
+        def post_process():
+            out = []
+            for datum in data:
+                commits = datum["pullRequest"]["commits"]["nodes"]
+                if sort == "last":
+                    commits = reversed(commits)
+                for commit in commits:
+                    commit["commit"]["authors"] = commit["commit"]["authors"]["nodes"]
+                    out.append(commit)
+            return out
+
+        git_actor_fields = "{name, email, date user {id, login}}"
+        commit_fields = f"{{abbreviatedOid, additions, deletions, authors(first: 100) {{nodes {git_actor_fields}}}, committer {git_actor_fields}, authoredByCommitter, authoredDate, committedDate, message, messageBody, messageHeadline, oid, id, resourcePath, url}}"
+        page_info_fields = "pageInfo {startCursor, endCursor, hasNextPage, hasPreviousPage}"
+        commits_args = ["after: $after", "before: $before", f"{sort}: {100 if count <= 0 else min(count, 100)}"]
+        commits_fields = f"nodes {{id, resourcePath, url, commit {commit_fields} }}"
+        commits_sig = f"commits({", ".join(commits_args)})"
+        payload = f"pullRequest(number: {number}) {{ {commits_sig} {{ {commits_fields} {page_info_fields} }} }}"
+        variables = {
+            "after": (cursor_after, "String", False),
+            "before": (cursor_before, "String", False),
+        }
+        data = [self._graphql_query(payload, variables)]
+        total_downloaded = 100
         while True:
-            response = self._rest_query(f"pulls/{number}/commits?per_page=100&page={page}")
-            commits.extend(response)
-            page += 1
-            if len(response) < 100:
-                break
-        return commits
-
-
+            page_info = data[-1]["pullRequest"]["commits"]["pageInfo"]
+            if count <= 0:
+                must_continue = page_info["hasNextPage" if sort == "first" else "hasPreviousPage"]
+                if not must_continue:
+                    return post_process()
+            elif total_downloaded >= count:
+                return post_process()
+            else:
+                variables[sort] = page_info["endCursor" if sort == "first" else "startCursor"]
+                data.append(self._graphql_query(payload, variables))
+                total_downloaded += 100
+
+        # commits = []
+        # page = 1
+        # while True:
+        #     response = self._rest_query(f"pulls/{number}/commits?per_page=100&page={page}")
+        #     commits.extend(response)
+        #     page += 1
+        #     if len(response) < 100:
+        #         break
+        # return commits
 
     def pull_create(
         self,
@@ -1046,15 +1095,22 @@ class Repo:
             raise ValueError("At least one of 'new_name', 'color', or 'description' must be specified.")
         return self._rest_query(query=f"labels/{name}", verb="PATCH", json=data)
 
+    def release_get(self, release_id: int) -> dict:
+        return self._rest_query(query=f"releases/{release_id}")
+
+    def release_delete(self, release_id: int) -> None:
+        self._rest_query(query=f"releases/{release_id}", verb="DELETE", response_type=None)
+        return
+
     def release_create(
         self,
         tag_name: str,
-        name: str,
-        body: str,
-        target_commitish: str = "",
+        name: str | None = None,
+        body: str | None = None,
+        target_commitish: str | None = None,
         draft: bool = False,
         prerelease: bool = False,
-        discussion_category_name: str = "",
+        discussion_category_name: str | None = None,
         generate_release_notes: bool = False,
         make_latest: Literal['true', 'false', 'legacy'] = 'true'
     ):
@@ -1094,22 +1150,62 @@ class Repo:
         ----------
         [GitHub API Docs](https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#create-a-release)
         """
-        data = {
-            "tag_name": tag_name,
-            "draft": draft,
-            "prerelease": prerelease,
-            "generate_release_notes": generate_release_notes,
-            "make_latest": make_latest,
-        }
-        if name:
-            data["name"] = name
-        if body:
-            data["body"] = body
-        if target_commitish:
-            data["target_commitish"] = target_commitish
-        if discussion_category_name:
-            data["discussion_category_name"] = discussion_category_name
-        return self._rest_query(query="releases", verb="POST", json=data)
+        data = {k: v for k, v in locals().items() if k != "self" and v is not None}
+        return self._rest_query(query=f"releases", verb="POST", json=data)
+
+    def release_update(
+        self,
+        release_id: int,
+        tag_name: str | None = None,
+        name: str | None = None,
+        body: str | None = None,
+        target_commitish: str | None = None,
+        draft: bool | None = None,
+        prerelease: bool | None = None,
+        discussion_category_name: str | None = None,
+        make_latest: Literal['true', 'false', 'legacy'] | None = None
+    ):
+        """Update a release.
+
+        Parameters
+        ----------
+        tag_name : str
+            The name of the tag.
+        name : str
+            The name of the release.
+        body : str
+            The body of the release post, i.e. text describing the release.
+        target_commitish : str, optional
+            The commitish value that determines where the Git tag is created from.
+            Can be any branch or commit SHA. Unused if the Git tag already exists.
+            The default is the repository's default branch.
+        draft : bool, optional
+            `True` to create a draft (unpublished) release, `False` to create a published one.
+        prerelease : bool, default: False
+            `True` to identify the release as a prerelease, `False` to identify it as a full release.
+        discussion_category_name : str, optional
+            The name of the discussion category for the release, to be created and linked to the release.
+            The value must be a category that already exists in the repository.
+        make_latest : {'true', 'false', 'legacy'}, optional
+            Whether this release should be set as the latest release for the repository.
+            Drafts and prereleases cannot be set as latest.
+            Defaults to 'true' for newly published releases.
+            'legacy' specifies that the latest release should be determined based on
+            the release creation date and higher semantic version.
+
+        References
+        ----------
+        [GitHub API Docs](https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#create-a-release)
+        """
+        data = {k: v for k, v in locals().items() if k not in ("self", "release_id") and v is not None}
+        return self._rest_query(query=f"releases/{release_id}", verb="PATCH", json=data)
+
+    def release_asset_list(self, release_id: int) -> list[dict]:
+        return self._rest_query(query=f"releases/{release_id}/assets")
+
+    def release_asset_delete(self, asset_id: int) -> None:
+        self._rest_query(query=f"releases/assets/{asset_id}", verb="DELETE", response_type=None)
+        return
 
     def release_asset_upload(
         self,
@@ -1701,7 +1797,7 @@ class Repo:
         """
         payload = "branchProtectionRules(first: 100) {nodes {id, pattern}}"
         data = self._graphql_query(payload)
-        return data["repository"]["branchProtectionRules"]["nodes"]
+        return data["branchProtectionRules"]["nodes"]
 
     def branch_protection_rule_create(
         self,

pylinks-0.0.0.dev49/src/pylinks/api/zenodo.py

@@ -0,0 +1,240 @@
+from __future__ import annotations as _annotations
+
+from typing import TYPE_CHECKING as _TYPE_CHECKING
+from pathlib import Path as _Path
+import pylinks as _pylinks
+
+if _TYPE_CHECKING:
+    from typing import Literal
+
+
+class Zenodo:
+    """Zenodo API.
+
+    References
+    ----------
+    - [API Manual](https://developers.zenodo.org/)
+    - [Main Repository](https://github.com/zenodo/zenodo)
+    """
+    def __init__(self, token: str, sandbox: bool = False):
+        self._sandbox = sandbox
+        self._url = _pylinks.url.create(
+            "https://sandbox.zenodo.org/api" if sandbox else "https://zenodo.org/api"
+        )
+        self._headers = {"Authorization": f"Bearer {token}"}
+        return
+
+    def rest_query(
+        self,
+        query: str,
+        verb: Literal["GET", "POST", "PUT", "PATCH", "OPTIONS", "DELETE"] = "GET",
+        params: dict | None = None,
+        data = None,
+        json = None,
+        content_type: str | None = "application/json",
+        response_type: Literal["str", "json", "bytes"] | None = "json"
+    ) -> dict | list:
+        content_header = {"Content-Type": content_type} if content_type else {}
+        return _pylinks.http.request(
+            url=self._url / query,
+            verb=verb,
+            params=params,
+            data=data,
+            json=json,
+            headers=self._headers | content_header,
+            response_type=response_type, # All responses are JSON (https://developers.zenodo.org/#responses)
+        )
+
+    def create_and_publish(
+        self,
+        metadata: dict,
+        files: list[str | _Path | tuple[str | _Path, str]],
+        previous_id: str | int | None = None
+    ):
+        def add_files(bucket_id: str):
+            for file in files:
+                if not isinstance(file, (str, _Path)):
+                    filepath = file[0]
+                    name = file[1]
+                else:
+                    filepath = file
+                    name = None
+                self.file_create(
+                    bucket_id=bucket_id,
+                    filepath=filepath,
+                    name=name,
+                )
+            return
+
+        if not previous_id:
+            new_depo = self.deposition_create(metadata=metadata)
+            add_files(bucket_id=new_depo["links"]["bucket"])
+            return self.deposition_publish(new_depo["id"])
+        new_ver = self.deposition_new_version(deposition_id=previous_id)
+        for previous_file in new_ver["files"]:
+            self.file_delete(deposition_id=new_ver["id"], file_id=previous_file["id"])
+        add_files(new_ver["links"]["bucket"])
+        return self.deposition_publish(new_ver["id"])
+
+
+    def deposition_list(
+        self,
+        query: str | None = None,
+        status: Literal["draft", "published"] | None = None,
+        sort: Literal["bestmatch", "mostrecent", "-bestmatch", "-mostrecent"] | None = None,
+        page: int | None = None,
+        size: int | None = None,
+        all_versions: bool | None = None,
+    ):
+        params = {k: v for k, v in locals().items() if k not in ("self", "query") and v}
+        if query:
+            params["q"] = query
+        return self.rest_query(
+            "deposit/depositions",
+            verb="GET",
+            params=params,
+        )
+
+    def deposition_retrieve(self, deposition_id: str | int):
+        return self.rest_query(
+            f"deposit/depositions/{deposition_id}",
+            verb="GET",
+        )
+
+    def deposition_delete(self, deposition_id: str | int):
+        self.rest_query(
+            f"deposit/depositions/{deposition_id}",
+            verb="DELETE",
+            response_type=None
+        )
+        return
+
+    def deposition_create(self, metadata: dict | None = None) -> dict:
+        """Create a new deposition.
+
+        Returns
+        -------
+
+        Example response:
+        :::{code-block} json
+
+        {
+            "conceptrecid": "542200",
+            "created": "2020-05-19T11:58:41.606998+00:00",
+            "files": [],
+            "id": 542201,
+            "links": {
+                "bucket": "https://zenodo.org/api/files/568377dd-daf8-4235-85e1-a56011ad454b",
+                "discard": "https://zenodo.org/api/deposit/depositions/542201/actions/discard",
+                "edit": "https://zenodo.org/api/deposit/depositions/542201/actions/edit",
+                "files": "https://zenodo.org/api/deposit/depositions/542201/files",
+                "html": "https://zenodo.org/deposit/542201",
+                "latest_draft": "https://zenodo.org/api/deposit/depositions/542201",
+                "latest_draft_html": "https://zenodo.org/deposit/542201",
+                "publish": "https://zenodo.org/api/deposit/depositions/542201/actions/publish",
+                "self": "https://zenodo.org/api/deposit/depositions/542201"
+            },
+            "metadata": {
+                "prereserve_doi": {
+                    "doi": "10.5072/zenodo.542201",
+                    "recid": 542201
+                }
+            },
+            "modified": "2020-05-19T11:58:41.607012+00:00",
+            "owner": 12345,
+            "record_id": 542201,
+            "state": "unsubmitted",
+            "submitted": false,
+            "title": ""
+        }
+        :::
+        """
+        return self.rest_query(
+            query="deposit/depositions",
+            verb="POST",
+            json={"metadata": metadata} if metadata else {},
+        )
+
+    def deposition_new_version(self, deposition_id: int | str):
+        """Create a new version of a deposition as a draft."""
+        return self.rest_query(
+            query=f"deposit/depositions/{deposition_id}/actions/newversion",
+            verb="POST",
+        )
+
+    def deposition_update(self, deposition_id: int | str, metadata: dict):
+        """Update and existing deposition."""
+        return self.rest_query(
+            query=f"deposit/depositions/{deposition_id}",
+            verb="PUT",
+            json={"metadata": metadata},
+        )
+
+    def deposition_publish(self, deposition_id: int | str) -> dict:
+        """Publish a deposition."""
+        return self.rest_query(
+            query=f"deposit/depositions/{deposition_id}/actions/publish",
+            verb="POST",
+        )
+
+    def file_list(self, deposition_id: str | int):
+        return self.rest_query(
+            f"deposit/depositions/{deposition_id}/files",
+            verb="GET"
+        )
+
+    def file_create(
+        self,
+        bucket_id: str,
+        filepath: str | _Path,
+        name: str | None = None,
+    ) -> dict:
+        """Upload a file to a Zenodo bucket.
+
+        Parameters
+        ----------
+        bucket_id
+            Bucket ID (e.g., `"d7524553-7f8c-4632-bffb-8bea6a90b88b"`)
+            or bucket URL (e.g., `"https://zenodo.org/api/files/d7524553-7f8c-4632-bffb-8bea6a90b88b"`)
+
+        Returns
+        -------
+
+        Example response:
+        :::{code-block} json
+
+        {
+          "key": "my-file.zip",
+          "mimetype": "application/zip",
+          "checksum": "md5:2942bfabb3d05332b66eb128e0842cff",
+          "version_id": "38a724d3-40f1-4b27-b236-ed2e43200f85",
+          "size": 13264,
+          "created": "2020-02-26T14:20:53.805734+00:00",
+          "updated": "2020-02-26T14:20:53.811817+00:00",
+          "links": {
+            "self": "https://zenodo.org/api/files/44cc40bc-50fd-4107-b347-00838c79f4c1/dummy_example.pdf",
+            "version": "https://zenodo.org/api/files/44cc40bc-50fd-4107-b347-00838c79f4c1/dummy_example.pdf?versionId=38a724d3-40f1-4b27-b236-ed2e43200f85",
+            "uploads": "https://zenodo.org/api/files/44cc40bc-50fd-4107-b347-00838c79f4c1/dummy_example.pdf?uploads"
+          },
+          "is_head": true,
+          "delete_marker": false
+        }
+        :::
+        """
+        bucket_id = bucket_id.removeprefix(f"{self._url}/files/")
+        filepath = _Path(filepath)
+        name = name or filepath.name
+        with open(filepath, "rb") as file:
+            return self.rest_query(
+                query=f"files/{bucket_id}/{name}",
+                verb="PUT",
+                data=file,
+                content_type=None,
+            )
+
+    def file_delete(self, deposition_id: str | int, file_id: str | int):
+        return self.rest_query(
+            f"deposit/depositions/{deposition_id}/files/{file_id}",
+            verb="DELETE",
+            response_type=None,
+        )

{pylinks-0.0.0.dev47 → pylinks-0.0.0.dev49}/src/pylinks/exception/api.py

@@ -101,7 +101,7 @@ class GraphQLResponseError(WebAPIError):
     Exception class for GraphQL
     """
 
-    def __init__(self, response: dict):
+    def __init__(self, response: dict, query: str):
         if "errors" in response:
             intro = "GraphQL response contains errors."
         elif "data" not in response:
@@ -109,10 +109,16 @@ class GraphQLResponseError(WebAPIError):
         super().__init__(
             title="GraphQL Response Error",
             intro=intro,
-            details=_mdit.element.code_block(
-                json.dumps(response, indent=3), language="json", caption="GraphQL Response"
-            ),
+            details=_mdit.block_container(
+                _mdit.element.code_block(
+                    json.dumps(response, indent=3), language="json", caption="GraphQL Response"
+                ),
+                _mdit.element.code_block(
+                    query, language="graphql", caption="GraphQL Query"
+                ),
+            )
         )
+        self.query = query
         return
 
 

{pylinks-0.0.0.dev47 → pylinks-0.0.0.dev49}/src/pylinks/http.py

@@ -277,9 +277,9 @@ def graphql_query(
     if isinstance(response, dict):
         error_title = "GraphQL API Error"
         if "errors" in response:
-            raise _exception.GraphQLResponseError(response)
+            raise _exception.GraphQLResponseError(response, query)
         elif "data" not in response:
-            raise _exception.GraphQLResponseError(response)
+            raise _exception.GraphQLResponseError(response, query)
         else:
             response = response["data"]
     return response

pylinks-0.0.0.dev47/src/PyLinks.egg-info/requires.txt

@@ -1,3 +0,0 @@
-requests<3,>=2.31.0
-ExceptionMan==0.0.0.dev34
-MDit==0.0.0.dev34

pylinks-0.0.0.dev47/src/pylinks/api/zenodo.py

@@ -1,147 +0,0 @@
-from __future__ import annotations as _annotations
-
-from typing import TYPE_CHECKING as _TYPE_CHECKING
-from pathlib import Path as _Path
-import pylinks as _pylinks
-
-if _TYPE_CHECKING:
-    from typing import Literal
-
-
-class Zenodo:
-    """Zenodo API.
-
-    References
-    ----------
-    - [API Manual](https://developers.zenodo.org/)
-    - [Main Repository](https://github.com/zenodo/zenodo)
-    """
-    def __init__(self, token: str, sandbox: bool = False):
-        self._sandbox = sandbox
-        self._url = _pylinks.url.create("https://zenodo.org/api")
-        self._url_sandbox = _pylinks.url.create("https://sandbox.zenodo.org/api")
-        self._headers = {"Authorization": token}
-        return
-
-    def rest_query(
-        self,
-        query: str,
-        verb: Literal["GET", "POST", "PUT", "PATCH", "OPTIONS", "DELETE"] = "GET",
-        data = None,
-        json = None,
-        content_type: str | None = "application/json",
-        sandbox: bool | None = None,
-    ) -> dict | list:
-        sandbox = sandbox if sandbox is not None else self._sandbox
-        base_url = self._url_sandbox if sandbox else self._url
-        content_header = {"Content-Type": content_type} if content_type else {}
-        return _pylinks.http.request(
-            url=base_url / query,
-            verb=verb,
-            data=data,
-            json=json,
-            headers=self._headers | content_header,
-            response_type="json", # All responses are JSON (https://developers.zenodo.org/#responses)
-        )
-
-    def deposition_create(
-        self,
-        metadata: dict | None = None,
-        sandbox: bool | None = None,
-    ) -> dict:
-        """Create a new deposition.
-
-        Returns
-        -------
-
-        Example response:
-        :::{code-block} json
-
-        {
-            "conceptrecid": "542200",
-            "created": "2020-05-19T11:58:41.606998+00:00",
-            "files": [],
-            "id": 542201,
-            "links": {
-                "bucket": "https://zenodo.org/api/files/568377dd-daf8-4235-85e1-a56011ad454b",
-                "discard": "https://zenodo.org/api/deposit/depositions/542201/actions/discard",
-                "edit": "https://zenodo.org/api/deposit/depositions/542201/actions/edit",
-                "files": "https://zenodo.org/api/deposit/depositions/542201/files",
-                "html": "https://zenodo.org/deposit/542201",
-                "latest_draft": "https://zenodo.org/api/deposit/depositions/542201",
-                "latest_draft_html": "https://zenodo.org/deposit/542201",
-                "publish": "https://zenodo.org/api/deposit/depositions/542201/actions/publish",
-                "self": "https://zenodo.org/api/deposit/depositions/542201"
-            },
-            "metadata": {
-                "prereserve_doi": {
-                    "doi": "10.5072/zenodo.542201",
-                    "recid": 542201
-                }
-            },
-            "modified": "2020-05-19T11:58:41.607012+00:00",
-            "owner": 12345,
-            "record_id": 542201,
-            "state": "unsubmitted",
-            "submitted": false,
-            "title": ""
-        }
-        :::
-        """
-        return self.rest_query(
-            query="deposit/depositions",
-            verb="POST",
-            json=metadata or {},
-            sandbox=sandbox,
-        )
-
-    def deposition_publish(self, deposition_id: str) -> dict:
-        """Publish a deposition."""
-        return self.rest_query(
-            query=f"deposit/depositions/{deposition_id}/actions/publish",
-            verb="POST",
-        )
-
-    def file_create(
-        self,
-        bucket_url: str | _pylinks.url.URL,
-        filepath: str | _Path,
-        upload_path: str | None = None,
-    ) -> dict:
-        """Upload a file to a Zenodo bucket.
-
-        Returns
-        -------
-
-        Example response:
-        :::{code-block} json
-
-        {
-          "key": "my-file.zip",
-          "mimetype": "application/zip",
-          "checksum": "md5:2942bfabb3d05332b66eb128e0842cff",
-          "version_id": "38a724d3-40f1-4b27-b236-ed2e43200f85",
-          "size": 13264,
-          "created": "2020-02-26T14:20:53.805734+00:00",
-          "updated": "2020-02-26T14:20:53.811817+00:00",
-          "links": {
-            "self": "https://zenodo.org/api/files/44cc40bc-50fd-4107-b347-00838c79f4c1/dummy_example.pdf",
-            "version": "https://zenodo.org/api/files/44cc40bc-50fd-4107-b347-00838c79f4c1/dummy_example.pdf?versionId=38a724d3-40f1-4b27-b236-ed2e43200f85",
-            "uploads": "https://zenodo.org/api/files/44cc40bc-50fd-4107-b347-00838c79f4c1/dummy_example.pdf?uploads"
-          },
-          "is_head": true,
-          "delete_marker": false
-        }
-        :::
-        """
-        if not isinstance(bucket_url, _pylinks.url.URL):
-            bucket_url = _pylinks.url.create(bucket_url)
-        filepath = _Path(filepath)
-        upload_path = upload_path or filepath.name
-        with open(filepath, "rb") as file:
-            return self.rest_query(
-                query=bucket_url / upload_path,
-                verb="PUT",
-                data=file,
-                content_type=None,
-            )