PyLinks 0.0.0.dev27__tar.gz → 0.0.0.dev28__tar.gz

{pylinks-0.0.0.dev27 → pylinks-0.0.0.dev28}/PKG-INFO

@@ -1,5 +1,7 @@
 Metadata-Version: 2.1
 Name: PyLinks
-Version: 0.0.0.dev27
+Version: 0.0.0.dev28
 Requires-Python: >=3.10
 Requires-Dist: requests<3,>=2.31.0
+Requires-Dist: ExceptionMan==0.0.0.dev15
+Requires-Dist: MDit==0.0.0.dev15

pylinks-0.0.0.dev28/README.md

@@ -0,0 +1,4 @@
+# PyLinks
+
+Web-API implementations and URI utilities for Python.
+PyLinks also includes implementations for the following Web-APIs: GitHub, DOI, ORCID.

{pylinks-0.0.0.dev27 → pylinks-0.0.0.dev28}/pyproject.toml

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

{pylinks-0.0.0.dev27 → pylinks-0.0.0.dev28}/src/PyLinks.egg-info/PKG-INFO

@@ -1,5 +1,7 @@
 Metadata-Version: 2.1
 Name: PyLinks
-Version: 0.0.0.dev27
+Version: 0.0.0.dev28
 Requires-Python: >=3.10
 Requires-Dist: requests<3,>=2.31.0
+Requires-Dist: ExceptionMan==0.0.0.dev15
+Requires-Dist: MDit==0.0.0.dev15

{pylinks-0.0.0.dev27 → pylinks-0.0.0.dev28}/src/PyLinks.egg-info/SOURCES.txt

@@ -1,3 +1,4 @@
+README.md
 pyproject.toml
 src/PyLinks.egg-info/PKG-INFO
 src/PyLinks.egg-info/SOURCES.txt
@@ -7,7 +8,6 @@ src/PyLinks.egg-info/requires.txt
 src/PyLinks.egg-info/top_level.txt
 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
@@ -17,6 +17,7 @@ src/pylinks/api/doi.py
 src/pylinks/api/github.py
 src/pylinks/api/orcid.py
 src/pylinks/exception/__init__.py
+src/pylinks/exception/api.py
 src/pylinks/exception/base.py
 src/pylinks/exception/media_type.py
 src/pylinks/exception/uri.py

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

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

{pylinks-0.0.0.dev27 → pylinks-0.0.0.dev28}/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, uri, media_type, string
+from pylinks import url, http, api, site, uri, media_type, string

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

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

pylinks-0.0.0.dev28/src/pylinks/exception/api.py

