odatapy 5.0.0a1__py3-none-any.whl

odatapy/__init__.py

@@ -0,0 +1,29 @@
+"""odatapy — an OData v4.0 / v4.01 server and client library for Python.
+
+A port of Apache Olingo OData 5.0.0 (Java) to idiomatic Python.
+
+Quick start (server):
+
+    from odatapy.server import OData
+    from odatapy.server.inmemory import InMemoryDataStore, InMemoryProcessor
+
+    odata = OData.new_instance()
+    service_metadata = odata.create_service_metadata(MyProvider())
+    handler = odata.create_handler(service_metadata)
+    handler.register(InMemoryProcessor(store))
+    # wrap with odatapy.server.adapters.ODataASGIApp / ODataWSGIApp
+
+Quick start (client):
+
+    from odatapy.client import ODataClient
+    from odatapy.client.transport import HttpxTransport
+
+    client = ODataClient("http://host/svc", HttpxTransport())
+    products = client.get_entity_set(client.entity_set_uri("Products").filter("Price gt 10"))
+
+See PYTHON_ODATA_PORT_PLAN.md for the full roadmap.
+"""
+
+__version__ = "5.0.0a1"
+
+__all__ = ["__version__"]

odatapy/client/__init__.py

@@ -0,0 +1,26 @@
+"""OData client.
+
+Build request URIs with :class:`URIBuilder`, execute them through a pluggable
+:class:`~odatapy.client.transport.Transport` (httpx by default, or an in-process
+handler), and get back payload objects. :class:`ODataClient` is the entry point.
+"""
+
+from odatapy.client.client import EdmEnabledODataClient, ODataClient
+from odatapy.client.filters import FilterFactory, and_, not_, or_
+from odatapy.client.responses import ClientResponse, ODataClientError
+from odatapy.client.transport import HandlerTransport, Transport
+from odatapy.client.uri_builder import URIBuilder
+
+__all__ = [
+    "ODataClient",
+    "EdmEnabledODataClient",
+    "URIBuilder",
+    "FilterFactory",
+    "and_",
+    "or_",
+    "not_",
+    "Transport",
+    "HandlerTransport",
+    "ClientResponse",
+    "ODataClientError",
+]

odatapy/client/client.py

