metafold 0.1.0__py3-none-any.whl

metafold/__init__.py

@@ -0,0 +1,27 @@
+from metafold.client import Client
+from metafold.assets import AssetsEndpoint
+from metafold.jobs import JobsEndpoint
+
+
+class MetafoldClient(Client):
+    """Metafold REST API client.
+
+    Attributes:
+        assets: Sub-client for assets endpoint.
+        jobs: Sub-client for jobs endpoint.
+    """
+
+    def __init__(
+        self, access_token: str, project_id: str,
+        base_url: str = "https://api.metafold3d.com",
+    ) -> None:
+        """Initialize Metafold API client.
+
+        Args:
+            access_token: Metafold API secret key.
+            project_id: ID of the project to make API calls against.
+            base_url: Metafold API URL. Used for internal testing.
+        """
+        super().__init__(access_token, project_id, base_url=base_url)
+        self.assets = AssetsEndpoint(self)
+        self.jobs = JobsEndpoint(self)

metafold/api.py

@@ -0,0 +1,25 @@
+from datetime import datetime, timezone
+from typing import Any
+
+
+def asdatetime(s: str | datetime) -> datetime:
+    """Parse Metafold API datetime.
+
+    Note datetime strings returned by the Metafold API are RFC 1123 formatted,
+    times are always in GMT.
+
+    Returns:
+        UTC datetime.
+    """
+    if isinstance(s, datetime):
+        return s
+    return datetime.strptime(s, "%a, %d %b %Y %H:%M:%S %Z").replace(tzinfo=timezone.utc)
+
+
+def asdict(**kwargs: Any) -> dict[str, Any]:
+    """Convert present kwargs to dictionary."""
+    d = {}
+    for k, v in kwargs.items():
+        if v is not None:
+            d[k] = v
+    return d

metafold/assets.py

@@ -0,0 +1,130 @@
+from attrs import field, frozen
+from datetime import datetime
+from metafold.api import asdatetime, asdict
+from metafold.client import Client
+from os import PathLike
+from requests import Response
+from typing import IO, Optional
+import requests
+
+
+@frozen(kw_only=True)
+class Asset:
+    """Asset resource.
+
+    Attributes:
+        id: Asset ID.
+        filename: Asset filename.
+        size: File size in bytes.
+        checksum: File checksum.
+        created: Asset creation datetime.
+        modified: Asset last modified datetime.
+    """
+    id: str
+    filename: str
+    size: int
+    checksum: str
+    created: datetime = field(converter=asdatetime)
+    modified: datetime = field(converter=asdatetime)
+
+
+class AssetsEndpoint:
+    """Metafold assets endpoint."""
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def list(self, sort: Optional[str] = None, q: Optional[str] = None) -> list[Asset]:
+        """List assets.
+
+        Args:
+            sort: Sort string. For details on syntax see the Metafold API docs.
+                Supported sorting fields are: "id", "filename", "size", "created", or
+                "modified".
+            q: Query string. For details on syntax see the Metafold API docs.
+                Supported search fields are: "id" and "filename".
+
+        Returns:
+            List of asset resources.
+        """
+        url = f"/projects/{self._client.project_id}/assets"
+        payload = asdict(sort=sort, q=q)
+        r: Response = self._client.get(url, params=payload)
+        return [Asset(**a) for a in r.json()]
+
+    def get(self, id: str) -> Asset:
+        """Get an asset.
+
+        Args:
+            id: ID of asset to get.
+
+        Returns:
+            Asset resource.
+        """
+        url = f"/projects/{self._client.project_id}/assets/{id}"
+        r: Response = self._client.get(url)
+        return Asset(**r.json())
+
+    def download_file(self, id: str, path: str | PathLike):
+        """Download an asset.
+
+        Args:
+            id: ID of asset to download.
+            path: Path to downloaded file.
+        """
+        url = f"/projects/{self._client.project_id}/assets/{id}"
+        r: Response = self._client.get(url, params={"download": "true"})
+        r = requests.get(r.json()["link"], stream=True)
+        with open(path, "wb") as f:
+            for chunk in r.iter_content(chunk_size=65536):  # 64 KiB
+                f.write(chunk)
+
+    def create(self, f: str | bytes | PathLike | IO[bytes]) -> Asset:
+        """Upload an asset.
+
+        Args:
+            f: File-like object (opened in binary mode) or path to file on disk.
+
+        Returns:
+            Asset resource.
+        """
+        fp: IO[bytes] = _open_file(f)
+        try:
+            url = f"/projects/{self._client.project_id}/assets"
+            r: Response = self._client.post(url, files={"file": fp})
+        finally:
+            fp.close()
+        return Asset(**r.json())
+
+    def update(self, id: str, f: str | bytes | PathLike | IO[bytes]) -> Asset:
+        """Update an asset.
+
+        Args:
+            id: ID of asset to update.
+            f: File-like object (opened in binary mode) or path to file on disk.
+
+        Returns:
+            Updated asset resource.
+        """
+        fp: IO[bytes] = _open_file(f)
+        try:
+            url = f"/projects/{self._client.project_id}/assets/{id}"
+            r: Response = self._client.patch(url, files={"file": fp})
+        finally:
+            fp.close()
+        return Asset(**r.json())
+
+    def delete(self, id: str) -> None:
+        """Delete an asset.
+
+        Args:
+            id: ID of asset to delete.
+        """
+        url = f"/projects/{self._client.project_id}/assets/{id}"
+        self._client.delete(url)
+
+
+def _open_file(f: str | bytes | PathLike | IO[bytes]) -> IO[bytes]:
+    if isinstance(f, str | bytes | PathLike):
+        return open(f, "rb")
+    return f

