PyLinks 0.0.0.dev23__tar.gz → 0.0.0.dev25__tar.gz

{PyLinks-0.0.0.dev23 → pylinks-0.0.0.dev25}/PKG-INFO

@@ -1,5 +1,5 @@
 Metadata-Version: 2.1
 Name: PyLinks
-Version: 0.0.0.dev23
-Requires-Python: >=3.9
+Version: 0.0.0.dev25
+Requires-Python: >=3.10
 Requires-Dist: requests<3,>=2.31.0

{PyLinks-0.0.0.dev23 → pylinks-0.0.0.dev25}/pyproject.toml

@@ -17,10 +17,10 @@ namespaces = true
 # ----------------------------------------- Project Metadata -------------------------------------
 #
 [project]
-version = "0.0.0.dev23"
+version = "0.0.0.dev25"
 name = "PyLinks"
 dependencies = [
     "requests >= 2.31.0, < 3",
 ]
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 

{PyLinks-0.0.0.dev23 → pylinks-0.0.0.dev25}/src/PyLinks.egg-info/PKG-INFO

@@ -1,5 +1,5 @@
 Metadata-Version: 2.1
 Name: PyLinks
-Version: 0.0.0.dev23
-Requires-Python: >=3.9
+Version: 0.0.0.dev25
+Requires-Python: >=3.10
 Requires-Dist: requests<3,>=2.31.0

{PyLinks-0.0.0.dev23 → pylinks-0.0.0.dev25}/src/PyLinks.egg-info/SOURCES.txt

@@ -9,14 +9,22 @@ src/pylinks/__init__.py
 src/pylinks/_settings.py
 src/pylinks/exceptions.py
 src/pylinks/http.py
+src/pylinks/media_type.py
 src/pylinks/url.py
 src/pylinks/api/__init__.py
 src/pylinks/api/doi.py
 src/pylinks/api/github.py
 src/pylinks/api/orcid.py
+src/pylinks/exception/__init__.py
+src/pylinks/exception/base.py
+src/pylinks/exception/media_type.py
+src/pylinks/exception/uri.py
 src/pylinks/site/__init__.py
 src/pylinks/site/binder.py
 src/pylinks/site/conda.py
 src/pylinks/site/github.py
+src/pylinks/site/lib_io.py
 src/pylinks/site/pypi.py
-src/pylinks/site/readthedocs.py
+src/pylinks/site/readthedocs.py
+src/pylinks/uri/__init__.py
+src/pylinks/uri/data.py

{PyLinks-0.0.0.dev23 → pylinks-0.0.0.dev25}/src/pylinks/__init__.py