@@ -0,0 +1,295 @@
+"""The OData client (Olingo ODataClient / EdmEnabledODataClient)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from odatapy.client import serialization
+from odatapy.client.responses import ClientResponse, ODataClientError
+from odatapy.client.transport import Transport
+from odatapy.client.uri_builder import URIBuilder
+from odatapy.data import Entity, EntityCollection
+
+_JSON = "application/json"
+_DEFAULT_HEADERS = {
+    "Accept": _JSON,
+    "OData-Version": "4.01",
+    "OData-MaxVersion": "4.01",
+}
+
+
+class ODataClient:
+    """A blocking OData v4 client.
+
+    ``transport`` decides how requests are sent (httpx over the network, or an
+    in-process :class:`~odatapy.client.transport.HandlerTransport`).
+    """
+
+    def __init__(self, service_root: str, transport: Transport) -> None:
+        self.service_root = service_root.rstrip("/")
+        self.transport = transport
+
+    # --- URI building ----------------------------------------------------
+    def uri(self) -> URIBuilder:
+        return URIBuilder(self.service_root)
+
+    def entity_set_uri(self, name: str) -> URIBuilder:
+        return self.uri().append_entity_set_segment(name)
+
+    def entity_uri(self, name: str, key: Any) -> URIBuilder:
+        return self.uri().append_entity_set_segment(name).append_key_segment(key)
+
+    # --- retrieve --------------------------------------------------------
+    def get_entity_set(
+        self, uri: str | URIBuilder, accept: str | None = None
+    ) -> EntityCollection:
+        response = self._request("GET", _url(uri), accept=accept)
+        _raise_for_status(response)
+        return serialization.read_entity_collection(response.content)
+
+    def get_entity(self, uri: str | URIBuilder, accept: str | None = None) -> Entity:
+        response = self._request("GET", _url(uri), accept=accept)
+        _raise_for_status(response)
+        entity = serialization.read_entity(response.content)
+        if not entity.etag:
+            entity.etag = response.get_header("ETag")
+        return entity
+
+    def get_property_value(self, uri: str | URIBuilder) -> Any:
+        """Read a primitive/complex property.
+
+        Handles both the JSON ``{"value": ...}`` envelope and raw ``.../$value``
+        responses (returned as text, or ``None`` for 204 No Content).
+        """
+        response = self._request("GET", _url(uri))
+        _raise_for_status(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        content_type = (response.get_header("Content-Type") or "").lower()
+        if "json" in content_type or "xml" in content_type:
+            return serialization.read_property(response.content)
+        if content_type.startswith("text/") or _url(uri).rstrip("/").endswith("$value"):
+            return response.text()
+        return serialization.read_property(response.content)
+
+    def get_service_document(self) -> dict[str, Any]:
+        response = self._request("GET", self.service_root + "/")
+        _raise_for_status(response)
+        return serialization.read_json(response.content)
+
+    def get_count(self, entity_set_uri: str | URIBuilder) -> int:
+        """``GET .../$count`` as an integer."""
+        url = _url(entity_set_uri).rstrip("/")
+        if not url.endswith("$count"):
+            url += "/$count"
+        response = self._request("GET", url, accept="text/plain")
+        _raise_for_status(response)
+        return int(response.text().strip())
+
+    def get_raw(self, uri: str | URIBuilder) -> ClientResponse:
+        return self._request("GET", _url(uri))
+
+    def get_metadata_document(self) -> str:
+        response = self._request(
+            "GET", self.service_root + "/$metadata", accept="application/xml"
+        )
+        _raise_for_status(response)
+        return response.text()
+
+    # --- create / update / delete ---------------------------------------
+    def create_entity(self, entity_set: str, entity: Entity | dict[str, Any]) -> Entity:
+        url = self.entity_set_uri(entity_set).build()
+        body = serialization.write_entity(entity)
+        response = self._request("POST", url, body=body, content_type=_JSON)
+        _raise_for_status(response, expected=(200, 201, 204))
+        if response.content:
+            return serialization.read_entity(response.content)
+        result = entity if isinstance(entity, Entity) else _dict_to_entity(entity)
+        location = response.get_header("Location")
+        if location:
+            result.id = location
+        return result
+
+    def update_entity(
+        self,
+        uri: str | URIBuilder,
+        entity: Entity | dict[str, Any],
+        method: str = "PATCH",
+        etag: str | None = None,
+    ) -> ClientResponse:
+        # Olingo's UpdateType.REPLACE is a PUT on the wire.
+        http_method = method.upper()
+        if http_method == "REPLACE":
+            http_method = "PUT"
+        if http_method not in ("PATCH", "PUT"):
+            raise ValueError("update_entity method must be 'PATCH', 'PUT' or 'REPLACE'.")
+        body = serialization.write_entity(entity)
+        headers = {}
+        if etag:
+            headers["If-Match"] = etag
+        response = self._request(
+            http_method, _url(uri), body=body, content_type=_JSON, extra=headers
+        )
+        _raise_for_status(response, expected=(200, 204))
+        return response
+
+    def update_property(
+        self,
+        uri: str | URIBuilder,
+        value: Any,
+        etag: str | None = None,
+    ) -> ClientResponse:
+        """PUT a single primitive/complex property (``{"value": ...}`` payload)."""
+        body = serialization.write_property(value)
+        headers = {"If-Match": etag} if etag else {}
+        response = self._request("PUT", _url(uri), body=body, content_type=_JSON, extra=headers)
+        _raise_for_status(response, expected=(200, 204))
+        return response
+
+    def delete_entity(self, uri: str | URIBuilder, etag: str | None = None) -> ClientResponse:
+        headers = {"If-Match": etag} if etag else {}
+        response = self._request("DELETE", _url(uri), extra=headers)
+        _raise_for_status(response, expected=(200, 204))
+        return response
+
+    # --- async protocol ---------------------------------------------------
+    def execute_async(
+        self,
+        method: str,
+        uri: str | URIBuilder,
+        body: bytes | None = None,
+        content_type: str | None = None,
+    ) -> "AsyncOperation":
+        """Send a request with ``Prefer: respond-async``.
+
+        Returns an :class:`AsyncOperation`; if the server answered 202 the
+        operation polls the status-monitor URL, otherwise the final response is
+        available immediately.
+        """
+        response = self._request(
+            method, _url(uri), body=body, content_type=content_type,
+            extra={"Prefer": "respond-async"},
+        )
+        operation = AsyncOperation(self)
+        if response.status_code == 202 and response.get_header("Location"):
+            operation.monitor_url = response.get_header("Location")
+        else:
+            operation._result = response
+        return operation
+
+    # --- operations ------------------------------------------------------
+    def invoke_function(self, uri: str | URIBuilder) -> ClientResponse:
+        return self._request("GET", _url(uri))
+
+    def invoke_action(
+        self, uri: str | URIBuilder, parameters: dict[str, Any] | None = None
+    ) -> ClientResponse:
+        body = serialization.write_parameters(parameters or {})
+        return self._request("POST", _url(uri), body=body, content_type=_JSON)
+
+    # --- internals -------------------------------------------------------
+    def _request(
+        self,
+        method: str,
+        url: str,
+        body: bytes | None = None,
+        content_type: str | None = None,
+        accept: str | None = None,
+        extra: dict[str, str] | None = None,
+    ) -> ClientResponse:
+        headers = dict(_DEFAULT_HEADERS)
+        if accept:
+            headers["Accept"] = accept
+        if content_type:
+            headers["Content-Type"] = content_type
+        if extra:
+            headers.update(extra)
+        return self.transport.send(method, url, headers, body or b"")
+
+
+class EdmEnabledODataClient(ODataClient):
+    """A client that fetches and caches the service ``$metadata`` as an :class:`Edm`."""
+
+    def __init__(self, service_root: str, transport: Transport) -> None:
+        super().__init__(service_root, transport)
+        self._edm = None
+        self._metadata_etag: str | None = None
+
+    def get_edm(self, refresh: bool = False):
+        from odatapy.edm.model import Edm
+        from odatapy.edm.xml_io import XmlEdmProvider
+
+        if self._edm is not None and not refresh:
+            return self._edm
+        response = self._request(
+            "GET", self.service_root + "/$metadata", accept="application/xml"
+        )
+        _raise_for_status(response)
+        self._metadata_etag = response.get_header("ETag")
+        self._edm = Edm.from_provider(XmlEdmProvider(response.content))
+        return self._edm
+
+    @property
+    def cached_edm(self):
+        return self._edm
+
+
+class AsyncOperation:
+    """Tracks an OData async request (202 Accepted + status monitor)."""
+
+    def __init__(self, client: "ODataClient") -> None:
+        self._client = client
+        self.monitor_url: str | None = None
+        self._result: ClientResponse | None = None
+
+    @property
+    def is_done(self) -> bool:
+        return self._result is not None
+
+    def poll(self) -> ClientResponse | None:
+        """One poll of the monitor URL; returns the final response or None if pending."""
+        if self._result is not None:
+            return self._result
+        if not self.monitor_url:
+            return None
+        response = self._client._request("GET", self.monitor_url)
+        if response.status_code == 202:
+            return None
+        self._result = response
+        return response
+
+    def result(self, retries: int = 60, interval: float = 0.5) -> ClientResponse:
+        """Poll until the result is available."""
+        import time
+
+        for _ in range(retries):
+            response = self.poll()
+            if response is not None:
+                return response
+            time.sleep(interval)
+        raise TimeoutError("The asynchronous operation did not complete in time.")
+
+    def cancel(self) -> None:
+        if self.monitor_url and self._result is None:
+            self._client._request("DELETE", self.monitor_url)
+
+
+# ---------------------------------------------------------------------------
+def _url(uri: str | URIBuilder) -> str:
+    return uri.build() if isinstance(uri, URIBuilder) else uri
+
+
+def _raise_for_status(response: ClientResponse, expected: tuple[int, ...] | None = None) -> None:
+    if expected is not None:
+        if response.status_code not in expected:
+            raise ODataClientError(response)
+        return
+    if not response.is_success:
+        raise ODataClientError(response)
+
+
+def _dict_to_entity(data: dict[str, Any]) -> Entity:
+    entity = Entity()
+    for key, value in data.items():
+        entity.set_property(key, value)
+    return entity

odatapy/client/filters.py

@@ -0,0 +1,118 @@
+"""Programmatic ``$filter`` builder (Olingo FilterFactory).
+
+A small fluent DSL that produces OData filter strings::
+
+    from odatapy.client.filters import Field, and_
+    and_(Field("Price").gt(10), Field("Name").startswith("A"))
+    # -> "(Price gt 10) and (startswith(Name,'A'))"
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import uuid
+from decimal import Decimal
+from typing import Any
+
+
+def literal(value: Any) -> str:
+    """Render a Python value as an OData literal."""
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float, Decimal)):
+        return str(value)
+    if isinstance(value, uuid.UUID):
+        return str(value)
+    if isinstance(value, _dt.datetime):
+        return value.isoformat()
+    if isinstance(value, _dt.date):
+        return value.isoformat()
+    if isinstance(value, _dt.time):
+        return value.isoformat()
+    if isinstance(value, Filter):
+        return value.text
+    text = str(value).replace("'", "''")
+    return f"'{text}'"
+
+
+class Filter:
+    """A rendered filter fragment."""
+
+    def __init__(self, text: str) -> None:
+        self.text = text
+
+    def __str__(self) -> str:
+        return self.text
+
+    def __and__(self, other: "Filter") -> "Filter":
+        return and_(self, other)
+
+    def __or__(self, other: "Filter") -> "Filter":
+        return or_(self, other)
+
+    def __invert__(self) -> "Filter":
+        return not_(self)
+
+
+class Field:
+    """A property reference in a filter expression."""
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+
+    def _binary(self, op: str, value: Any) -> Filter:
+        return Filter(f"{self.path} {op} {literal(value)}")
+
+    def eq(self, value: Any) -> Filter:
+        return self._binary("eq", value)
+
+    def ne(self, value: Any) -> Filter:
+        return self._binary("ne", value)
+
+    def gt(self, value: Any) -> Filter:
+        return self._binary("gt", value)
+
+    def ge(self, value: Any) -> Filter:
+        return self._binary("ge", value)
+
+    def lt(self, value: Any) -> Filter:
+        return self._binary("lt", value)
+
+    def le(self, value: Any) -> Filter:
+        return self._binary("le", value)
+
+    def contains(self, value: Any) -> Filter:
+        return Filter(f"contains({self.path},{literal(value)})")
+
+    def startswith(self, value: Any) -> Filter:
+        return Filter(f"startswith({self.path},{literal(value)})")
+
+    def endswith(self, value: Any) -> Filter:
+        return Filter(f"endswith({self.path},{literal(value)})")
+
+
+def and_(*filters: Filter) -> Filter:
+    return Filter(" and ".join(f"({f.text})" for f in filters))
+
+
+def or_(*filters: Filter) -> Filter:
+    return Filter(" or ".join(f"({f.text})" for f in filters))
+
+
+def not_(inner: Filter) -> Filter:
+    return Filter(f"not ({inner.text})")
+
+
+class FilterFactory:
+    """Convenience factory mirroring Olingo's FilterFactory."""
+
+    @staticmethod
+    def field(path: str) -> Field:
+        return Field(path)
+
+    and_ = staticmethod(and_)
+    or_ = staticmethod(or_)
+    not_ = staticmethod(not_)
+    literal = staticmethod(literal)

