powerfunc 0.2.0__tar.gz → 0.3.0__tar.gz

powerfunc-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+# One run per branch. Keying on the head branch (not github.ref) makes the
+# push and pull_request events for the same branch share a group, so we get a
+# single run per commit instead of two, and a new push cancels an in-progress
+# run for the same branch so live remote tests can't pile up.
+concurrency:
+  group: ci-${{ github.event.pull_request.head.ref || github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uvx pre-commit run --all-files --show-diff-on-failure
+
+  test-core:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uvx --with tox-uv tox run -e core
+
+  test-gcp:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Run GCP tests
+        env:
+          GOOGLE_CLOUD_API_KEY: ${{ secrets.GOOGLE_CLOUD_API_KEY }}
+          GCP_BUCKET: gs://powerfunc-temporary-348293
+          GCP_REGION: europe-west4
+        run: uvx --with tox-uv tox run -e gcp
+
+  test-modal:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Run Modal tests
+        env:
+          MODAL_TOKEN_ID: ${{ secrets.MODAL_TOKEN_ID }}
+          MODAL_TOKEN_SECRET: ${{ secrets.MODAL_TOKEN_SECRET }}
+        run: uvx --with tox-uv tox run -e modal

powerfunc-0.3.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: powerfunc
+Version: 0.3.0
+Summary: Make functions run however you like — CLI, pipeline, or remote compute
+Project-URL: Homepage, https://github.com/ddrakard/powerfunc
+Project-URL: Repository, https://github.com/ddrakard/powerfunc
+Project-URL: Documentation, https://github.com/ddrakard/powerfunc/blob/main/documentation/readme.md
+License-File: LICENSE.txt
+Requires-Python: >=3.9
+Requires-Dist: cloudpathlib[all]
+Requires-Dist: cloudpickle
+Requires-Dist: fsspec[adl,gcs,s3]
+Requires-Dist: jsonargparse>=4.49.0
+Requires-Dist: pydantic>=2
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: tox; extra == 'dev'
+Requires-Dist: tox-uv; extra == 'dev'
+Provides-Extra: gcp
+Requires-Dist: google-auth; extra == 'gcp'
+Requires-Dist: google-cloud-batch; extra == 'gcp'
+Requires-Dist: google-cloud-compute; extra == 'gcp'
+Requires-Dist: google-cloud-run; extra == 'gcp'
+Provides-Extra: modal
+Requires-Dist: modal; extra == 'modal'
+Description-Content-Type: text/markdown
+
+# powerfunc
+
+Add superpowers to your functions. Run them from the CLI, on cloud data, or on cloud compute.
+
+## Features
+
+- Load and save function arguments and results to file paths, local or in cloud storage.
+- Invoke functions on the command line.
+- Remote execution on cloud compute.
+- YAML configuration file support.
+- Supports [pandas](https://pandas.pydata.org/), [polars](https://pola.rs/), [PyArrow](https://pypi.org/project/pyarrow/), [Dask](https://www.dask.org/), and the Python [`csv` module](https://docs.python.org/3/library/csv.html) out of the box
+- Supports cloud providers [Google Cloud](https://cloud.google.com) and [Modal](https://modal.com/).
+- Extensible for new data types and cloud providers.
+
+## Installation
+
+```bash
+pip install powerfunc
+```
+
+With [Google Cloud](https://cloud.google.com) remote execution:
+
+```bash
+pip install 'powerfunc[gcp]'
+```
+
+With [Modal](https://modal.com/) remote execution:
+
+```bash
+pip install 'powerfunc[modal]'
+```
+
+## Example usage
+
+Decorate a normal function with `@powerfunc`:
+
+```python
+import pandas as pd
+from powerfunc import powerfunc
+
+@powerfunc
+def sum_col(df: pd.DataFrame) -> float:
+    return float(df["value"].sum())
+
+df = pd.DataFrame({"value": [1, 2, 3]})
+print(sum_col(df))
+```
+
+Then use it on files, local or in the cloud:
+
+```python
+print(sum_col("data.csv"))
+print(sum_col("https://storage.googleapis.com/powerfunc/data.csv"))
+```
+
+Add one line at the end of your file to make it runnable on the command line:
+
+```python
+from powerfunc import powerfunc
+
+...
+
+powerfunc.enable_cli()
+```
+
+```sh
+python myfile.py gs://powerfunc/data.csv
+```
+
+## Support
+
+This project is in early development. Breaking changes may happen at any time.
+
+## Documentation
+
+For complete information on using powerfunc, including executing on cloud compute, please see the [documentation](documentation/readme.md).
+
+## License
+
+Released under the [MIT](LICENSE.txt) license.

{powerfunc-0.2.0 → powerfunc-0.3.0}/README.md

@@ -21,13 +21,13 @@ pip install powerfunc
 With [Google Cloud](https://cloud.google.com) remote execution:
 
 ```bash
-pip install powerfunc[gcp]
+pip install 'powerfunc[gcp]'
 ```
 
 With [Modal](https://modal.com/) remote execution:
 
 ```bash
-pip install powerfunc[modal]
+pip install 'powerfunc[modal]'
 ```
 
 ## Example usage

{powerfunc-0.2.0 → powerfunc-0.3.0}/documentation/advanced_usage.md

@@ -12,10 +12,10 @@ Subclass `ComputeSpecification` to define reusable compute configurations:
 ```python
 from dataclasses import field
 from pydantic.dataclasses import dataclass
-from powerfunc.compute import ComputeSpecification, Provider
-from powerfunc.providers.gcp import GCPProvider
+from powerfunc.compute import ComputeSpecification, CpuCount, DockerImageUri, GpuModel, MemorySize, Provider
+from powerfunc.providers.gcp_cloud_run import GCPCloudRunProvider
 
-provider = GCPProvider(
+provider = GCPCloudRunProvider(
     project="my-project",
     region="us-central1",
     temporary_bucket_path="gs://my-bucket/tmp",
@@ -23,10 +23,10 @@ provider = GCPProvider(
 
 @dataclass
 class MyGpuSpec(ComputeSpecification):
-    cpu: float = 8.0
-    memory: int = 32768
-    image: str = "gcr.io/deeplearning-platform-release/base-cu121"
-    gpu: str = "a100"
+    cpu: CpuCount = 8.0
+    memory: MemorySize = 32768
+    image: DockerImageUri = "nvidia/cuda:12.1.0-base-ubuntu22.04"
+    gpu: GpuModel = "a100"
     provider: Provider = field(default_factory=lambda: provider)
 
 MY_GPU = MyGpuSpec()

powerfunc-0.3.0/documentation/integrations/snakemake.md

@@ -0,0 +1,44 @@
+# Snakemake
+
+powerfunc functions can be called directly from a [Snakemake](https://snakemake.readthedocs.io/)
+rule. Call `.snakemake()` inside a `run:` block and the rule's inputs, params and outputs are
+bound automatically.
+
+## Usage
+
+```python
+# functions.py
+import pandas as pd
+from powerfunc import powerfunc
+
+@powerfunc
+def sum_col(df: pd.DataFrame) -> pd.DataFrame:
+    return df.sum().to_frame().T
+```
+
+```python
+# Snakefile
+from functions import sum_col
+
+rule sum:
+    input: "data.csv"
+    output: "result.csv"
+    run:
+        sum_col.snakemake()
+```
+
+## Binding rules
+
+Inputs (`input`) and params (`params`) are bound to the function's arguments:
+
+- When **both** inputs and params are present, they must all be **named** (keyword).
+  Positional entries are only allowed when one of the two is absent.
+- Inputs are passed as paths and are read through powerfunc's
+  [converters](../readme.md#automatic-reading-and-writing-data), so a `pd.DataFrame`
+  parameter receives the loaded file. Params are passed through unchanged.
+
+Outputs (`output`) are bound as follows:
+
+- A single **unnamed** output receives the function's **return value**, written through
+  powerfunc's converters.
+- Named outputs and multiple outputs are not supported.

powerfunc-0.3.0/documentation/providers/gcp.md

@@ -0,0 +1,171 @@
+# Google Cloud Platform
+
+powerfunc supports two GCP execution backends: [Cloud Run Jobs](https://cloud.google.com/run/docs/create-jobs) and [Batch](https://cloud.google.com/batch/docs). Both use the same authentication, bucket-based data transfer, and `ComputeSpecification` model.
+
+## Contents
+
+- [Installation](#installation)
+- [Setup and configuration](#setup-and-configuration)
+- [Cloud Run](#cloud-run)
+- [Batch](#batch)
+- [Environment variables](#environment-variables)
+- [Predefined configurations](#predefined-configurations)
+- [Supported GPUs](#supported-gpus)
+- [Limitations](#limitations)
+
+## Installation
+
+Make sure to install with the `gcp` option.
+
+```sh
+pip install 'powerfunc[gcp]'
+```
+
+or
+
+```sh
+uv add 'powerfunc[gcp]'
+```
+
+## Setup
+
+You need to have a Google Cloud account with a project inside it where the remote execution can happen. You must authenticate with the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) using:
+
+```sh
+gcloud auth application-default login
+```
+
+powerfunc transfers data in and out of the compute job using a [Google Cloud Storage bucket](https://docs.cloud.google.com/storage/docs/buckets). Therefore, you need to have or create a bucket that powerfunc can use, and provide these details.
+
+### Command line usage
+
+When runnng from the command line, [module-style invocation](https://docs.python.org/3/using/cmdline.html#cmdoption-m) `python -m my.module` must be used instead of direct script execution `python myscript.py`.
+
+## Cloud Run
+
+Cloud Run Jobs is a serverless execution backend. It scales to zero, has fast cold starts for cached images, and supports GPUs.
+
+Configure in `powerfunc.yaml`:
+
+```yaml
+compute:
+  class_path: powerfunc.providers.gcp_cloud_run.GcpCloudRunCpuSmall
+  init_args:
+    timeout: 600
+    provider:
+      class_path: powerfunc.providers.gcp_cloud_run.GCPCloudRunProvider
+      init_args:
+        project: my-gcp-project
+        region: us-central1
+        temporary_bucket_path: gs://my-bucket/powerfunc-temp
+```
+
+Or directly in Python:
+
+```python
+from powerfunc.providers.gcp_cloud_run import GCPCloudRunProvider, GcpCloudRunCpuSmall
+
+provider = GCPCloudRunProvider(
+    project="my-gcp-project",
+    region="us-central1",
+    temporary_bucket_path="gs://my-bucket/",
+)
+compute = GcpCloudRunCpuSmall(timeout=600, provider=provider)
+
+result = sum_col("gs://bucket/data.csv", compute=compute)
+```
+
+Cloud Run Jobs can require some time to start, particularly for a docker image that has not been used recently.
+
+## Batch
+
+Batch provisions Compute Engine VMs. It supports GPUs, higher resource limits than Cloud Run, spot (preemptible) VMs, and explicit machine type selection.
+
+Configure in `powerfunc.yaml`:
+
+```yaml
+compute:
+  class_path: powerfunc.providers.gcp_batch.GcpBatchCpuSmall
+  init_args:
+    timeout: 600
+    provider:
+      class_path: powerfunc.providers.gcp_batch.GCPBatchProvider
+      init_args:
+        project: my-gcp-project
+        region: us-central1
+        temporary_bucket_path: gs://my-bucket/powerfunc-temp
+```
+
+Or directly in Python:
+
+```python
+from powerfunc.providers.gcp_batch import GCPBatchProvider, GcpBatchCpuSmall
+
+provider = GCPBatchProvider(
+    project="my-gcp-project",
+    region="us-central1",
+    temporary_bucket_path="gs://my-bucket/",
+    spot=True,  # optional: use spot (preemptible) VMs
+    machine_type="n1-standard-4",  # optional: Batch auto-selects if omitted
+)
+compute = GcpBatchCpuSmall(timeout=600, provider=provider)
+
+result = sum_col("gs://bucket/data.csv", compute=compute)
+```
+
+`machine_type` is optional — Batch selects a machine from the requested CPU/memory when it
+is not given. For GPUs, a compatible `machine_type` is usually required.
+
+## Environment variables
+
+Both Cloud Run and Batch support passing environment variables to the remote container via the `environment_variables` provider option:
+
+```python
+provider = GCPCloudRunProvider(
+    project="my-project",
+    region="us-central1",
+    temporary_bucket_path="gs://my-bucket/tmp",
+    environment_variables={"MY_API_KEY": "secret123"},
+)
+```
+
+Or in `powerfunc.yaml`:
+
+```yaml
+provider:
+  init_args:
+    environment_variables:
+      MY_API_KEY: secret123
+```
+
+## Supported GPUs
+
+Both Cloud Run and Batch support: `t4`, `a100`, `l4`, `v100`.
+
+## Predefined configurations
+
+| Class | Provider | CPU | Memory | Image | GPU |
+|---|---|---|---|---|---|
+| `GcpCloudRunCpuSmall` | Cloud Run | 1 vCPU | 2GB | `python:3.12-slim` | — |
+| `GcpCloudRunGpu` | Cloud Run | 4 vCPU | 16GB | `nvidia/cuda:12.1.0-base-ubuntu22.04` | L4 |
+| `GcpBatchCpuSmall` | Batch | 1 vCPU | 2GB | `python:3.12-slim` | — |
+| `GcpBatchGpu` | Batch | 4 vCPU | 16GB | `nvidia/cuda:12.1.0-base-ubuntu22.04` | L4 |
+
+All presets require a `timeout` argument (in seconds), e.g. `GcpCloudRunCpuSmall(timeout=600)` or `GcpBatchCpuSmall(timeout=600)`.
+
+## Known limitations
+
+### Codebase synchronisation
+
+A simple codebase synchronisation method is used. It is not robust to work with all codebases and scenarios. For complex setups, understanding of the underlying infrastructure technologies (such as Python packaging and [Docker](https://www.docker.com/)) will likely be needed. To enable rapid execution for complex codebases, additional setup in needed, such as preparing docker images.
+
+### Anonymous usage
+
+For public GCS buckets without credentials, configure fsspec before importing powerfunc:
+
+```python
+import fsspec
+fsspec.config.conf["gs"] = {"token": "anon"}
+```
+
+**Parquet files on `gs://` hang without credentials** for pandas and polars — their parquet readers use pyarrow's C++ GCS filesystem which has no anonymous mode and no timeout. Use `gcloud auth application-default login` to resolve this, or access parquet via HTTPS instead.

{powerfunc-0.2.0 → powerfunc-0.3.0}/documentation/providers/modal.md

@@ -14,13 +14,13 @@ This page describes how to execute powerfunc functions remotely on [Modal](https
 Make sure to install with the `modal` option.
 
 ```sh
-pip install powerfunc[modal]
+pip install 'powerfunc[modal]'
 ```
 
 or
 
 ```sh
-uv add powerfunc[modal]
+uv add 'powerfunc[modal]'
 ```
 
 You must have a Modal account. Then authenticate to Modal:
@@ -33,13 +33,13 @@ python -m modal setup
 
 ```python
 from powerfunc import powerfunc
-from powerfunc.providers.modal import MODAL_CPU_SMALL
+from powerfunc.providers.modal import ModalCpuSmall
 
 @powerfunc
 def sum_col(df: pd.DataFrame) -> float:
     return float(df["value"].sum())
 
-result = sum_col("data.csv", compute=MODAL_CPU_SMALL)
+result = sum_col("data.csv", compute=ModalCpuSmall(timeout=600))
 ```
 
 Or set a default in `powerfunc.yaml` so all calls run on Modal without passing `compute=`:
@@ -47,6 +47,8 @@ Or set a default in `powerfunc.yaml` so all calls run on Modal without passing `
 ```yaml
 compute:
   class_path: powerfunc.providers.modal.ModalCpuSmall
+  init_args:
+    timeout: 600
 ```
 
 ## Dependencies
@@ -56,7 +58,7 @@ By default the container uses Modal's `debian_slim` base image. If your function
 ```python
 from powerfunc.providers.modal import ModalProvider, ModalCpuSmall
 
-compute = ModalCpuSmall(provider=ModalProvider(pip_packages=("pandas", "pyarrow")))
+compute = ModalCpuSmall(timeout=600, provider=ModalProvider(pip_packages=("pandas", "pyarrow")))
 result = sum_col("data.csv", compute=compute)
 ```
 
@@ -65,7 +67,7 @@ To use a different base image, set `image` on the compute specification:
 ```python
 from powerfunc.providers.modal import ModalCpuSmall
 
-compute = ModalCpuSmall(image="python:3.12-slim")
+compute = ModalCpuSmall(timeout=600, image="python:3.12-slim")
 result = sum_col("data.csv", compute=compute)
 ```
 
@@ -75,6 +77,7 @@ Or in `powerfunc.yaml`:
 compute:
   class_path: powerfunc.providers.modal.ModalCpuSmall
   init_args:
+    timeout: 600
     image: "python:3.12-slim"
     provider:
       class_path: powerfunc.providers.modal.ModalProvider
@@ -89,4 +92,4 @@ compute:
 | `ModalCpuSmall` | 1 vCPU | 1GB | — |
 | `ModalGpuA100` | 8 vCPU | 80GB | A100 |
 
-Convenience instances `powerfunc.providers.modal.MODAL_CPU_SMALL` and `powerfunc.providers.modal.MODAL_GPU_A100` are available for direct use.
+All presets require a `timeout` argument (in seconds), e.g. `ModalCpuSmall(timeout=600)`.

{powerfunc-0.2.0 → powerfunc-0.3.0}/documentation/readme.md

@@ -10,6 +10,7 @@
 - [Cloud providers and remote execution](#cloud-providers-and-remote-execution)
 - [Configuration](#configuration)
 - [Supported formats](#supported-formats)
+- [Integrations](#integrations)
 - [Known limitations](#known-limitations)
 - [Advanced usage](#advanced-usage)
 
@@ -24,13 +25,13 @@ pip install powerfunc
 For GCP remote execution:
 
 ```sh
-pip install powerfunc[gcp]
+pip install 'powerfunc[gcp]'
 ```
 
 For Modal remote execution:
 
 ```sh
-pip install powerfunc[modal]
+pip install 'powerfunc[modal]'
 ```
 
 Or using [uv](https://github.com/astral-sh/uv):
@@ -40,11 +41,11 @@ uv add powerfunc
 ```
 
 ```sh
-uv add powerfunc[gcp]
+uv add 'powerfunc[gcp]'
 ```
 
 ```sh
-uv add powerfunc[modal]
+uv add 'powerfunc[modal]'
 ```
 
 ## Basic usage
@@ -151,10 +152,11 @@ For example:
 
 ```yaml
 compute:
-  class_path: powerfunc.providers.gcp.GcpCpuSmall
+  class_path: powerfunc.providers.gcp_cloud_run.GcpCloudRunCpuSmall
   init_args:
+    timeout: 600
     provider:
-      class_path: powerfunc.providers.gcp.GCPProvider
+      class_path: powerfunc.providers.gcp_cloud_run.GCPCloudRunProvider
       init_args:
         project: my-gcp-project
         region: us-central1
@@ -192,6 +194,12 @@ python my_script.py sum_col data.csv --config my_config.yaml
 | `dask.dataframe.DataFrame` | `.csv`, `.parquet` |
 | `csv.reader` | `.csv` |
 
+## Integrations
+
+powerfunc functions can be driven by external workflow tools:
+
+- [Snakemake](integrations/snakemake.md) — bind a rule's inputs, params and outputs with `function.snakemake()`.
+
 ## Known limitations
 
 ### Anonymous `gs://` access

{powerfunc-0.2.0 → powerfunc-0.3.0}/pyproject.toml

@@ -4,12 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "powerfunc"
-version = "0.2.0"
+version = "0.3.0"
 description = "Make functions run however you like — CLI, pipeline, or remote compute"
+readme = "README.md"
 requires-python = ">=3.9"
 dependencies = [
     "pydantic>=2",
     "cloudpathlib[all]",
+    "fsspec[gcs,s3,adl]",
     "jsonargparse>=4.49.0",
     "cloudpickle",
 ]
@@ -17,25 +19,25 @@ dependencies = [
 [project.optional-dependencies]
 gcp = [
     "google-cloud-run",
+    "google-cloud-batch",
+    "google-cloud-compute",
     "google-auth",
 ]
 modal = [
     "modal",
 ]
 dev = [
-    "pytest",
-    "pandas",
-    "polars",
-    "pyarrow",
-    "openpyxl",
-    "xlsxwriter",
-    "fastexcel",
-    "dask[dataframe]",
-    "gcsfs",
+    "tox",
+    "tox-uv",
     "ruff",
     "pre-commit",
 ]
 
+[project.urls]
+Homepage = "https://github.com/ddrakard/powerfunc"
+Repository = "https://github.com/ddrakard/powerfunc"
+Documentation = "https://github.com/ddrakard/powerfunc/blob/main/documentation/readme.md"
+
 [tool.ruff]
 target-version = "py39"
 line-length = 100
@@ -43,6 +45,10 @@ line-length = 100
 [tool.ruff.lint]
 select = ["E", "F", "W", "I", "B", "C4", "UP", "RUF"]
 
+[tool.pytest.ini_options]
+pythonpath = ["tests"]
+addopts = "--import-mode=importlib"
+
 [dependency-groups]
 dev = [
     "cloudpickle>=3.1.2",

{powerfunc-0.2.0 → powerfunc-0.3.0}/src/powerfunc/compute.py

@@ -1,5 +1,5 @@
 import dataclasses
-from typing import Annotated, Any, Callable, Optional
+from typing import Annotated, Any, Callable, Optional, TypeAlias
 
 from pydantic import Field, GetCoreSchemaHandler
 from pydantic.dataclasses import dataclass as pydantic_dataclass
@@ -7,6 +7,12 @@ from pydantic_core import core_schema
 
 from powerfunc.command_line import ExpectedException
 
+Timeout: TypeAlias = Annotated[float, Field(gt=0, description="Maximum job duration in seconds")]
+CpuCount: TypeAlias = Annotated[float, Field(gt=0, description="Number of vCPUs")]
+MemorySize: TypeAlias = Annotated[int, Field(gt=0, description="RAM in MB")]
+DockerImageUri: TypeAlias = Annotated[str, Field(description="Container image URI")]
+GpuModel: TypeAlias = Annotated[Optional[str], Field(description="GPU model name")]
+
 
 class Provider:
     """Base compute provider. Subclass and implement call()."""
@@ -34,20 +40,21 @@ class UndefinedProvider(Provider):
 class ComputeSpecification:
     """Specifies compute resources for remote execution."""
 
-    cpu: Annotated[float, Field(gt=0, description="Number of vCPUs")]
-    memory: Annotated[int, Field(gt=0, description="RAM in MB")]
-    image: Annotated[str, Field(description="Container image URI")] = ""
+    timeout: Timeout
+    cpu: CpuCount
+    memory: MemorySize
+    image: DockerImageUri = ""
     provider: Provider = dataclasses.field(default_factory=UndefinedProvider)
-    gpu: Annotated[Optional[str], Field(description="GPU model name")] = None
+    gpu: GpuModel = None
 
 
 @pydantic_dataclass
 class CpuSmall(ComputeSpecification):
     """1 vCPU, 2GB RAM, Python 3.12 slim."""
 
-    cpu: float = 1.0
-    memory: int = 2048
-    image: str = "python:3.12-slim"
+    cpu: CpuCount = 1.0
+    memory: MemorySize = 2048
+    image: DockerImageUri = "python:3.12-slim"
 
 
 user_identifier: Optional[str] = None