metafold/client.py

@@ -0,0 +1,52 @@
+from requests import HTTPError, Response, Session
+from typing import Any, Callable
+from urllib.parse import urljoin
+import platform
+
+
+class Client:
+    """Base client."""
+
+    def __init__(self, access_token: str, project_id: str, base_url: str) -> None:
+        # TODO(ryan): Validate project id
+        self._project_id = project_id
+        self._base_url = base_url
+        self._session = Session()
+        self._session.headers.update({
+            "Accept": "application/json",
+            "Authorization": f"Bearer {access_token}",
+            "User-Agent": f"Python/{platform.python_version()}",
+        })
+
+    @property
+    def project_id(self) -> str:
+        return self._project_id
+
+    def _request(
+        self, request: Callable[..., Response], url: str,
+        *args: Any, **kwargs: Any,
+    ) -> Response:
+        url = urljoin(self._base_url, url)
+        r: Response = request(url, *args, **kwargs)
+        if not r.ok:
+            r: dict[str, Any] = r.json()
+            # Error responses aren't entirely consistent in the Metafold API,
+            # for now we check for a handful of possible fields.
+            reason = r.get("errors") or r.get("msg") or r.get("description")
+            raise HTTPError(f"HTTP error occurred: {reason or r.reason}")
+        return r
+
+    def get(self, url: str, *args: Any, **kwargs: Any) ->  Response:
+        return self._request(self._session.get, url, *args, **kwargs)
+
+    def post(self, url: str, *args: Any, **kwargs: Any) ->  Response:
+        return self._request(self._session.post, url, *args, **kwargs)
+
+    def put(self, url: str, *args: Any, **kwargs: Any) ->  Response:
+        return self._request(self._session.put, url, *args, **kwargs)
+
+    def patch(self, url: str, *args: Any, **kwargs: Any) ->  Response:
+        return self._request(self._session.patch, url, *args, **kwargs)
+
+    def delete(self, url: str, *args: Any, **kwargs: Any) ->  Response:
+        return self._request(self._session.delete, url, *args, **kwargs)

metafold/exceptions.py

@@ -0,0 +1,2 @@
+class PollTimeout(Exception):
+    """Raised when a dispatched job failed to complete within expected time."""

metafold/jobs.py

