pybc365 0.1.0__py3-none-any.whl

pybc365/__init__.py

@@ -0,0 +1,83 @@
+"""
+A modern, fully typed Python client for Microsoft Dynamics 365 Business Central.
+
+The package reads published OData V4 web services from one company on one
+server. Every read starts at Client and runs through Query.
+
+Examples:
+    >>> import httpx
+    >>> import pybc365
+    >>> client = pybc365.Client(
+    ...     base_url="https://bc.example.com/BC",
+    ...     company="CRONUS",
+    ...     auth=httpx.BasicAuth("user", "token"),
+    ... )
+    >>> rows = client.service("Customers").all()  # doctest: +SKIP
+"""
+
+from httpx import Auth
+
+from ._version import __version__
+from .client import Client
+from .errors import (
+    AuthenticationError,
+    AuthorizationError,
+    BadRequestError,
+    BC365Error,
+    ConfigurationError,
+    FilterError,
+    NotFoundError,
+    NotSupportedError,
+    ProtocolError,
+    ResponseError,
+    ServerError,
+    ThrottledError,
+    TransportError,
+)
+from .filters import (
+    And,
+    Comparison,
+    F,
+    Field,
+    FilterExpression,
+    InList,
+    Or,
+    Raw,
+    raw,
+)
+from .query import Converter, Order, Query, asc, desc
+from .retry import Retry
+
+__all__ = [
+    "And",
+    "Auth",
+    "AuthenticationError",
+    "AuthorizationError",
+    "BC365Error",
+    "BadRequestError",
+    "Client",
+    "Comparison",
+    "ConfigurationError",
+    "Converter",
+    "F",
+    "Field",
+    "FilterError",
+    "FilterExpression",
+    "InList",
+    "NotFoundError",
+    "NotSupportedError",
+    "Or",
+    "Order",
+    "ProtocolError",
+    "Query",
+    "Raw",
+    "ResponseError",
+    "Retry",
+    "ServerError",
+    "ThrottledError",
+    "TransportError",
+    "__version__",
+    "asc",
+    "desc",
+    "raw",
+]

pybc365/_reader.py