@@ -0,0 +1,166 @@
+"""Custom exceptions raised by the package."""
+
+from __future__ import annotations as _annotations
+
+from typing import TYPE_CHECKING as _TYPE_CHECKING
+
+import mdit as _mdit
+from pylinks.exception import PyLinksError
+
+if _TYPE_CHECKING:
+    from typing import Any, Callable
+    from requests import PreparedRequest, Request, Response
+    from requests.exceptions import RequestException
+
+
+class WebAPIError(PyLinksError):
+    """Base Exception class for all web API exceptions."""
+    pass
+
+
+class WebAPIRequestError(WebAPIError):
+    def __init__(self, request_error: RequestException):
+        self.request = request_error.request
+        self.response = request_error.response
+        details = []
+        if self.request:
+            details.append(_process_request(self.request))
+        if self.response:
+            summary, response_details = _process_response(self.response)
+            details.append(response_details)
+
+        super().__init__(
+            title="Web API Request Error",
+            intro=str(request_error),
+            details=_mdit.block_container(*details) if details else None,
+        )
+        return
+
+
+class WebAPIStatusCodeError(WebAPIError):
+    """
+    Base Exception class for web API status code related exceptions.
+    By default, raised when status code is in range [400, 600).
+    """
+
+    def __init__(self, response: Response):
+        self.request = response.request
+        self.response = response
+        response_summary, response_details = _process_response(response)
+        details = _mdit.block_container(
+            _process_request(self.request),
+            response_details,
+        )
+        super().__init__(
+            title="Web API Status Code Error",
+            intro=response_summary,
+            details=details,
+        )
+        return
+
+
+class WebAPITemporaryStatusCodeError(WebAPIStatusCodeError):
+    """
+    Exception class for status code errors related to temporary issues.
+    By default, raised when status code is in (408, 429, 500, 502, 503, 504).
+    """
+    pass
+
+
+class WebAPIPersistentStatusCodeError(WebAPIStatusCodeError):
+    """
+    Exception class for status code errors related to persistent issues.
+    By default, raised when status code is in range [400, 600),
+    but not in (408, 429, 500, 502, 503, 504).
+    """
+    pass
+
+
+class WebAPIValueError(WebAPIError):
+    """
+    Exception class for response value errors.
+    """
+
+    def __init__(self, response_value: Any, response_verifier: Callable[[Any], bool]):
+        self.response_value = response_value
+        self.response_verifier = response_verifier
+        error_msg = (
+            f"Response verifier function {response_verifier} failed to verify {response_value}."
+        )
+        super().__init__(
+            title="Web API Response Verification Error",
+            intro=error_msg,
+        )
+        return
+
+
+def _process_response(response: Response):
+    # Decode error reason from server
+    # This part is adapted from `requests` library; See PR #3538 on their GitHub
+    if isinstance(response.reason, bytes):
+        try:
+            reason = response.reason.decode("utf-8")
+        except UnicodeDecodeError:
+            reason = response.reason.decode("iso-8859-1")
+    else:
+        reason = response.reason
+
+    response_info = []
+    response_summary = _mdit.element.field_list()
+    side = "Client" if response.status_code < 500 else "Server"
+    for title, value in (
+        ("Status Code", response.status_code),
+        ("Side", side),
+        ("Reason", reason),
+        ("URL", response.url),
+    ):
+        if value:
+            response_summary.append(
+                title=title,
+                body=_mdit.element.code_span(str(value)),
+            )
+    if response_summary.content.elements():
+        response_info.append(response_summary)
+    if response.text:
+        response_info.append(
+            _mdit.element.code_block(response.text, caption="Content")
+        )
+    summary = f"HTTP {response.status_code} error ({side.lower()} side) from {response.url}: {reason}"
+    return summary, _mdit.element.dropdown(
+        title="Response",
+        body=response_info,
+        icon="📥"
+    )
+
+
+def _process_request(request: Request | PreparedRequest):
+    request_info = []
+    request_summary = _mdit.element.field_list()
+    for title, attr_name in (
+        ("Method", "method"),
+        ("URL", "url"),
+    ):
+        value = getattr(request, attr_name, None)
+        if value:
+            request_summary.append(
+                title=title,
+                body=_mdit.element.code_span(value),
+            )
+    if request_summary.content.elements():
+        request_info.append(request_summary)
+    for title, attr_name in (
+        ("Data", "data"),
+        ("JSON", "json"),
+        ("Parameters", "params"),
+        ("Body", "body"),
+    ):
+        value = getattr(request, attr_name, None)
+        if value:
+            request_info.append(
+                _mdit.element.code_block(str(value), caption=title)
+            )
+    return _mdit.element.dropdown(
+        title="Request",
+        body=request_info,
+        icon="📤"
+    )

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

@@ -0,0 +1,50 @@
+"""PyLinks base exception."""
+
+from __future__ import annotations as _annotations
+from typing import TYPE_CHECKING as _TYPE_CHECKING
+from functools import partial as _partial
+
+from exceptionman import ReporterException as _ReporterException
+import mdit as _mdit
+
+if _TYPE_CHECKING:
+    from pathlib import Path
+
+
+class PyLinksError(_ReporterException):
+    """Base exception for PyLinks.
+
+    All exceptions raised by PyLinks inherit from this class.
+    """
+    def __init__(
+        self,
+        title: str,
+        intro,
+        details = None,
+    ):
+        sphinx_config = {"html_title": "PyLinks Error Report"}
+        sphinx_target_config = _mdit.target.sphinx(
+            renderer=_partial(
+                _mdit.render.sphinx,
+                config=_mdit.render.get_sphinx_config(sphinx_config)
+            )
+        )
+        report = _mdit.document(
+            heading=title,
+            body={"intro": intro},
+            section={"details": _mdit.document(heading="Details", body=details)} if details else None,
+            target_configs_md={"sphinx": sphinx_target_config},
+        )
+        super().__init__(report=report)
+        return
+
+
+class PyLinksFileNotFoundError(PyLinksError):
+    """File not found error."""
+    def __init__(self, path: Path):
+        super().__init__(
+            title="File Not Found Error",
+            intro=_mdit.inline_container("No file found at input path ", _mdit.element.code_span(str(path))),
+        )
+        self.path = path
+        return

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