odatapy/client/responses.py

@@ -0,0 +1,99 @@
+"""Client response wrappers."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ClientResponse:
+    """A raw HTTP response returned by a :class:`Transport`."""
+
+    status_code: int
+    headers: dict[str, str] = field(default_factory=dict)
+    content: bytes = b""
+
+    def get_header(self, name: str) -> str | None:
+        for key, value in self.headers.items():
+            if key.lower() == name.lower():
+                return value
+        return None
+
+    def text(self, encoding: str = "utf-8") -> str:
+        return self.content.decode(encoding)
+
+    @property
+    def is_success(self) -> bool:
+        return 200 <= self.status_code < 300
+
+
+class ODataClientError(Exception):
+    """Raised when the server returns a non-2xx response.
+
+    ``error_code`` / ``error_message`` / ``error_target`` / ``error_details`` are
+    populated from an OData JSON or XML error body when one is present.
+    """
+
+    def __init__(self, response: ClientResponse, message: str | None = None) -> None:
+        self.response = response
+        self.status_code = response.status_code
+        self.error_code: str | None = None
+        self.error_target: str | None = None
+        self.error_details: list[dict[str, Any]] = []
+        parsed = self._extract(response)
+        self.error_message = message or parsed
+        super().__init__(f"HTTP {response.status_code}: {self.error_message}")
+
+    def _extract(self, response: ClientResponse) -> str:
+        content = response.content or b""
+        if not content:
+            return ""
+        try:
+            text = content.decode("utf-8")
+        except UnicodeDecodeError:
+            return content.decode("utf-8", "replace")
+        stripped = text.lstrip()
+        if stripped.startswith("<"):
+            return self._extract_xml(stripped) or text
+        try:
+            body = json.loads(text)
+        except ValueError:
+            return text
+        error = body.get("error") if isinstance(body, dict) else None
+        if not isinstance(error, dict):
+            return text
+        code = error.get("code")
+        self.error_code = str(code) if code is not None else None
+        target = error.get("target")
+        self.error_target = str(target) if target is not None else None
+        details = error.get("details")
+        if isinstance(details, list):
+            self.error_details = [d for d in details if isinstance(d, dict)]
+        msg = error.get("message")
+        if isinstance(msg, dict):  # OData 4.0 "message": {"lang": ..., "value": ...}
+            msg = msg.get("value")
+        return str(msg) if msg is not None else text
+
+    def _extract_xml(self, text: str) -> str | None:
+        from xml.etree import ElementTree as ET
+
+        try:
+            root = ET.fromstring(text)
+        except ET.ParseError:
+            return None
+        message = None
+        for el in root.iter():
+            local = el.tag.rsplit("}", 1)[-1]
+            if local == "code" and self.error_code is None:
+                self.error_code = (el.text or "").strip() or None
+            elif local == "message" and message is None:
+                message = (el.text or "").strip()
+            elif local == "target" and self.error_target is None:
+                self.error_target = (el.text or "").strip() or None
+        return message
+
+
+class ODataServerError(ODataClientError):
+    """Raised for 5xx responses (subclass of :class:`ODataClientError`)."""