@@ -0,0 +1,199 @@
+"""Internal. ResponseReader turns one response into rows, a count, or an error."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from ._transport import ATTEMPTS_KEY, retry_after_seconds
+from .errors import (
+    AuthenticationError,
+    AuthorizationError,
+    BadRequestError,
+    NotFoundError,
+    NotSupportedError,
+    ProtocolError,
+    ResponseError,
+    ServerError,
+    ThrottledError,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    import httpx
+
+# The parser reads the float token as the string Business Central wrote, so it
+# sees every digit. None leaves the standard float in place.
+type _FloatParser = Callable[[str], Any] | None
+
+# An error body is cut to this many characters, so an HTML error page never
+# becomes the whole exception message.
+_MESSAGE_LIMIT = 200
+
+_CLIENT_ERROR = 400
+_SERVER_ERROR = 500
+_ABOVE_SERVER_ERROR = 600
+
+# 413 is here even though the retry layer never retries it: resending an
+# identical GET cannot shrink the response.
+_THROTTLED_STATUSES = frozenset({408, 413, 429, 503, 504})
+
+_BY_STATUS: dict[int, type[ResponseError]] = {
+    401: AuthenticationError,
+    403: AuthorizationError,
+    404: NotFoundError,
+    501: NotSupportedError,
+}
+
+
+class ResponseReader:
+    """
+    What reads one Business Central response.
+
+    The reader holds the caller's float parser and nothing else. It sends no
+    request, and it never closes a response it did not open.
+    """
+
+    def __init__(self, parse_float: _FloatParser) -> None:
+        """
+        Keep the float parser every body decodes with.
+
+        Args:
+            parse_float: How to build a number from a JSON float token. None
+                keeps the standard float.
+        """
+        self._parse_float = parse_float
+
+    def page(self, response: httpx.Response) -> tuple[list[dict[str, Any]], str | None]:
+        """
+        Return the rows of one page, and the link to the next page.
+
+        Args:
+            response: The response to read.
+
+        Returns:
+            The rows, and the next link, or None when the page is the last one.
+
+        Raises:
+            ResponseError: If the status is 400 or above.
+            ProtocolError: If the body is not an OData collection, or carries a
+                next link the library cannot follow.
+        """
+        self._raise_for_status(response)
+        body = self._json_or_none(response)
+        if not isinstance(body, dict) or not isinstance(body.get("value"), list):
+            msg = "the response is not an OData collection: no JSON 'value' array"
+            raise ProtocolError(msg, request=response.request, response=response)
+
+        value: list[dict[str, Any]] = body["value"]
+        link = body.get("@odata.nextLink")
+        if link is None:
+            return value, None
+        # A next link is sent byte for byte, so the library resolves nothing and
+        # only follows one it can send as it stands.
+        if not isinstance(link, str) or not link.startswith(("http://", "https://")):
+            msg = (
+                "the response carries an @odata.nextLink the library cannot "
+                f"follow: {link!r}"
+            )
+            raise ProtocolError(msg, request=response.request, response=response)
+        return value, link
+
+    def count(self, response: httpx.Response) -> int:
+        """
+        Return how many rows match, from the OData count beside the page.
+
+        Args:
+            response: The response to read.
+
+        Returns:
+            The row count.
+
+        Raises:
+            ResponseError: If the status is 400 or above.
+            ProtocolError: If the body carries no numeric count.
+        """
+        self._raise_for_status(response)
+        body = self._json_or_none(response)
+        count = body.get("@odata.count") if isinstance(body, dict) else None
+        # A bool is an int in Python, and true is not a count.
+        if isinstance(count, int) and not isinstance(count, bool):
+            return count
+        if isinstance(count, str):
+            try:
+                return int(count)
+            except ValueError:
+                pass
+        msg = (
+            "the response carries no numeric @odata.count, so the library cannot "
+            f"say how many rows match: {count!r}"
+        )
+        raise ProtocolError(msg, request=response.request, response=response)
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        if response.status_code >= _CLIENT_ERROR:
+            raise self._response_error(response)
+
+    def _response_error(self, response: httpx.Response) -> ResponseError:
+        status = response.status_code
+        code, message = self._error_code_and_message(response)
+        # The retry transport reports its count on a private extension key.
+        attempts = int(response.extensions.get(ATTEMPTS_KEY, 1))
+        if status in _THROTTLED_STATUSES:
+            return ThrottledError(
+                status=status,
+                code=code,
+                message=message,
+                request=response.request,
+                response=response,
+                attempts=attempts,
+                retry_after=retry_after_seconds(response),
+            )
+        return _BY_STATUS.get(status, _catch_all(status))(
+            status=status,
+            code=code,
+            message=message,
+            request=response.request,
+            response=response,
+            attempts=attempts,
+        )
+
+    def _error_code_and_message(
+        self, response: httpx.Response
+    ) -> tuple[str | None, str]:
+        body = self._json_or_none(response)
+        error = body.get("error") if isinstance(body, dict) else None
+        if not isinstance(error, dict):
+            return None, _body_text(response)
+
+        code = error.get("code")
+        message = error.get("message")
+        return (
+            code if isinstance(code, str) else None,
+            message if isinstance(message, str) else _body_text(response),
+        )
+
+    def _json_or_none(self, response: httpx.Response) -> object:
+        # The catch names the two ways a body can fail to be JSON, and no wider,
+        # because a caller's parse_float runs inside this call and its own
+        # ValueError must reach the caller rather than read as a malformed body.
+        try:
+            return response.json(parse_float=self._parse_float)
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            return None
+
+
+def _catch_all(status: int) -> type[ResponseError]:
+    if _CLIENT_ERROR <= status < _SERVER_ERROR:
+        return BadRequestError
+    if _SERVER_ERROR <= status < _ABOVE_SERVER_ERROR:
+        return ServerError
+    return ResponseError
+
+
+def _body_text(response: httpx.Response) -> str:
+    text = response.text.strip()
+    if len(text) > _MESSAGE_LIMIT:
+        return text[:_MESSAGE_LIMIT] + "..."
+    return text

pybc365/_surface.py

@@ -0,0 +1,111 @@
+"""Internal. ODataSurface builds published web service URLs."""
+
+import logging
+from urllib.parse import quote
+
+from .errors import ConfigurationError
+
+_logger = logging.getLogger("pybc365")
+
+_ROOT = "base_url is the server root, stopping before the ODataV4 or api segment."
+_NOT_REST = "The library reads published web services, not the REST API."
+
+# Each entry is (the lowercased substring to look for, the part to name back,
+# the reason to give).
+_REJECTED = (
+    ("/api/", "/api", _NOT_REST),
+    ("companies(", "companies(", _NOT_REST),
+    ("/odatav4/", "/ODataV4", _ROOT),
+    ("company(", "Company(", _ROOT),
+)
+
+
+class ODataSurface:
+    """
+    The one URL form v0.1 reads: <base_url>/ODataV4/Company('<name>')/<service>.
+
+    The surface owns every cleaning rule, so a bad base_url, company or web
+    service name raises ConfigurationError from here.
+    """
+
+    def __init__(self, *, base_url: str, company: str) -> None:
+        """
+        Clean and keep the two parts of the URL that never change.
+
+        Args:
+            base_url: The server root, stopping before the ODataV4 segment.
+            company: The company name, unescaped.
+
+        Raises:
+            ConfigurationError: If either argument is malformed.
+        """
+        self._base_url = _clean_base_url(base_url)
+        self._company = _clean_company(company)
+
+    def service_url(self, name: str) -> str:
+        """
+        Return the URL of one published web service.
+
+        Args:
+            name: The published name of the web service.
+
+        Returns:
+            The full URL to read.
+
+        Raises:
+            ConfigurationError: If name is empty.
+
+        Examples:
+            >>> surface = ODataSurface(
+            ...     base_url="https://bc.example.com/BC", company="CRONUS"
+            ... )
+            >>> surface.service_url("Customers")
+            "https://bc.example.com/BC/ODataV4/Company('CRONUS')/Customers"
+        """
+        service = _clean_service(name)
+        return f"{self._base_url}/ODataV4/Company('{self._company}')/{service}"
+
+
+def _clean_base_url(base_url: str) -> str:
+    cleaned = base_url.strip().rstrip("/")
+    scheme = cleaned.split("://", 1)[0].lower() if "://" in cleaned else ""
+    if scheme not in {"http", "https"}:
+        msg = f"base_url must start with http:// or https://, got {base_url!r}"
+        raise ConfigurationError(msg)
+
+    # The trailing slash lets one substring match both "/api/" and a bare "/api"
+    # at the end.
+    probe = f"{cleaned.lower()}/"
+    for substring, named, reason in _REJECTED:
+        if substring in probe:
+            msg = (
+                f"base_url must not contain {named!r}: delete it and everything "
+                f"after it. {reason}"
+            )
+            raise ConfigurationError(msg)
+
+    if scheme == "http":
+        _logger.warning(
+            "base_url uses http, so credentials and rows cross the network in "
+            "clear: %s",
+            cleaned,
+        )
+    return cleaned
+
+
+def _clean_company(company: str) -> str:
+    cleaned = company.strip()
+    if not cleaned:
+        msg = "company must not be empty"
+        raise ConfigurationError(msg)
+    # OData escapes a single quote by doubling it, so the doubled pair must
+    # survive quote() unencoded.
+    return quote(cleaned.replace("'", "''"), safe="'")
+
+
+def _clean_service(name: str) -> str:
+    cleaned = name.strip().strip("/").strip()
+    if not cleaned:
+        msg = f"the web service name must not be empty, got {name!r}"
+        raise ConfigurationError(msg)
+    return quote(cleaned, safe="")

pybc365/_transport.py

@@ -0,0 +1,140 @@
+"""Internal. The transport wrapper that applies the Retry policy."""
+
+from __future__ import annotations
+
+import logging
+import math
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from typing import TYPE_CHECKING
+
+import httpx
+
+from .errors import TransportError
+
+if TYPE_CHECKING:
+    from .retry import Retry
+
+_logger = logging.getLogger("pybc365")
+
+# The wrapper reports its attempt count to the error layer on this private
+# extension key. It is never public API.
+ATTEMPTS_KEY = "pybc365_attempts"
+
+
+class RetryTransport(httpx.BaseTransport):
+    """
+    A transport that sends a failed request again, following a Retry policy.
+
+    Client always installs it, so a caller-supplied transport retries too.
+    """
+
+    def __init__(self, inner: httpx.BaseTransport, retry: Retry) -> None:
+        """
+        Wrap one transport with one policy.
+
+        Args:
+            inner: The transport that sends the request.
+            retry: The policy deciding what to send again, and when.
+        """
+        self._inner = inner
+        self._retry = retry
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        """
+        Send the request, and send it again while the policy allows it.
+
+        Args:
+            request: The request to send.
+
+        Returns:
+            The final response, unread, carrying the attempt count on its
+            extensions.
+
+        Raises:
+            TransportError: If no attempt got a response.
+        """
+        attempt = 0
+        while True:
+            attempt += 1
+            final = attempt >= self._retry.max_attempts
+            try:
+                response = self._inner.handle_request(request)
+            except httpx.TransportError as exc:
+                if final:
+                    msg = f"{request.method} {request.url} failed: {exc}"
+                    raise TransportError(
+                        msg, request=request, attempts=attempt
+                    ) from exc
+                self._wait(attempt, type(exc).__name__, None)
+                continue
+
+            if final or response.status_code not in self._retry.retry_statuses:
+                response.extensions[ATTEMPTS_KEY] = attempt
+                return response
+
+            response.close()
+            self._wait(attempt, response.status_code, retry_after_seconds(response))
+
+    def close(self) -> None:
+        """Close the transport this wrapper sends through."""
+        self._inner.close()
+
+    def _wait(self, attempt: int, cause: object, retry_after: float | None) -> None:
+        delay = self._delay(attempt, retry_after)
+        _logger.warning(
+            "attempt %d of %d failed with %s, retrying in %.3f seconds",
+            attempt,
+            self._retry.max_attempts,
+            cause,
+            delay,
+        )
+        # Retry owns the two seams; the wrapper is the only reader of them.
+        self._retry._sleep(delay)  # ruff: ignore[private-member-access]
+
+    def _delay(self, attempt: int, retry_after: float | None) -> float:
+        retry = self._retry
+        if retry_after is not None:
+            return min(retry_after, retry.max_delay)
+        # An exponent past 1024 overflows, and any exponent this large is far
+        # past max_delay already.
+        exponent = min(attempt - 1, 512)
+        ceiling = min(retry.max_delay, retry.base_delay * 2.0**exponent)
+        # Full jitter: several workers against one server otherwise retry in
+        # lockstep.
+        return retry._random() * ceiling  # ruff: ignore[private-member-access]
+
+
+def retry_after_seconds(response: httpx.Response) -> float | None:
+    """
+    Return the seconds the Retry-After header asks for, if it is readable.
+
+    Args:
+        response: The response to read the header from.
+
+    Returns:
+        The seconds to wait, never negative, or None when the header is absent
+        or unparseable.
+    """
+    raw = response.headers.get("Retry-After")
+    if raw is None:
+        return None
+
+    # Retry-After comes in two forms: delta-seconds, or an HTTP date.
+    value = raw.strip()
+    try:
+        seconds = float(value)
+    except ValueError:
+        pass
+    else:
+        # A server sending a negative or a non-finite delay is telling the
+        # library nothing it can wait for.
+        return max(seconds, 0.0) if math.isfinite(seconds) else None
+
+    try:
+        when = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=UTC)
+    return max((when - datetime.now(tz=UTC)).total_seconds(), 0.0)

pybc365/_version.py

@@ -0,0 +1,9 @@
+"""Internal. The installed version of the package."""
+
+from importlib import metadata
+
+try:
+    __version__ = metadata.version("pybc365")
+except metadata.PackageNotFoundError:  # pragma: no cover
+    # The package is running from a source tree that was never installed.
+    __version__ = "0.0.0"