@@ -11,7 +11,5 @@ but can be used directly from the root. It returns a URL object, also defined in
 Other available modules offer shortcuts for creating useful URLs for popular online services.
 """
 
-from ._settings import settings
-from .url import url
-from .http import request, download, graphql_query
-from . import api, site
+from pylinks._settings import settings
+from pylinks import url, http, api, site, exceptions, uri, media_type

{PyLinks-0.0.0.dev23 → pylinks-0.0.0.dev25}/src/pylinks/api/doi.py

@@ -5,7 +5,7 @@ import datetime
 from typing import Optional
 
 # Non-standard libraries
-from pylinks.http import request as _request
+import pylinks as _pylinks
 
 
 class DOI:
@@ -58,13 +58,13 @@ class DOI:
             accept += f"; style={style}"
         if locale:
             accept += f"; locale={locale}"
-        return _request(
+        return _pylinks.http.request(
             self.url, headers={"accept": accept}, encoding="utf-8", response_type="str"
         )
 
     @property
     def bibtex(self) -> str:
-        return _request(
+        return _pylinks.http.request(
             self.url,
             headers={"accept": "application/x-bibtex"},
             encoding="utf-8",
@@ -73,7 +73,7 @@ class DOI:
 
     @property
     def ris(self) -> str:
-        return _request(
+        return _pylinks.http.request(
             self.url,
             headers={"accept": "application/x-research-info-systems"},
             encoding="utf-8",
@@ -85,7 +85,7 @@ class DOI:
         """
         Citation data as a dictionary with Citeproc JSON schema.
         """
-        return _request(
+        return _pylinks.http.request(
             self.url,
             headers={"accept": "application/citeproc+json"},
             encoding="utf-8",
@@ -98,7 +98,7 @@ class DOI:
         journal = data["container-title"] or None
         journal_abbr = (
             (
-                data.get("container-title-short") or _request(
+                data.get("container-title-short") or _pylinks.http.request(
                 f"https://abbreviso.toolforge.org/abbreviso/a/{journal}",
                     response_type="str",
                 ).title()

{PyLinks-0.0.0.dev23 → pylinks-0.0.0.dev25}/src/pylinks/api/github.py

@@ -5,16 +5,15 @@ import re
 import mimetypes
 
 # Non-standard libraries
-import pylinks
-from pylinks import request, url, graphql_query
+import pylinks as _pylinks
 
 
 class GitHub:
 
     def __init__(self, token: Optional[str] = None):
         self._endpoint = {
-            "api": url("https://api.github.com"),
-            "upload": url("https://uploads.github.com"),
+            "api": _pylinks.url.create("https://api.github.com"),
+            "upload": _pylinks.url.create("https://uploads.github.com"),
         }
         self._token = token
         self._headers = {"X-GitHub-Api-Version": "2022-11-28"}
@@ -31,7 +30,7 @@ class GitHub:
         extra_headers: dict | None = None,
     ) -> dict:
         headers = self._headers | extra_headers if extra_headers else self._headers
-        response = graphql_query(
+        response = _pylinks.http.graphql_query(
             url=self._endpoint["api"] / "graphql",
             query=f"{{{query}}}",
             headers=headers,
@@ -50,7 +49,7 @@ class GitHub:
             f'mutation($mutationInput:{mutation_input_name}!) '
             f'{{{mutation_name}(input:$mutationInput) {{{mutation_payload}}}}}'
         )
-        response = graphql_query(
+        response = _pylinks.http.graphql_query(
             url=self._endpoint["api"] / "graphql",
             query=query,
             variables={"mutationInput": mutation_input},
@@ -69,7 +68,7 @@ class GitHub:
         endpoint: Literal['api', 'upload'] = "api"
     ):
         headers = self._headers | extra_headers if extra_headers else self._headers
-        return request(
+        return _pylinks.http.request(
             verb=verb,
             url=self._endpoint[endpoint] / query,
             headers=headers,
@@ -100,8 +99,9 @@ class User:
         extra_headers: dict | None = None,
         endpoint: Literal['api', 'upload'] = "api"
     ):
+        query_part = f"/{query}" if query else ""
         return self._github.rest_query(
-            query=f"users/{self.username}/{query}",
+            query=f"users/{self.username}{query_part}",
             verb=verb,
             data=data,
             json=json,
@@ -144,8 +144,9 @@ class Repo:
         extra_headers: dict | None = None,
         endpoint: Literal['api', 'upload'] = "api"
     ):
+        query_part = f"/{query}" if query else ""
         return self._github.rest_query(
-            f"repos/{self._username}/{self._name}/{query}",
+            f"repos/{self._username}/{self._name}{query_part}",
             verb=verb,
             data=data,
             json=json,
@@ -328,7 +329,7 @@ class Repo:
                 if entry["type"] == "file":
                     filename = Path(entry["path"]).name
                     full_download_path = download_path / filename
-                    pylinks.download(
+                    _pylinks.http.download(
                         url=entry["download_url"], filepath=full_download_path, create_dirs=create_dirs
                     )
                     final_download_paths.append(full_download_path)
@@ -362,7 +363,7 @@ class Repo:
             full_download_path = download_path / download_filename
         else:
             full_download_path = download_path / Path(content["path"]).name
-        pylinks.download(
+        _pylinks.http.download(
             url=content["download_url"],
             filepath=full_download_path,
             create_dirs=create_dirs,
@@ -370,7 +371,7 @@ class Repo:
         )
         return full_download_path
 
-    def semantic_versions(self, tag_prefix: str = "v") -> list[tuple[int, int, int]]:
+    def semantic_versions(self, tag_prefix: str = "v") -> list[str]:
         """
         Get a list of all tags from a GitHub repository that represent SemVer version numbers,
         i.e. 'X.Y.Z' where X, Y, and Z are integers.
@@ -386,16 +387,11 @@ class Repo:
             `[(0, 1, 0), (0, 1, 1), (0, 2, 0), (1, 0, 0), (1, 1, 0)]`
         """
         tags = self.tag_names(pattern=rf"^{tag_prefix}(\d+\.\d+\.\d+)$")
-        return sorted([tuple(map(int, tag[0].split("."))) for tag in tags])
+        return sorted((tag[0] for tag in tags), key=lambda x: tuple(map(int, x.split("."))))
 
     def discussion_categories(self) -> list[dict[str, str]]:
         """Get discussion categories for a repository.
 
