Metadata-Version: 2.4
Name: nexus-fs
Version: 0.4.2
Summary: Unified filesystem abstraction for cloud storage — mount S3, GCS, and local storage with two lines of Python
Project-URL: Homepage, https://github.com/nexi-lab/nexus
Project-URL: Documentation, https://nexi-lab.github.io/nexus/latest/
Project-URL: Repository, https://github.com/nexi-lab/nexus
Project-URL: Issues, https://github.com/nexi-lab/nexus/issues
Author: Nexi Lab Team
License-Expression: Apache-2.0
Keywords: agents,ai,cloud,filesystem,gcs,s3,storage,vfs
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
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: Topic :: System :: Filesystems
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: aiofiles>=23.0
Requires-Dist: anyio>=4.0
Requires-Dist: blake3>=0.4
Requires-Dist: click>=8.0
Requires-Dist: cryptography>=41.0
Requires-Dist: orjson>=3.9
Requires-Dist: platformdirs>=4.0
Requires-Dist: pydantic[email]>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: all
Requires-Dist: boto3>=1.28; extra == 'all'
Requires-Dist: fsspec>=2024.0; extra == 'all'
Requires-Dist: google-api-python-client>=2.0; extra == 'all'
Requires-Dist: google-auth-oauthlib>=1.0; extra == 'all'
Requires-Dist: google-cloud-storage>=2.0; extra == 'all'
Requires-Dist: rapidfuzz>=3.0; extra == 'all'
Requires-Dist: textual>=1.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: boto3>=1.28; extra == 'dev'
Requires-Dist: fsspec>=2024.0; extra == 'dev'
Requires-Dist: google-api-python-client>=2.0; extra == 'dev'
Requires-Dist: google-auth-oauthlib>=1.0; extra == 'dev'
Requires-Dist: google-cloud-storage>=2.0; extra == 'dev'
Requires-Dist: moto[s3]>=5.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-textual-snapshot>=1.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: rapidfuzz>=3.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: textual>=1.0; extra == 'dev'
Provides-Extra: edit
Requires-Dist: rapidfuzz>=3.0; extra == 'edit'
Provides-Extra: fsspec
Requires-Dist: fsspec>=2024.0; extra == 'fsspec'
Provides-Extra: gcs
Requires-Dist: google-cloud-storage>=2.0; extra == 'gcs'
Provides-Extra: gdrive
Requires-Dist: google-api-python-client>=2.0; extra == 'gdrive'
Requires-Dist: google-auth-oauthlib>=1.0; extra == 'gdrive'
Provides-Extra: s3
Requires-Dist: boto3>=1.28; extra == 's3'
Provides-Extra: tui
Requires-Dist: textual>=1.0; extra == 'tui'
Description-Content-Type: text/markdown

# nexus-fs

Unified filesystem abstraction for cloud storage. Mount S3, GCS, Google Workspace, and local storage with two lines of Python.

```python
import nexus.fs

fs = nexus.fs.mount_sync("s3://my-bucket", "local://./data")
content = fs.read("/s3/my-bucket/README.md")
```

## Install

```bash
pip install nexus-fs            # core (local only)
pip install nexus-fs[s3]        # + Amazon S3
pip install nexus-fs[gcs]       # + Google Cloud Storage
pip install nexus-fs[gdrive]    # + Google Drive
pip install nexus-fs[fsspec]    # + fsspec/pandas/dask integration
pip install nexus-fs[tui]       # + interactive TUI playground
pip install nexus-fs[all]       # everything
```

## Quick Start

### Async

```python
import asyncio
import nexus.fs

async def main():
    fs = await nexus.fs.mount("s3://my-bucket", "local://./data")
    await fs.write("/local/data/hello.txt", b"Hello!")
    content = await fs.read("/local/data/hello.txt")
    print(content)

asyncio.run(main())
```

### Sync

```python
import nexus.fs

fs = nexus.fs.mount_sync("local://./data")
fs.write("/local/data/hello.txt", b"Hello!")
print(fs.read("/local/data/hello.txt"))
```

### Connectors (Google Workspace, GitHub, Slack, etc.)

```python
import nexus.fs

fs = nexus.fs.mount_sync("gws://sheets", "gws://docs")
# Uses gws CLI under the hood — no server needed
```

> **Prerequisite:** `gws://` mounts require the
> [gws CLI](https://github.com/nicholasgasior/gws) to be installed and
> authenticated. Other connectors (GitHub, Slack) require OAuth
> credentials configured via environment variables — see
> `nexus-fs doctor` for diagnostics.

## API

| Method | Description |
|--------|-------------|
| `read(path)` | Read file content |
| `write(path, content)` | Write/overwrite file |
| `ls(path, detail, recursive)` | List directory |
| `stat(path)` | Get file metadata |
| `exists(path)` | Check if path exists |
| `delete(path)` | Delete a file |
| `rename(old, new)` | Rename/move |
| `copy(src, dst)` | Copy a file |
| `mkdir(path)` | Create directory |
| `list_mounts()` | List mount points |

## TUI Playground

```bash
pip install nexus-fs[tui]
nexus-fs playground s3://my-bucket local://./data
```

## CLI

```bash
nexus-fs mount s3://my-bucket
nexus-fs mount list
nexus-fs mount test s3://my-bucket
nexus-fs unmount s3://my-bucket
```

> **Note:** The TUI uses direct backend access for low-latency browsing.
> File operation semantics in the playground may differ from the library API
> (e.g., metadata fields, error messages). The library API (`mount()` /
> `mount_sync()`) is the authoritative interface. TUI/library unification
> is planned for a future release.

## State Directory

nexus-fs stores runtime state (metadata DB, mount config) in a platform-specific
directory. This state is a **cache** — it can be safely deleted and will be
recreated on the next `mount()` call.

| Platform | Default path |
|----------|-------------|
| Linux | `~/.local/state/nexus-fs/` |
| macOS | `~/Library/Application Support/nexus-fs/` |
| Windows | `%LOCALAPPDATA%/nexus-fs/` |

Override with the `NEXUS_FS_STATE_DIR` environment variable.

Persistent secrets (OAuth tokens, encryption keys) are stored separately
under `~/.nexus/` with restricted permissions (`0700`).
Override with `NEXUS_FS_PERSISTENT_DIR`.

> **Concurrency:** nexus-fs is designed for single-process use per state
> directory. To run multiple independent instances, set a different
> `NEXUS_FS_STATE_DIR` for each process.

## Relationship to `nexus-ai-fs`

`nexus-fs` is the **slim standalone** cloud storage package (~16 dependencies).
`nexus-ai-fs` is the **full** Nexus filesystem/context plane (~100+ dependencies)
that includes server, bricks, gRPC, federation, and more.

Both packages install into the `nexus` Python namespace. **Do not install both
in the same environment** — they will conflict. Choose one:

- `pip install nexus-fs` — lightweight cloud storage only
- `pip install nexus-ai-fs` — full Nexus system (includes all `nexus-fs` functionality)

## License

Apache-2.0