@@ -0,0 +1,34 @@
+import mdit as _mdit
+
+from pylinks.exception import PyLinksError as _PyLinksError
+
+
+class PyLinksMediaTypeParseError(_PyLinksError):
+    """Error parsing a media type."""
+    def __init__(self, problem: str, media_type: str):
+        super().__init__(
+            title="Media Type Parse Error",
+            intro=_mdit.inline_container(
+                "Failed to parse media type ",
+                _mdit.element.code_span(media_type),
+                ". ",
+                problem,
+            )
+        )
+        self.problem = problem
+        self.media_type = media_type
+        return
+
+
+class PyLinksMediaTypeGuessError(_PyLinksError):
+    """Error guessing the media type of a data URI."""
+    def __init__(self, path: str):
+        super().__init__(
+            title="Media Type Guess Error",
+            intro=_mdit.inline_container(
+                "Failed to guess the media type of the file at path ",
+                _mdit.element.code_span(path),
+            )
+        )
+        self.path = path
+        return

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

@@ -0,0 +1,20 @@
+import mdit as _mdit
+
+from pylinks.exception import PyLinksError as _PyLinksError
+
+
+class PyLinksDataURIParseError(_PyLinksError):
+    """Error parsing a data URI."""
+    def __init__(self, problem: str, data_uri: str):
+        super().__init__(
+            title="Data URI Parse Error",
+            intro=_mdit.inline_container(
+                "Failed to parse data URI ",
+                _mdit.element.code_span(data_uri),
+                ". ",
+                problem,
+            )
+        )
+        self.problem = problem
+        self.data_uri = data_uri
+        return

{pylinks-0.0.0.dev27 → pylinks-0.0.0.dev28}/src/pylinks/http.py

@@ -1,29 +1,35 @@
 """
 Handling HTTP requests and responses.
 """
+from __future__ import annotations as _annotations
 
+from typing import TYPE_CHECKING as _TYPE_CHECKING, NamedTuple as _NamedTuple
 
-from typing import (
-    Any,
-    Callable,
-    List,
-    Literal,
-    NamedTuple,
-    NoReturn,
-    Optional,
-    Sequence,
-    Tuple,
-    Union,
-    Type,
-)
 import time
 from functools import wraps
 from pathlib import Path
 import requests
-import pylinks as _pylinks
+
+from pylinks.exception import api as _exception
+
+if _TYPE_CHECKING:
+    from typing import (
+        Any,
+        Callable,
+        List,
+        Literal,
+        NoReturn,
+        Optional,
+        Sequence,
+        Tuple,
+        Union,
+        Type,
+    )
+    from pylinks.url import URL
+
 
 
-class RetryConfig(NamedTuple):
+class RetryConfig(_NamedTuple):
     """
     Configuration for the `retry_on_exception` decorator.
 
@@ -46,7 +52,7 @@ class RetryConfig(NamedTuple):
     sleep_time_scale: float = 3
 
 
-class HTTPRequestRetryConfig(NamedTuple):
+class HTTPRequestRetryConfig(_NamedTuple):
     """
     Configurations for retrying an HTTP request
     sent by `opencadd.webapi.http_request.response_http_request`.
