metafold package

Submodules

Module contents

class metafold.MetafoldClient(access_token: str | None = None, project_id: str | None = None, client_id: str | None = None, client_secret: str | None = None, auth_domain: str = 'metafold3d.us.auth0.com', base_url: str = 'https://api.metafold3d.com/')

Bases: Client

Metafold REST API client.

projects

Sub-client for projects endpoint.

Type:: metafold.projects.ProjectsEndpoint

assets

Sub-client for assets endpoint.

Type:: metafold.assets.AssetsEndpoint

jobs

Sub-client for jobs endpoint.

Type:: metafold.jobs.JobsEndpoint

metafold.projects module

class metafold.projects.Access(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Project access scope.

PRIVATE: Project is private to owner.

PUBLIC: Project may be accessed by unauthenticated users.

Bases: object

Project resource.

id

Project ID.

Type:: str

user

Project user ID.

Type:: str

name

Project name.

Type:: str

access

Project access.

Type:: metafold.projects.Access

created

Project creation datetime.

Type:: datetime.datetime

modified

Project last modified datetime.

Type:: datetime.datetime

thumbnail

URL to project thumbnail.

Type:: str | None

project

Arbitrary project data.

Type:: dict[str, Any] | None

graph

Project graph data.

Type:: dict[str, Any] | None

class metafold.projects.ProjectType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Project type.

DIGITAL_TEST_BENCH_EXPERIMENT: digital test bench experiment.

UNSPECIFIED: unspecified legacy project.

class metafold.projects.ProjectsEndpoint(client: Client)

Bases: object

Metafold projects endpoint.

create(name: str, access: Access | str = Access.PRIVATE, type: ProjectType | str = ProjectType.UNSPECIFIED, data: dict[str, Any] | None = None) → Project

Create a project.

Parameters:

name – Project name.
access – Project access. By default projects are private.
data – Optional project data. This parameter accepts arbitrary JSON-serializable data. Helpful for tracking application state.

Returns:

Project resource.

delete(id: str) → None

Delete an project.

Parameters:: id – Override ID of project to update. Defaults to client project ID.

duplicate(id: str, name: str, access: Access | str = Access.PRIVATE) → Project

Duplicate a project.

Parameters:

id – Project to duplicate.
name – New project name.
access – New project access. By default projects are private.

Returns:

Project resource.

get(id: str | None = None) → Project

Get an project.

Parameters:: id – Override ID of project to get. Defaults to client project ID.
Returns:: Project resource.

list(sort: str | None = None, q: str | None = None) → list[Project]

List projects.

Parameters:

sort – Sort string. For details on syntax see the Metafold API docs. Supported sorting fields are: “id”, “user”, “name”, “created”, and “modified”.
q – Query string. For details on syntax see the Metafold API docs. Supported search fields are: “id”, “user”, and “name”.

Returns:

List of project resources.

Update a project.

Parameters:

id – Override ID of project to update. Defaults to client project ID.
name – Optional project name.
access – Optional project access.
data – Optional project data. This parameter accepts arbitrary JSON-serializable data. Helpful for tracking application state.
graph – Optional shape JSON.

Returns:

Updated project resource.

metafold.assets module

class metafold.assets.Asset(*, id: str, filename: str, size: int, checksum: str, created: str | datetime, modified: str | datetime, project_id: str, job_id: str | None = None)

Bases: object

Asset resource.

id

Asset ID.

Type:: str

filename

Asset filename.

Type:: str

size

File size in bytes.

Type:: int

checksum

File checksum.

Type:: str

created

Asset creation datetime.

Type:: datetime.datetime

modified

Asset last modified datetime.

Type:: datetime.datetime

project_id

Project ID.

Type:: str

job_id

Job ID.

Type:: str | None

class metafold.assets.AssetsEndpoint(client: Client)

Bases: object

Metafold assets endpoint.

create(f: str | bytes | PathLike | IO[bytes], project_id: str | None = None) → Asset

Upload an asset.

Parameters:

f – File-like object (opened in binary mode) or path to file on disk.
project_id – Asset project ID.

Returns:

Asset resource.

delete(asset_id: str, project_id: str | None = None) → None

Delete an asset.

Parameters:

asset_id – ID of asset to delete.
project_id – Asset project ID.

download(asset_id: str, f: IO[bytes], project_id: str | None = None)

Download an asset.

Parameters:

asset_id – ID of asset to download.
f – File-like object open for writing in binary mode.
project_id – Asset project ID.

download_file(asset_id: str, path: str | PathLike, project_id: str | None = None)

Download an asset.

Parameters:

asset_id – ID of asset to download.
path – Path to downloaded file.
project_id – Asset project ID.

get(asset_id: str, project_id: str | None = None) → Asset

Get an asset.

Parameters:

asset_id – ID of asset to get.
project_id – Asset project ID.

Returns:

Asset resource.

list(sort: str | None = None, q: str | None = None, project_id: str | None = None) → list[Asset]

List assets.

Parameters:

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”.
project_id – Asset project ID.

Returns:

List of asset resources.

metafold.jobs module

class metafold.jobs.IO(*, params: dict[str, Any] | None = None, assets=None)

Bases: object

Job input/output.

params

JSON-encoded parameter values.

Type:: dict[str, Any] | None

assets

Related assets.

Type:: dict[str, metafold.assets.Asset] | None

class metafold.jobs.IODict: Bases: TypedDict

class metafold.jobs.Job(*, id: str, name: str | None = None, type: str, state: str, created: str | datetime, started=None, finished=None, error: str | None = None, inputs, outputs, needs: list[str], project_id: str | None = None, workflow_id: str | None = None, assets=None, parameters: dict[str, Any], meta: dict[str, Any])

Bases: object

Job resource.

id

Job ID.

Type:: str

name

Job name.

Type:: str | None

type

Job type.

Type:: str

state

Job state. May be one of: pending, started, success, failure, or canceled.

Type:: str

created

Job creation datetime.

Type:: datetime.datetime

started

Job started datetime.

Type:: datetime.datetime | None

finished

Job finished datetime.

Type:: datetime.datetime | None

error

Error message for failed jobs.

Type:: str | None

inputs

Input assets and parameters.

Type:: metafold.jobs.IO

outputs

Output assets and parameters.

Type:: metafold.jobs.IO

needs

List of upstream job IDs in a workflow graph.

Type:: list[str]

project_id

Project ID.

Type:: str | None

workflow_id

Workflow ID.

Type:: str | None

assets

(Deprecated) List of generated asset resources.

Type:: list[metafold.assets.Asset] | None

parameters

(Deprecated) Job parameters.

Type:: dict[str, Any]

meta

(Deprecated) Additional metadata generated by the job.

Type:: dict[str, Any]

class metafold.jobs.JobsEndpoint(client: Client)

Bases: object

Metafold jobs endpoint.

delete(job_id: str, project_id: str | None = None)

Delete a job.

Parameters:

job_id – ID of job to delete.
project_id – Job project ID.

get(job_id: str, project_id: str | None = None) → Job

Get a job.

Parameters:

job_id – ID of job to get.
project_id – Job project ID.

Returns:

Job resource.

list(sort: str | None = None, q: str | None = None, project_id: str | None = None) → list[Job]

List jobs.

Parameters:

sort – Sort string. For details on syntax see the Metafold API docs. Supported sorting fields are: “id”, “name”, “created”, “started”, or “finished”.
q – Query string. For details on syntax see the Metafold API docs. Supported search fields are: “id”, “name”, “type”, and “state”.
project_id – Job project ID.

Returns:

List of job resources.

run(type: str, params: dict[str, Any], name: str | None = None, timeout: int | float = 120, project_id: str | None = None) → Job

Dispatch a new job and wait for a result.

See Metafold API docs for the full list of jobs.

Parameters:

type – Job type.
params – Job parameters.
name – Optional job name.
timeout – Time in seconds to wait for a result.
project_id – Job project ID.

Returns:

Completed job resource.

run_status(type: str, params: dict[str, Any], name: str | None = None, project_id: str | None = None) → str

Dispatch a new job and return immediately without waiting for result.

See Metafold API docs for the full list of jobs.

Parameters:

type – Job type.
params – Job parameters.
name – Optional job name.
project_id – Job project ID.

Returns:

Job status url.

update(job_id: str, name: str | None = None, project_id: str | None = None) → Job

Update a job.

Parameters:

job_id – ID of job to update.
name – New job name. The existing name remains unchanged if None.
project_id – Job project ID.

Returns:

Updated job resource.

metafold.workflows module

class metafold.workflows.Workflow(*, client: MetafoldClient, id: str, link: str | None = None, jobs: list[str] = NOTHING, state: str, created: str | datetime, started=None, finished=None, definition: str, project_id: str)

Bases: object

Workflow resource.

id

Workflow ID.

Type:: str

state

Workflow state. May be one of: pending, started, success, failure, or canceled.

Type:: str

created

Workflow creation datetime.

Type:: datetime.datetime

started

Workflow started datetime.

Type:: datetime.datetime | None

finished

Workflow finished datetime.

Type:: datetime.datetime | None

definition

Workflow definition string.

Type:: str

project_id

Project ID.

Type:: str

get_asset(path: str) → Asset | None

Retrieve an asset from the workflow by dot notation.

Parameters:: path – Path to asset in the form “job.name”, e.g. “sample-mesh.volume” searches for the asset “volume” from the “sample-mesh” job.

get_parameter(path: str) → str | None

Retrieve a parameter from the workflow by dot notation.

Parameters:: path – Path to parameter in the form “job.name”, e.g. “sample-mesh.patch_size” searches for the parameter “patch_size” from the “sample-mesh” job.

class metafold.workflows.WorkflowsEndpoint(client: Client)

Bases: object

Metafold workflows endpoint.

cancel(workflow_id: str, project_id: str | None = None) → Workflow

Cancel a running workflow.

Parameters:

workflow_id – ID of workflow to cancel.
project_id – Workflow project ID.

Returns:

Workflow resource.

delete(workflow_id: str, project_id: str | None = None)

Delete a workflow.

Parameters:

workflow_id – ID of workflow to delete.
project_id – Workflow project ID.

get(workflow_id: str, project_id: str | None = None) → Workflow

Get a workflow.

Parameters:

workflow_id – ID of workflow to get.
project_id – Workflow project ID.

Returns:

Workflow resource.

list(sort: str | None = None, q: str | None = None, project_id: str | None = None) → list[Workflow]

List jobs.

Parameters:

sort – Sort string. For details on syntax see the Metafold API docs. Supported sorting fields are: “id”, “created”, “started”, or “finished”.
q – Query string. For details on syntax see the Metafold API docs. Supported search fields are: “id” and “state”.
project_id – Workflow project ID.

Returns:

List of job resources.

run(definition: str, parameters: dict[str, str] | None = None, assets: dict[str, str] | None = None, timeout: int | float = 120, project_id: str | None = None) → Workflow

Dispatch a new workflow and wait for it to complete.

Workflow completion does not indicate success. Access the completed workflow’s state to check for success/failure.

Parameters:

definition – Workflow definition YAML.
parameters – Parameter mapping for jobs in the definition.
assets – Asset mapping for jobs in the definition.
timeout – Time in seconds to wait for a result.
project_id – Workflow project ID.

Returns:

Completed workflow resource.

run_async(definition: str, parameters: dict[str, str] | None = None, assets: dict[str, str] | None = None, project_id: str | None = None) → Workflow

Dispatch a new workflow and return immediately without waiting for result.

Parameters:

definition – Workflow definition YAML.
parameters – Parameter mapping for jobs in the definition.
assets – Asset mapping for jobs in the definition.
project_id – Workflow project ID.

Returns:

Incomplete workflow resource.

metafold.client module

class metafold.client.Client(base_url: str, access_token: str | None = None, project_id: str | None = None, auth: AuthProvider | None = None)

Bases: object

Base client.

poll(url: str, timeout: int | float = 120, every: int | float = 1) → Response

Poll the given URL in regular intervals.

Helpful for waiting on async processes given a status URL.

Parameters:

timeout – Time in seconds to wait for a result.
every – Frequency in seconds.

Returns:

HTTP response.

metafold.exceptions module

exception metafold.exceptions.PollTimeout

Bases: Exception

Raised when a dispatched job failed to complete within expected time.