shoply 0.1.0__py3-none-any.whl

shoply/__init__.py

@@ -0,0 +1,20 @@
+"""Shoply's API from your own server: every route as a method, safe retries, pages, and checking
+webhooks. Docs: https://docs.shoply.gg/api-reference/python
+
+    import shoply
+
+    client = shoply.Client()  # SHOPLY_API_KEY from the environment
+    order = client.orders.show("8f2c...")
+"""
+
+from . import _webhooks as webhooks
+from ._client import Client
+from ._customer import Customer
+from ._errors import ShoplyError
+from ._files import File
+from ._generated.routes import EVENTS
+from ._generated.types import WebhookEvent, WebhookEventName
+from ._page import Page
+from ._version import VERSION
+
+__all__ = ["Client", "Customer", "ShoplyError", "File", "Page", "webhooks", "WebhookEvent", "WebhookEventName", "EVENTS", "VERSION"]

shoply/_calls.py

@@ -0,0 +1,42 @@
+"""What a call of a route is made of: its address, and where its fields go."""
+
+import urllib.parse
+from typing import Any, Dict, List, Optional, Tuple
+
+from ._generated.routes import ROUTES
+
+
+def prepare(id: str, path: List[str], fields: Dict[str, Any]) -> Tuple[Dict[str, Any], Dict[str, str], Optional[Dict[str, Any]], Any, Optional[Tuple[str, Any, Optional[str], Optional[str]]]]:
+    """The route, the address's IDs by name, and the fields: as the query, the JSON body, or a file."""
+    route = ROUTES[id]
+    values: Dict[str, str] = {}
+
+    for index, name in enumerate(route["params"]):
+        value = path[index] if index < len(path) else ""
+        if not isinstance(value, str) or value == "":
+            raise ValueError(f"{id} needs {name}.")
+        values[name] = value
+
+    given = {name: value for name, value in fields.items() if value is not None}
+    query: Optional[Dict[str, Any]] = None
+    body: Any = None
+    form = None
+
+    if route["upload"]:
+        form = (route["upload"], given.get("file"), given.get("filename"), given.get("content_type"))
+        # What the route takes beside the file (a dispute's file says its `kind`) is in the address.
+        query = {name: value for name, value in given.items() if name in route["query"]}
+    elif route["body"]:
+        query = {name: value for name, value in given.items() if name in route["query"]}
+        body = {name: value for name, value in given.items() if name not in route["query"]}
+    else:
+        query = given
+
+    return route, values, query, body, form
+
+
+def fill(template: str, values: Dict[str, str]) -> str:
+    """The route's address with its IDs in it, each escaped."""
+    for name, value in values.items():
+        template = template.replace("{" + name + "}", urllib.parse.quote(value, safe=""))
+    return template

shoply/_client.py