@@ -73,7 +79,7 @@ class HTTPRequestRetryConfig(NamedTuple):
 
 
 def request(
-    url: str | _pylinks.url.URL,
+    url: str | 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,
@@ -170,7 +176,7 @@ def request(
                     json=json,
                 )
             except requests.exceptions.RequestException as e:
-                raise _pylinks.exceptions.WebAPIRequestError(e) from e
+                raise _exception.WebAPIRequestError(e) from e
             _raise_for_status_code(
                 response=response,
                 temporary_error_status_codes=(
@@ -192,7 +198,7 @@ def request(
             else _retry_on_exception(
                 get_response,
                 config=retry_config.config_status,
-                catch=_pylinks.exceptions.WebAPITemporaryStatusCodeError,
+                catch=_exception.WebAPITemporaryStatusCodeError,
             )
         )
         # Call the (decorated or non-decorated) response function.
@@ -215,13 +221,12 @@ def request(
         if response_verifier is None or response_verifier(response_value):
             return response_value
         # otherwise raise
-        raise _pylinks.exceptions.WebAPIValueError(response_value=response_value, response_verifier=response_verifier)
+        raise _exception.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.
     response_val_func = (
-        get_response_value
-        if (
+        get_response_value if (
             retry_config is None
             or retry_config.config_response is None
             or response_verifier is None
@@ -229,7 +234,7 @@ def request(
         else _retry_on_exception(
             get_response_value,
             config=retry_config.config_response,
-            catch=_pylinks.exceptions.WebAPIValueError,
+            catch=_exception.WebAPIValueError,
         )
     )
     # Call the (decorated or non-decorated) response-value function and return.
@@ -269,9 +274,9 @@ def graphql_query(
     response = request(**args)
     if isinstance(response, dict):
         if "errors" in response:
-            raise _pylinks.exceptions.WebAPIError(response)
+            raise _exception.WebAPIError(response)
         elif "data" not in response:
-            raise _pylinks.exceptions.WebAPIError(response)
+            raise _exception.WebAPIError(response)
         else:
             response = response["data"]
     return response
@@ -355,9 +360,9 @@ def _raise_for_status_code(
         temporary_error_status_codes is not None
         and response.status_code in temporary_error_status_codes
     ):
-        raise _pylinks.exceptions.WebAPITemporaryStatusCodeError(response)
+        raise _exception.WebAPITemporaryStatusCodeError(response)
     if error_status_code_range[0] <= response.status_code <= error_status_code_range[1]:
-        raise _pylinks.exceptions.WebAPIPersistentStatusCodeError(response)
+        raise _exception.WebAPIPersistentStatusCodeError(response)
     return
 
 

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

@@ -1 +0,0 @@
-requests<3,>=2.31.0

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

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

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

@@ -1,23 +0,0 @@
-"""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.dev27/src/pylinks/exception/media_type.py

@@ -1,20 +0,0 @@
-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.dev27/src/pylinks/exception/uri.py

@@ -1,13 +0,0 @@
-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.dev27/src/pylinks/exceptions.py

@@ -1,74 +0,0 @@
-"""Custom exceptions raised by the package."""
-
-
-from typing import Any, Callable
-import requests
-
-
-class WebAPIError(IOError):
-    """Base Exception class for all web API exceptions."""
-    pass
-
-
-class WebAPIStatusCodeError(WebAPIError):
-    """
-    Base Exception class for web API status code related exceptions.
-    By default, raised when status code is in range [400, 600).
-    """
-
-    def __init__(self, response: requests.Response):
-        self.response: requests.Response = response
-        # Decode error reason from server
-        # This part is adapted from `requests` library; See PR #3538 on their GitHub
-        if isinstance(response.reason, bytes):
-            try:
-                self.reason = response.reason.decode("utf-8")
-            except UnicodeDecodeError:
-                self.reason = response.reason.decode("iso-8859-1")
-        else:
-            self.reason = response.reason
-        self.response_msg = response.text
-        self.side = "client" if response.status_code < 500 else "server"
-        self.status_code = response.status_code
-        self.url = response.url
-
-        error_msg = (
-            f"HTTP {self.side} error (status code: {self.status_code})\n"
-            f"- From: {self.url}\n"
-            f"- Reason: {self.reason}\n"
-            f"- Response: {self.response_msg}"
-        )
-        super().__init__(error_msg)
-        return
-
-
-class WebAPITemporaryStatusCodeError(WebAPIStatusCodeError):
-    """
-    Exception class for status code errors related to temporary issues.
-    By default, raised when status code is in (408, 429, 500, 502, 503, 504).
-    """
-    pass
-
-
-class WebAPIPersistentStatusCodeError(WebAPIStatusCodeError):
-    """
-    Exception class for status code errors related to persistent issues.
-    By default, raised when status code is in range [400, 600),
-    but not in (408, 429, 500, 502, 503, 504).
-    """
-    pass
-
-
-class WebAPIValueError(WebAPIError):
-    """
-    Exception class for response value errors.
-    """
-
-    def __init__(self, response_value: Any, response_verifier: Callable[[Any], bool]):
-        self.response_value = response_value
-        self.response_verifier = response_verifier
-        error_msg = (
-            f"Response verifier function {response_verifier} failed to verify {response_value}."
-        )
-        super().__init__(error_msg)
-        return