PyLinks 0.0.0.dev24__tar.gz → 0.0.0.dev26__tar.gz

{pylinks-0.0.0.dev24 → pylinks-0.0.0.dev26}/PKG-INFO

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

{pylinks-0.0.0.dev24 → pylinks-0.0.0.dev26}/pyproject.toml

@@ -17,7 +17,7 @@ namespaces = true
 # ----------------------------------------- Project Metadata -------------------------------------
 #
 [project]
-version = "0.0.0.dev24"
+version = "0.0.0.dev26"
 name = "PyLinks"
 dependencies = [
     "requests >= 2.31.0, < 3",

{pylinks-0.0.0.dev24 → pylinks-0.0.0.dev26}/src/PyLinks.egg-info/PKG-INFO

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

{pylinks-0.0.0.dev24 → pylinks-0.0.0.dev26}/src/PyLinks.egg-info/SOURCES.txt

@@ -9,15 +9,23 @@ src/pylinks/__init__.py
 src/pylinks/_settings.py
 src/pylinks/exceptions.py
 src/pylinks/http.py
+src/pylinks/media_type.py
+src/pylinks/string.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.dev24 → pylinks-0.0.0.dev26}/src/pylinks/__init__.py

@@ -12,4 +12,4 @@ Other available modules offer shortcuts for creating useful URLs for popular onl
 """
 
 from pylinks._settings import settings
-from pylinks import url, http, api, site, exceptions
+from pylinks import url, http, api, site, exceptions, uri, media_type

{pylinks-0.0.0.dev24 → pylinks-0.0.0.dev26}/src/pylinks/api/github.py

@@ -99,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,
@@ -143,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,
@@ -369,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.
@@ -385,7 +387,7 @@ 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.
@@ -846,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):
@@ -1502,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.dev26/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.dev26/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.dev26/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.dev26/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.dev24 → pylinks-0.0.0.dev26}/src/pylinks/http.py

@@ -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=(

pylinks-0.0.0.dev26/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.dev26/src/pylinks/string.py

@@ -0,0 +1,39 @@
+import re as _re
+import unicodedata as _unicodedata
+
+
+def to_slug(string: str) -> str:
+    """Convert a string to a URL-friendly slug.
+
+    This function performs unicode-normalization on the string,
+    converts it to lowercase,
+    replaces any non-alphanumeric characters with hyphens, and
+    removes leading and trailing hyphens.
+    """
+    # Normalize the string to decompose special characters
+    normalized_string = _unicodedata.normalize('NFKD', string)
+    # Encode the string to ASCII bytes, ignoring non-ASCII characters
+    ascii_bytes = normalized_string.encode('ascii', 'ignore')
+    # Decode back to a string
+    ascii_string = ascii_bytes.decode('ascii')
+    lower_case_string = ascii_string.lower()
+    return _re.sub(r'[^a-z0-9]+', '-', lower_case_string).strip('-')
+
+
+def camel_to_title(string: str) -> str:
+    """Convert a 'CamelCase' string to a 'Title Case' string.
+
+    This function inserts spaces before each uppercase letter (except the first letter)
+    and capitalizes the first letter of each word.
+    """
+    # Insert spaces before each uppercase letter (except the first letter)
+    spaced_str = _re.sub(r'(?<!^)(?=[A-Z])', ' ', string)
+    # Convert to title-case
+    title_str = spaced_str.title()
+    return title_str
+
+
+def snake_to_camel(string):
+    components = string.split('_')
+    return ''.join([components[0]] + [x.title() for x in components[1:]])
+

pylinks-0.0.0.dev26/src/pylinks/uri/__init__.py

@@ -0,0 +1 @@
+from pylinks.uri import data

pylinks-0.0.0.dev26/src/pylinks/uri/data.py

@@ -0,0 +1,200 @@
+"""Generate and process [data URIs](https://en.wikipedia.org/wiki/Data_URI_scheme).
+
+"""
+
+import base64 as _base64
+import re as _re
+from pathlib import Path as _Path
+import dataclasses as _dataclasses
+from typing import Literal as _Literal
+
+from pylinks.url import URL as _URL
+from pylinks.http import request as _request
+from pylinks import media_type as _media_type
+from pylinks.exception.uri import PyLinksDataURIParseError as _PyLinksDataURIParseError
+from pylinks.exception.base import PyLinksFileNotFoundError as _PyLinksFileNotFoundError
+
+
+@_dataclasses.dataclass
+class DataURI:
+    """A data URI.
+
+    Attributes
+    ----------
+    media_type : pylinks.media_type.MediaType, default: ""
+        The media type of the data.
+    data : str, default: ""
+        The data.
+    base64 : bool, default: False
+        Whether the data is base64 encoded.
+    """
+    media_type: _media_type.MediaType | None = None
+    data: str | None = None
+    base64: bool = False
+
+    def __str__(self) -> str:
+        media_type = str(self.media_type) if self.media_type else ""
+        if self.base64:
+            media_type += ";base64"
+        return f"data:{media_type},{self.data}"
+
+
+def parse(data_uri: str) -> DataURI:
+    """Parse a data URI.
+
+    Parameters
+    ----------
+    data_uri : str
+        The data URI to parse.
+
+    Returns
+    -------
+    DataURI
+        The parsed data URI.
+    """
+    regex = _re.compile(
+        r"^data:(?P<media_type>.*?)(?P<base64>\s*;\s*base64)?\s*,(?P<data>.*)$"
+    )
+    match = regex.match(data_uri)
+    if not match:
+        raise _PyLinksDataURIParseError(
+            f"The input does not match the regex pattern '{regex.pattern}'.",
+            data_uri,
+        )
+    components = match.groupdict()
+    media_type = components["media_type"] or None
+    if media_type:
+        media_type = _media_type.parse(media_type)
+    components["media_type"] = media_type
+    components["base64"] = bool(components["base64"])
+    return DataURI(**components)
+
+
+def create_from_path(
+    path_type: _Literal["file", "url"],
+    path: str,
+    media_type: _media_type.MediaType | None = None,
+    guess_media_type: bool = True,
+    base64: bool = False,
+) -> DataURI:
+    if path_type == "file":
+        return create_from_filepath(
+            filepath=path,
+            media_type=media_type,
+            guess_media_type=guess_media_type,
+            base64=base64,
+        )
+    elif path_type == "url":
+        return create_from_url(
+            url=path,
+            media_type=media_type,
+            guess_media_type=guess_media_type,
+            base64=base64,
+        )
+    raise ValueError(f"path_type '{path_type}' is invalid.")
+
+
+def create_from_url(
+    url: str | _URL,
+    media_type: _media_type.MediaType | None = None,
+    guess_media_type: bool = True,
+    base64: bool = False,
+) -> DataURI:
+    """Create a data URI from a URL.
+
+    Parameters
+    ----------
+    url : str | pylinks.url.URL
+        The URL of the data.
+    media_type : pylinks.media_type.MediaType | str | None, optional
+        Media (MIME) Type of the data.
+    guess_media_type : bool, default: True
+        Whether to guess the media type from the URL.
+        This is only done if the media type is not provided,
+        and will raise an error if the media type cannot be guessed.
+    base64 : bool, default: False
+        Whether to base64 encode the data.
+
+    Returns
+    -------
+    pylinks.uri.data.DataURI
+        The data URI.
+    """
+    url = str(url)
+    if media_type is None and guess_media_type:
+        media_type = _media_type.guess_from_uri(url)
+    data = _request(url, response_type="str" if not base64 else "bytes")
+    return create_from_data(data=data, media_type=media_type, base64=base64)
+
+
+def create_from_filepath(
+    filepath: str | _Path,
+    media_type: _media_type.MediaType | None = None,
+    guess_media_type: bool = True,
+    base64: bool = False,
+) -> DataURI:
+    """Create a data URI from a file.
+
+    Parameters
+    ----------
+    filepath : str | pathlib.Path
+        Path to the file.
+    media_type : pylinks.media_type.MediaType | str | None, optional
+        Media (MIME) Type of the data.
+    guess_media_type : bool, default: True
+        Whether to guess the media type from the URL.
+        This is only done if the media type is not provided,
+        and will raise an error if the media type cannot be guessed.
+    base64 : bool, default: False
+        Whether to base64 encode the data.
+
+    Returns
+    -------
+    pylinks.uri.data.DataURI
+        The data URI.
+    """
+    filepath = _Path(filepath).resolve()
+    if not filepath.is_file():
+        raise _PyLinksFileNotFoundError(filepath)
+    if media_type is None and guess_media_type:
+        media_type = _media_type.guess_from_uri(str(filepath))
+    data = filepath.read_bytes() if base64 else filepath.read_text()
+    return create_from_data(data=data, media_type=media_type, base64=base64)
+
+
+def create_from_data(
+    data: str | bytes,
+    media_type: _media_type.MediaType | None = None,
+    base64: bool = False,
+) -> DataURI:
+    """Create a data URI.
+
+    Parameters
+    ----------
+    media_type : str | list[str | tuple[str, str]] | dict[str, str | None], optional
+        The media type of the data.
+        This can be either a fully formed media type as a string,
+        a dictionary of parameter name and value pairs (using None for parameters without values),
+        or an iterable where the elements are either strings (for parameters without values)
+        or tuples of parameter name and value.
+        For example, all of the following are valid and equivalent:
+        - As a string: "text/plain;charset=UTF-8"
+        - As a list of strings (attribute-value pairs not separated): `["text/plain", "charset=UTF-8"]`
+        - As a list of strings and tuples: `["text/plain", ("charset", "UTF-8")]`
+        - As a dictionary: `{"text/plain": None, "charset": "UTF-8"}`
+    data : str, optional
+        The data to include in the URI.
+    base64 : bool, default: False
+        Whether the data is base64 encoded.
+
+    Returns
+    -------
+    str
+        The data URI.
+    """
+    if base64:
+        data_bytes = data.encode() if isinstance(data, str) else data
+        data_str = _base64.b64encode(data_bytes).decode()
+    else:
+        data_str = data
+    return DataURI(media_type=media_type, data=data_str, base64=base64)

{pylinks-0.0.0.dev24 → pylinks-0.0.0.dev26}/src/pylinks/url.py

@@ -1,7 +1,6 @@
 """Create and modify URLs."""
 
-
-# Standard libraries
+from __future__ import annotations
 import re
 import urllib
 import webbrowser
@@ -59,14 +58,9 @@ class URL:
         Add a path at the end of the base URL (while preserving the query string and fragment),
         and return a new copy.
         """
-        if not isinstance(path, str):
-            raise TypeError("Adding a path can only be performed on strings.")
-        if path.startswith("/"):
-            path = path[1:]
-        if path.endswith("/"):
-            path = path[:-1]
+        path = str(path or "")
         return URL(
-            base=f"{self.base}/{path}",
+            base=f"{self.base.removesuffix("/")}/{path.removeprefix("/")}" if path else self.base,
             queries=self.queries.copy(),
             fragment=self.fragment,
             query_delimiter=self.query_delimiter,
@@ -99,31 +93,19 @@ class URL:
         for key, val in self.queries.items():
             if val is None:
                 continue
-            q_key = urllib.parse.quote(str(key), safe=self.quote_safe)
+            q_key = urllib.parse.quote(urllib.parse.unquote(str(key)), safe=self.quote_safe)
             if isinstance(val, bool) and val is True:
                 queries.append(q_key)
             else:
                 q_val = (
                     val.decode("utf8")
                     if isinstance(val, bytes)
-                    else urllib.parse.quote(str(val), safe=self.quote_safe)
+                    else urllib.parse.quote(urllib.parse.unquote(str(val)), safe=self.quote_safe)
                 )
                 queries.append(f"{q_key}={q_val}")
         return self.query_delimiter.join(queries)
 
-    def add_path(self, path: str) -> None:
-        """
-        Add a path to the end of the base URL, while preserving the query string and fragment.
-        This modifies the current instance in place.
-        """
-        if path.startswith("/"):
-            path = path[1:]
-        if path.endswith("/"):
-            path = path[:-1]
-        self.base += f"/{path}"
-        return
-
-    def copy(self) -> "URL":
+    def copy(self) -> URL:
         """Create a new copy."""
         return self.__copy__()
 
@@ -172,7 +154,7 @@ def create(
         Delimiter for the query string.
     """
     base, base_queries, base_fragment = _process_url(url, query_delimiter=query_delimiter)
-    queries = base_queries | queries if queries else base_queries
+    queries = base_queries | (queries or {})
     fragment = fragment if fragment else base_fragment
     return URL(
         base=base,