Metadata-Version: 2.4
Name: pyspiral
Version: 0.16.33
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: License :: Other/Proprietary License
Requires-Dist: betterproto2>=0.9.0
Requires-Dist: click>=8.0.0
Requires-Dist: google-re2>=1.1.20240702
Requires-Dist: grpclib>=0.4.7
Requires-Dist: httpx>=0.27.0
Requires-Dist: pyarrow>=21.0.0
Requires-Dist: pydantic[email]>=2.13.1,<2.14
Requires-Dist: pyjwt[crypto]>=2.9.0
Requires-Dist: pyperclip>=1.9.0
Requires-Dist: questionary==2.1.1
Requires-Dist: typer>=0.16
Requires-Dist: zstandard>=0.23.0
Requires-Dist: orjson>=3.10.0
Requires-Dist: substrait<0.31
Requires-Dist: duckdb>=1.3.2 ; extra == 'duckdb'
Requires-Dist: datasets>=4.3.0 ; extra == 'huggingface'
Requires-Dist: pyiceberg[s3fs]>=0.9.1 ; extra == 'iceberg'
Requires-Dist: polars>=1.31.0 ; extra == 'polars'
Requires-Dist: rasterio ; extra == 'rasterio'
Requires-Dist: ray[data]>=2.55.0 ; extra == 'ray'
Requires-Dist: cloudpickle>=3 ; extra == 'ray'
Requires-Dist: rerun-sdk>=0.26.0 ; extra == 'viz'
Requires-Dist: rerun-notebook>=0.30.0 ; extra == 'viz'
Requires-Dist: attrs ; extra == 'viz'
Provides-Extra: duckdb
Provides-Extra: huggingface
Provides-Extra: iceberg
Provides-Extra: polars
Provides-Extra: rasterio
Provides-Extra: ray
Provides-Extra: viz
Summary: Python client for Spiral.
Home-Page: https://spiraldb.com
Author-email: SpiralDB <hello@spiraldb.com>
License: Proprietary License
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# PySpiral

PySpiral is the legacy SpiralDB Python API. It remains available as
`pip install pyspiral` with `import spiral`, and continues to target the old
table format.

The new engine SDK is published separately as `spiraldb` and uses
`import spiraldb`.

## Third-Party Notices

PySpiral packages include `spiral/THIRD_PARTY_NOTICES.md`.

## Volumes on hosted SpiralDB

Choose an existing Volume when creating a project:

```python
import spiral

client = spiral.Spiral()
project = client.create_project(description="Archive", volume_id="vol_example")
print(project.get_storage())
```

List available Volumes with `client.api.volumes.list()`. To register an existing
AWS bucket or prefix with OIDC credentials:

```python
from spiral.api.volumes import AwsOidcCredential, RegisterVolumeRequest

volume = client.api.volumes.register(
    RegisterVolumeRequest(
        name="Archive",
        uri="s3://my-bucket/archive/",
        region="eu-west-2",
        credential=AwsOidcCredential(
            role_arn="arn:aws:iam::123456789012:role/spiral-storage",
            region="eu-west-2",
        ),
    )
)
print(volume.identity.trust_policy)
```

Apply the returned trust policy to the AWS role before using the storage.
Registration does not create a bucket or test object reads and writes. Volume
registration and changes require organization owner permissions.

The same API accepts `GcsOidcCredential`, `R2Credential`, and
`S3LikeCredential` (providers `minio`, `rustfs`, and `s3_like`). Read responses
omit secrets. Organization members can receive only a Volume's ID and name;
its storage details and identity are available to owners.

Use `client.api.volumes.update_status(volume.id, "retired")` to stop new
allocations, or `"revoked"` to stop issuing or renewing access. Already issued
credentials remain usable until they expire. Use `"active"` to reactivate it.
`client.api.volumes.update_credential(volume.id, credential)` replaces the
credential while retaining the storage root.

For an existing project:

```python
from spiral.api.volumes import FileSystemStorage, VolumeStorage

project.select_storage(VolumeStorage(volume_id="vol_example"))
project.select_storage(FileSystemStorage())
```

Storage selection controls allocation of new managed tables on servers that
support Volumes. It does not move existing data or change PySpiral's legacy
table format. This client support does not port the new engine's data path.

Without `volume_id`, project creation keeps the organization's default-storage
behavior. The `filesystem` parameter remains available for legacy servers;
current hosted servers require Volumes instead of an explicit `filesystem`.
Do not pass both parameters.

The legacy CLI provides the same operations:

```sh
spiral volumes ls
spiral volumes register --name Archive --uri s3://my-bucket/archive/ \
  --provider aws --role-arn arn:aws:iam::123456789012:role/spiral-storage --region eu-west-2
spiral projects create --description Archive --volume vol_example
spiral projects storage project_example
spiral projects storage project_example --volume vol_example
spiral projects storage project_example --file-system
spiral volumes status vol_example retired
spiral volumes credential vol_example --provider aws \
  --role-arn arn:aws:iam::123456789012:role/spiral-storage --region eu-west-2
```

For S3-compatible storage, use `--provider s3_like` (or `minio` / `rustfs`)
and `--endpoint`. For R2, use `--provider r2 --account-id ACCOUNT_ID` and,
if needed, `--jurisdiction eu`. These providers read `AWS_ACCESS_KEY_ID` and
`AWS_SECRET_ACCESS_KEY` from the environment, as legacy `fs update` does.
For GCS OIDC, use `--provider gcs --workload-identity-provider PROVIDER_RESOURCE`
and `--service-account EMAIL`.

JSON files remain optional: `spiral volumes register --request-file volume.json`
or `spiral volumes credential vol_example --request-file credential.json`.
Do not combine `--request-file` with storage flags. `volume.json` uses the server's registration format:

```json
{
  "name": "Archive",
  "uri": "s3://my-bucket/archive/",
  "region": "eu-west-2",
  "credential": {
    "provider": "aws",
    "type": "oidc",
    "roleArn": "arn:aws:iam::123456789012:role/spiral-storage",
    "region": "eu-west-2"
  }
}
```

`credential.json` contains just the `credential` field with the replacement
credential. Access-key secrets come from environment variables or the optional JSON file;
they do not need to appear in shell arguments.


### Migrating legacy `fs` commands

The following commands are deprecated. They still call the legacy APIs for
compatibility, and print a warning and migration instructions to stderr.

| Deprecated command | Replacement |
| --- | --- |
| `spiral fs show PROJECT` | `spiral projects storage PROJECT` |
| `spiral fs list-providers` | `spiral volumes ls` |
| `spiral fs update PROJECT ...` | `spiral volumes register --name NAME --uri URI --provider PROVIDER ...`, then `spiral projects storage PROJECT --volume VOLUME_ID` |

Choose a platform Volume from `volumes ls` instead of a built-in provider.
For a custom bucket, register its root once and select that Volume for each
project that should use it. An AWS or GCS Volume has its own OIDC identity:
configure the returned trust policy instead of reusing a legacy file system's
identity. Volume selection does not migrate existing files.

`spiral fs mounts` remains available. Mount management has no equivalent in the
Volume API, and its server endpoints are not deprecated.