@@ -0,0 +1,114 @@
+import os
+from typing import Any, Dict, List, Optional, Union
+
+from ._calls import fill, prepare
+from ._errors import ShoplyError
+from ._files import File
+from ._generated.resources import ClientResources
+from ._page import Page
+from ._transport import Transport
+
+
+class Client(ClientResources):
+    """Shoply's API from your own server, with a store's secret API key. Every route of the API
+    reference is a method named by its id: `orders.show` is `client.orders.show(order_id)`.
+
+        client = shoply.Client(api_key=os.environ["SHOPLY_API_KEY"])
+        order = client.orders.show("8f2c...")
+
+    A call takes the IDs in the route's address, in order, then its fields as keyword
+    arguments, then options (`idempotency_key`, `timeout`, `max_retries`, `headers`). It answers
+    the route's `data`, as dicts; a list that is paged answers a Page, and a file a File.
+
+    Docs: https://docs.shoply.gg/api-reference/python
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        store_id: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+    ) -> None:
+        """
+        api_key:     `shoply_sk_...`. Left out, SHOPLY_API_KEY from the environment.
+        store_id:    the store's ID. Left out, it is asked of the key the first time it is needed.
+        timeout:     how long one try waits for an answer, in seconds. 60.
+        max_retries: how many more tries a request that is safe to repeat is given. 2.
+        """
+        key = api_key if api_key is not None else os.environ.get("SHOPLY_API_KEY")
+
+        if not isinstance(key, str) or not key.startswith("shoply_sk_"):
+            raise ShoplyError("Pass the store's secret API key as `api_key` (shoply_sk_...), or set SHOPLY_API_KEY.", code="api_key_required")
+
+        self._store_id = store_id
+        self._transport = Transport(base_url, timeout, max_retries, lambda: key)
+        self._resources()
+
+    def store_id(self) -> str:
+        """The store the key belongs to, asked once and remembered."""
+        if self._store_id is None:
+            answer = self._transport.send("GET", "/key")
+            assert isinstance(answer, dict)
+            self._store_id = str(answer["data"]["store"]["id"])
+        return self._store_id
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Dict[str, Any]] = None,
+        body: Any = None,
+        idempotency_key: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """Any route, by its method and its address after /v1, for one newer than this package:
+        `{storeId}` in the path is filled in. Answers the whole envelope: `data`, and `meta`,
+        `pages` and `total` where the route has them."""
+        method = method.upper()
+        if "{storeId}" in path:
+            path = fill(path, {"storeId": self.store_id()})
+        answer = self._transport.send(
+            method, path, query=query, body=body, idempotent=method != "GET",
+            options={"idempotency_key": idempotency_key, "timeout": timeout, "max_retries": max_retries, "headers": headers},
+        )
+        assert isinstance(answer, dict)
+        return answer
+
+    def _call(self, id: str, path: List[str], fields: Dict[str, Any], options: Dict[str, Any]) -> Any:
+        route, values, query, body, form = prepare(id, path, fields)
+
+        def fetch(page: int) -> Union[Dict[str, Any], File]:
+            filled = dict(values)
+            if "{storeId}" in route["path"]:
+                filled["storeId"] = self.store_id()
+            asked = dict(query or {}, page=page) if route["paged"] else query
+            return self._transport.send(
+                route["method"], fill(route["path"], filled), query=asked, body=body, form=form,
+                idempotent=route["idempotent"], file=route["file"], options=options,
+            )
+
+        if route["paged"]:
+            given = fields.get("page")
+            return _page(fetch, given if isinstance(given, int) and given > 0 else 1)
+
+        answer = fetch(1)
+        return answer if isinstance(answer, File) else answer.get("data")
+
+
+def _page(fetch: Any, number: int) -> Page[Any]:
+    answer = fetch(number)
+    data = answer.get("data")
+    return Page(
+        list(data) if isinstance(data, list) else [],
+        number,
+        int(answer["pages"]) if isinstance(answer.get("pages"), int) else None,
+        int(answer["total"]) if isinstance(answer.get("total"), int) else None,
+        answer.get("meta") if isinstance(answer.get("meta"), dict) else None,
+        lambda next: _page(fetch, next),
+    )

shoply/_customer.py

@@ -0,0 +1,61 @@
+from typing import Any, Dict, List, Optional
+
+from ._calls import fill, prepare
+from ._errors import ShoplyError
+from ._generated.resources import CustomerResources
+from ._transport import Transport
+
+
+class Customer(CustomerResources):
+    """The Customer API: a buyer signed in on your own site or app with a code emailed to them,
+    reading their own orders, keys, subscriptions and affiliate page. It holds the buyer's token
+    and no key.
+
+        buyer = shoply.Customer(store_id="YOUR_STORE_ID")
+        buyer.login(email=email)
+        buyer.verify(email=email, code=code)  # keeps the token
+        me = buyer.show()
+    """
+
+    def __init__(
+        self,
+        store_id: str,
+        *,
+        token: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+    ) -> None:
+        """
+        store_id: the store's ID, from Settings, General. It is not a secret.
+        token:    a token from an earlier sign-in (`shoply_ct_...`), if you kept one.
+        """
+        if not isinstance(store_id, str) or store_id == "":
+            raise ShoplyError("Pass the store's ID as `store_id`. It is in Settings, General, in the store's dashboard.", code="store_id_required")
+
+        self.store_id = store_id
+        self.token = token
+        self._transport = Transport(base_url, timeout, max_retries, lambda: self.token)
+        self._resources()
+
+    def _call(self, id: str, path: List[str], fields: Dict[str, Any], options: Dict[str, Any]) -> Any:
+        route, values, query, body, _ = prepare(id, path, fields)
+
+        if route["signed_in"] and not self.token:
+            raise ShoplyError("Sign the buyer in first: login, then verify with the code they were emailed.", code="customer_token_required")
+
+        answer = self._transport.send(
+            route["method"], fill(route["path"], dict(values, storeId=self.store_id)),
+            query=query, body=body, idempotent=False, options=options,
+        )
+        assert isinstance(answer, dict)
+        data = answer.get("data")
+
+        # Signing in hands out the token; signing out ends it.
+        if id == "customer.verify" and isinstance(data, dict) and isinstance(data.get("token"), str):
+            self.token = data["token"]
+
+        if id in ("customer.logout", "customer.logoutEverywhere"):
+            self.token = None
+
+        return data

shoply/_errors.py

@@ -0,0 +1,32 @@
+from typing import Any, Dict, Optional
+
+
+class ShoplyError(Exception):
+    """A request Shoply refused, or one that never got an answer.
+
+    `status` is the HTTP status (0 when nothing answered), `code` the word that does not change
+    (`not_found`, `missing_scope`, `validation_failed`, `rate_limited`... and `connection_error`
+    or `timeout` when nothing answered), `errors` what is wrong with each field for
+    `validation_failed`, `request_id` what to quote to Shoply about it, `retry_after` the seconds
+    to wait when told to slow down, and `body` the whole answer.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        code: Optional[str] = None,
+        errors: Optional[Dict[str, str]] = None,
+        request_id: Optional[str] = None,
+        retry_after: Optional[int] = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.errors = errors
+        self.request_id = request_id
+        self.retry_after = retry_after
+        self.body = body

shoply/_files.py

@@ -0,0 +1,26 @@
+import os
+from typing import Dict, Optional, Union
+
+
+class File:
+    """A route's answer that is a file, a CSV or a PDF, as it came: `body` its bytes, `headers` by
+    lowercase name."""
+
+    def __init__(self, body: bytes, headers: Dict[str, str]) -> None:
+        self.body = body
+        self.headers = headers
+
+    @property
+    def content_type(self) -> Optional[str]:
+        """Its type, "text/csv"."""
+        return self.headers.get("content-type")
+
+    def text(self, encoding: str = "utf-8-sig") -> str:
+        """Its body as text. A CSV from Shoply starts with a byte order mark, for spreadsheets,
+        which this leaves out."""
+        return self.body.decode(encoding)
+
+    def save(self, path: Union[str, "os.PathLike[str]"]) -> None:
+        """Written to a file."""
+        with open(path, "wb") as handle:
+            handle.write(self.body)

shoply/_generated/__init__.py

@@ -0,0 +1 @@
+# Written by scripts/generate.py from the API reference. Do not edit by hand.