-        Parameters
-        ----------
-        access_token : str
-            GitHub access token.
-
         Returns
         -------
             A list of discussion categories as dictionaries with keys "name", "slug", and "id".
@@ -852,6 +848,12 @@ class Repo:
         return output
 
     def repo_topics_replace(self, topics: list[str]):
+        """Replace all repository topics.
+
+        References
+        ----------
+        - [GitHub API Docs](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#replace-all-repository-topics)
+        """
         topic_pattern = re.compile(r"^[a-z0-9][a-z0-9\-]*$")
         for topic in topics:
             if not isinstance(topic, str):
@@ -1508,6 +1510,21 @@ class Repo:
             raise ValueError("At least one of the ruleset parameters must be specified.")
         return self._rest_query(query=f"rulesets/{ruleset_id}", verb="PUT", json=data)
 
+    def ruleset_delete(self, ruleset_id: int) -> dict:
+        """
+        Delete a ruleset.
+
+        Parameters
+        ----------
+        ruleset_id : int
+            The ID of the ruleset.
+
+        References
+        ----------
+        - [GitHub API Docs](https://docs.github.com/en/rest/repos/rules?apiVersion=2022-11-28#delete-a-repository-ruleset)
+        """
+        return self._rest_query(query=f"rulesets/{ruleset_id}", verb="DELETE")
+
     def actions_permissions_workflow_default(self) -> dict:
         """
         Get default workflow permissions granted to the GITHUB_TOKEN when running workflows in the repository,

{PyLinks-0.0.0.dev23 → pylinks-0.0.0.dev25}/src/pylinks/api/orcid.py

@@ -3,7 +3,7 @@ import re
 import warnings
 
 # Non-standard libraries
-import pylinks
+import pylinks as _pylinks
 
 
 class Orcid:
@@ -20,7 +20,7 @@ class Orcid:
     @property
     def records(self) -> dict:
         if not self._data:
-            self._data = pylinks.request(
+            self._data = _pylinks.http.request(
                 url=f"https://pub.orcid.org/v3.0/{self.id}",
                 headers={"Accept": "application/json"},
                 response_type="json",

pylinks-0.0.0.dev25/src/pylinks/exception/__init__.py

@@ -0,0 +1,2 @@
+from pylinks.exception.base import PyLinksException
+from pylinks.exception import media_type

pylinks-0.0.0.dev25/src/pylinks/exception/base.py

@@ -0,0 +1,23 @@
+"""PyLinks base exception."""
+
+from pathlib import Path as _Path
+
+
+class PyLinksException(Exception):
+    """Base exception for PyLinks.
+
+    All exceptions raised by PyLinks inherit from this class.
+    """
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(message)
+        return
+
+
+class PyLinksFileNotFoundError(PyLinksException):
+    """File not found error."""
+    def __init__(self, path: str | _Path):
+        msg = f"No file found at input path '{path}.'"
+        super().__init__(message=msg)
+        self.path = path
+        return

pylinks-0.0.0.dev25/src/pylinks/exception/media_type.py

@@ -0,0 +1,20 @@
+from pylinks.exception import PyLinksException as _PyLinksException
+
+
+class PyLinksMediaTypeParseError(_PyLinksException):
+    """Error parsing a media type."""
+    def __init__(self, message: str, media_type: str):
+        msg = f"Failed to parse media type '{media_type}': {message}"
+        super().__init__(message=msg)
+        self.message = message
+        self.media_type = media_type
+        return
+
+
+class PyLinksMediaTypeGuessError(_PyLinksException):
+    """Error guessing the media type of a data URI."""
+    def __init__(self, path: str):
+        msg = f"Failed to guess the media type of '{path}'."
+        super().__init__(message=msg)
+        self.path = path
+        return

pylinks-0.0.0.dev25/src/pylinks/exception/uri.py

@@ -0,0 +1,13 @@
+from pathlib import Path as _Path
+
+from pylinks.exception import PyLinksException as _PyLinksException
+
+
+class PyLinksDataURIParseError(_PyLinksException):
+    """Error parsing a data URI."""
+    def __init__(self, message: str, data_uri: str):
+        msg = f"Failed to parse data URI '{data_uri}': {message}"
+        super().__init__(message=msg)
+        self.message = message
+        self.data_uri = data_uri
+        return

{PyLinks-0.0.0.dev23 → pylinks-0.0.0.dev25}/src/pylinks/http.py

@@ -20,7 +20,7 @@ import time
 from functools import wraps
 from pathlib import Path
 import requests
-from pylinks import exceptions
+import pylinks as _pylinks
 
 
 class RetryConfig(NamedTuple):
@@ -73,7 +73,7 @@ class HTTPRequestRetryConfig(NamedTuple):
 
 
 def request(
-    url: str,
+    url: str | _pylinks.url.URL,
     verb: Union[str, Literal["GET", "POST", "PUT", "PATCH", "OPTIONS", "DELETE"]] = "GET",
     params: Optional[Union[dict, List[tuple], bytes]] = None,
     data: Optional[Union[dict, List[tuple], bytes]] = None,
@@ -150,24 +150,27 @@ def request(
 
     def get_response_value():
         def get_response():
-            response = requests.request(
-                method=verb,
-                url=str(url),
-                params=params,
-                data=data,
-                headers=headers,
-                cookies=cookies,
-                files=files,
-                auth=auth,
-                timeout=timeout,
-                allow_redirects=allow_redirects,
-                proxies=proxies,
-                hooks=hooks,
-                stream=stream,
-                verify=verify,
-                cert=cert,
-                json=json,
-            )
+            try:
+                response = requests.request(
+                    method=verb,
+                    url=str(url),
+                    params=params,
+                    data=data,
+                    headers=headers,
+                    cookies=cookies,
+                    files=files,
+                    auth=auth,
+                    timeout=timeout,
+                    allow_redirects=allow_redirects,
+                    proxies=proxies,
+                    hooks=hooks,
+                    stream=stream,
+                    verify=verify,
+                    cert=cert,
+                    json=json,
+                )
+            except requests.exceptions.RequestException as e:
+                raise _pylinks.exceptions.WebAPIRequestError(e) from e
             _raise_for_status_code(
                 response=response,
                 temporary_error_status_codes=(
@@ -189,7 +192,7 @@ def request(
             else _retry_on_exception(
                 get_response,
                 config=retry_config.config_status,
-                catch=exceptions.WebAPITemporaryStatusCodeError,
+                catch=_pylinks.exceptions.WebAPITemporaryStatusCodeError,
             )
         )
         # Call the (decorated or non-decorated) response function.
@@ -212,7 +215,7 @@ def request(
         if response_verifier is None or response_verifier(response_value):
             return response_value
         # otherwise raise
-        raise exceptions.WebAPIValueError(response_value=response_value, response_verifier=response_verifier)
+        raise _pylinks.exceptions.WebAPIValueError(response_value=response_value, response_verifier=response_verifier)
 
     # Depending on specifications in argument `retry_config`, either decorate `get_response_value`
     # with `retry_on_exception`, or leave it as is.
@@ -226,7 +229,7 @@ def request(
         else _retry_on_exception(
             get_response_value,
             config=retry_config.config_response,
-            catch=exceptions.WebAPIValueError,
+            catch=_pylinks.exceptions.WebAPIValueError,
         )
     )
     # Call the (decorated or non-decorated) response-value function and return.
@@ -266,9 +269,9 @@ def graphql_query(
     response = request(**args)
     if isinstance(response, dict):
         if "errors" in response:
-            raise exceptions.WebAPIError(response)
+            raise _pylinks.exceptions.WebAPIError(response)
         elif "data" not in response:
-            raise exceptions.WebAPIError(response)
+            raise _pylinks.exceptions.WebAPIError(response)
         else:
             response = response["data"]
     return response
@@ -352,9 +355,9 @@ def _raise_for_status_code(
         temporary_error_status_codes is not None
         and response.status_code in temporary_error_status_codes
     ):
-        raise exceptions.WebAPITemporaryStatusCodeError(response)
+        raise _pylinks.exceptions.WebAPITemporaryStatusCodeError(response)
     if error_status_code_range[0] <= response.status_code <= error_status_code_range[1]:
-        raise exceptions.WebAPIPersistentStatusCodeError(response)
+        raise _pylinks.exceptions.WebAPIPersistentStatusCodeError(response)
     return
 
 

pylinks-0.0.0.dev25/src/pylinks/media_type.py

@@ -0,0 +1,111 @@
+"""Create and parse [media types](https://en.wikipedia.org/wiki/Media_type).
+
+References
+----------
+- [Offical IANA Media Types](https://www.iana.org/assignments/media-types/media-types.xml)
+- [Common MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types)
+- [Database of mime types](https://github.com/jshttp/mime-db/tree/master)
+- [Database of mime types](https://github.com/patrickmccallum/mimetype-io/blob/master/src/mimeData.json)
+- [JSON list of file extensions with their mime types](https://github.com/micnic/mime.json)
+- [Python mimetypes](https://docs.python.org/3/library/mimetypes.html)
+"""
+
+import mimetypes as _mimetypes
+import dataclasses as _dataclasses
+import re as _re
+
+from pylinks import exception as _exception
+
+
+@_dataclasses.dataclass
+class MediaType:
+    """A [Media Type](https://www.iana.org/assignments/media-types/media-types.xhtml) (aka MIME type).
+
+    A media type consists of a type, a subtype with optional tree prefix,
+    optional suffixes, and optional parameters in the following format:
+    ```
+    media-type = type "/" [tree "."] subtype ["+" suffix]* [";" parameter];
+    ```
+
+    Attributes
+    ----------
+    type : str, default: ""
+        Type of the media. Standard types are
+        'application', 'audio', 'example', 'font', 'haptics',
+        'image', 'message', 'model', 'multipart', 'text', and 'video'.
+    tree : str, default: ""
+        Tree prefix of the media type, e.g., 'vnd', 'prs', 'x'.
+    subtype : str, default: ""
+        Subtype of the media (without the tree prefix), e.g.,
+        'json', 'ms-excel', 'oasis.opendocument.text'.
+    suffixes : list[str], default: []
+        Type suffixes, e.g., 'json', 'xml', 'zip'.
+    parameters : dict[str, str | None], default: {}
+        Additional parameters, e.g., `{"charset": "UTF-8"}`.
+    """
+    type: str
+    subtype: str
+    tree: str = ""
+    suffixes: list[str] = _dataclasses.field(default_factory=list)
+    parameters: dict[str, str | None] = _dataclasses.field(default_factory=dict)
+
+    def __str__(self) -> str:
+        suffixes = "".join(f"+{suffix}" for suffix in self.suffixes)
+        if self.parameters:
+            joined = "; ".join(f"{k}={v}" if v else k for k, v in self.parameters.items())
+            params = f"; {joined}"
+        else:
+            params = ""
+        full_subtype = f"{self.tree}.{self.subtype}" if self.tree else self.subtype
+        return f"{self.type}/{full_subtype}{suffixes}{params}"
+
+
+def parse(media_type: str) -> MediaType:
+    regex = _re.compile(
+        r"""
+            ^
+            (?P<type>[\w\-]+)
+            /
+            (?:(?P<tree>[\w\-]+)\.)?
+            (?P<subtype>[\w\-.]+)
+            (?P<suffixes>(\+[\w\-.]+)*)?
+            (?:\s*;\s*(?P<parameters>.*))?
+            $
+        """,
+        _re.VERBOSE
+    )
+    match = regex.match(media_type)
+    if not match:
+        raise _exception.media_type.PyLinksMediaTypeParseError(
+            f"The input does not match the regex pattern '{regex.pattern}'.",
+            media_type
+        )
+    mime = match.groupdict()
+    mime["suffixes"] = [suffix for suffix in mime.get("suffixes", "").split("+") if suffix]
+    params = {}
+    if mime["parameters"]:
+        for param in mime["parameters"].split(";"):
+            key, *value = param.split("=", 1)
+            params[key.strip()] = value[0].strip() if value else None
+    mime["parameters"] = params
+    return MediaType(**mime)
+
+
+def guess_from_uri(uri: str) -> MediaType:
+    """Guess the media type of a given URI (e.g. URL or filepath).
+
+    Parameters
+    ----------
+    uri : str
+        The URI to guess the media type from.
+
+    Returns
+    -------
+    MediaType
+        The guessed media type.
+    """
+    uri = str(uri)
+    mimetype = _mimetypes.guess_type(uri)[0]
+    if mimetype is None:
+        raise _exception.media_type.PyLinksMediaTypeGuessError(uri)
+    return parse(mimetype)

pylinks-0.0.0.dev25/src/pylinks/site/__init__.py

@@ -0,0 +1 @@
+from pylinks.site import binder, conda, github, pypi, readthedocs, lib_io