@@ -0,0 +1,123 @@
+from attrs import field, frozen
+from datetime import datetime
+from metafold.api import asdatetime, asdict
+from metafold.assets import Asset
+from metafold.client import Client
+from metafold.exceptions import PollTimeout
+from requests import Response
+from typing import Any, Optional
+import time
+
+
+def _assets(v: list[dict[str, Any] | Asset]) -> list[Asset]:
+    return [a if isinstance(a, Asset) else Asset(**a) for a in v]
+
+
+@frozen(kw_only=True)
+class Job:
+    """Job resource.
+
+    Attributes:
+        id: Job ID.
+        name: Job name.
+        type: Job type.
+        parameters: Job parameters.
+        created: Job creation datetime.
+        state: Job state. May be one of: pending, started, success, or failure.
+        assets: List of generated asset resources.
+        meta: Additional metadata generated by the job.
+    """
+    id: str
+    name: Optional[str] = None
+    type: str
+    parameters: dict[str, Any]
+    created: datetime = field(converter=asdatetime)
+    state: str
+    assets: list[Asset] = field(converter=_assets)
+    meta: dict[str, Any]
+
+
+class JobsEndpoint:
+    """Metafold jobs endpoint."""
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def list(self, sort: Optional[str] = None, q: Optional[str] = None) -> list[Job]:
+        """List jobs.
+
+        Args:
+            sort: Sort string. For details on syntax see the Metafold API docs.
+                Supported sorting fields are: "id", "name", or "created".
+            q: Query string. For details on syntax see the Metafold API docs.
+                Supported search fields are: "id", "name", "type", and "state".
+
+        Returns:
+            List of job resources.
+        """
+        url = f"/projects/{self._client.project_id}/jobs"
+        payload = asdict(sort=sort, q=q)
+        r: Response = self._client.get(url, params=payload)
+        return [Job(**j) for j in r.json()]
+
+    def get(self, id: str) -> Job:
+        """Get a job.
+
+        Args:
+            id: ID of job to get.
+
+        Returns:
+            Job resource.
+        """
+        url = f"/projects/{self._client.project_id}/jobs/{id}"
+        r: Response = self._client.get(url)
+        return Job(**r.json())
+
+    def run(
+        self, type: str, params: dict[str, Any],
+        name: Optional[str] = None,
+        timeout: int | float = 120,
+    ) -> Job:
+        """Dispatch a new job and wait for a result.
+
+        See Metafold API docs for the full list of jobs.
+
+        Args:
+            type: Job type.
+            params: Job parameters.
+            name: Optional job name.
+            timeout: Time in seconds to wait for a result.
+
+        Returns:
+            Completed job resource.
+        """
+        payload = asdict(type=type, parameters=params, name=name)
+        r: Response = self._client.post(f"/projects/{self._client.project_id}/jobs", json=payload)
+        r = self._poll(r.json()["link"], timeout)
+        return Job(**r.json())
+
+    def update(self, id: str, name: Optional[str] = None) -> Job:
+        """Update a job.
+
+        Args:
+            id: ID of job to update.
+            name: New job name. The existing name remains unchanged if None.
+
+        Returns:
+            Updated job resource.
+        """
+        url = f"/projects/{self._client.project_id}/jobs/{id}"
+        payload = asdict(name=name)
+        r: Response = self._client.patch(url, data=payload)
+        return Job(**r.json())
+
+    def _poll(self, url: str, timeout: int | float) -> Response:
+        t0 = time.monotonic()
+        r = self._client.get(url)
+        while r.status_code == 202:
+            elapsed = time.monotonic() - t0
+            if elapsed >= timeout:
+                raise PollTimeout("Job timed out")
+            time.sleep(1)
+            r = self._client.get(url)
+        return r

metafold-0.1.0.dist-info/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2024 Metafold 3D
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

metafold-0.1.0.dist-info/METADATA

@@ -0,0 +1,44 @@
+Metadata-Version: 2.1
+Name: metafold
+Version: 0.1.0
+Summary: Metafold SDK for Python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: attrs >=23.2
+Requires-Dist: requests >=2.31
+Requires-Dist: sphinx >=7.2
+Requires-Dist: sphinx-rtd-theme >=2.0
+Provides-Extra: test
+Requires-Dist: pytest >=7.3 ; extra == 'test'
+Requires-Dist: requests-toolbelt >=1.0 ; extra == 'test'
+
+# Metafold SDK for Python
+
+## Installation
+
+```
+pip install metafold
+```
+
+## Usage
+
+```
+from metafold import MetafoldClient
+
+access_token = "..."
+project_id = "123"
+
+metafold = MetafoldClient(access_token, project_id)
+
+assets = metafold.assets.list()
+print(assets[0].name)
+
+asset = metafold.assets.get("123")
+print(asset.name)
+```
+
+Read the [documentation][] for more info or play around with one of the
+[examples](examples).
+
+[documentation]: https://Metafold3d.github.io/metafold-python/

metafold-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+metafold/__init__.py,sha256=-xgonly8A0YEzh3uMkDA_vfRD0Ms9rgrMOkAoy-2F_A,846
+metafold/api.py,sha256=QPnsf_ntNsAN8uY_pUHB2R2AyOl5qsYhNpcBGAPmPgo,637
+metafold/assets.py,sha256=GVvdP0AaGqgyu73asDxILLy-ZuIP93yFq-B0yye1emc,3905
+metafold/client.py,sha256=0glZICHjNyVUvxdKNDaHNRwkOW81xtJsOLn1kbYt9oc,2006
+metafold/exceptions.py,sha256=dJhBgbryBhJUf20FT3eU1rjQJQ-aDEZ25g-YCn_TwQk,110
+metafold/jobs.py,sha256=mGFdA2NpQGxwTM7SV6xcPcl3cG2gyqlvAuRkCr4B7Ag,3805
+metafold-0.1.0.dist-info/LICENSE,sha256=LejZXzGwe9t0Ezk6g0bRmWUuFSI9vQSk1wJAc1NrrhE,1059
+metafold-0.1.0.dist-info/METADATA,sha256=p_ACUtmteEhITfEKZCKoYpJJSr2ZdPWbILRUNZNmjqs,911
+metafold-0.1.0.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+metafold-0.1.0.dist-info/top_level.txt,sha256=0dvwa2N6gvl2x4T9c62V4MbYD2soFedI6hm3-lWgyew,9
+metafold-0.1.0.dist-info/RECORD,,

metafold-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.42.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

metafold-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+metafold