---
question: How does a module write files that Files can show?
kind: task
via_web: na
via_cli: na
via_python: available
via_api: available
via_config: na
ref_python: engine.services.object_storage
ref_api: GET /api/files/raw/{path}
prereq: For the Python steps, a module. [Create a module](/capabilities/build/modules/creating-a-module) first.
next:
  - /capabilities/build/files/upload-a-file
  - /capabilities/build/modules/module-jobs
---

# Use files in code

Nexus Files and modules share one object storage service. A module reads what members upload, and members see what a module writes into their drive. Code that is not a module, such as a script, uses the Files API instead.

## Web UI

Not applicable. People use Files in Nexus: see [Upload a file](/capabilities/build/files/upload-a-file?via=web). Super admins can check what a module wrote in System › Data › Object storage.

## CLI

Not applicable. There is no `abi` command for object storage. Use another tab on this page. The command list is the [CLI reference](/user-guide/reference/cli).

## Python

### Declare the service

```python title="src/my_module/__init__.py"
from naas_abi_sdk import BaseModule, ModuleDependencies


class ABIModule(BaseModule):
    dependencies = ModuleDependencies(services=("object_storage",))
```

### Read and write

```python
storage = self.engine.services.object_storage
await storage.put_object("my_module", "notes/a.txt", b"hello")
content = await storage.get_object("my_module", "notes/a.txt")   # bytes
names = await storage.list_objects("my_module/notes")             # ["my_module/notes/a.txt"]
await storage.delete_object("my_module", "notes/a.txt")
```

`put_object` replaces an existing object. `get_object` and `delete_object` raise `ObjectNotFound` (`naas_abi_sdk.services.errors`) for a missing key, and `list_objects` for a missing prefix. `list_objects` returns the direct children as full paths, `.nexus_folder` markers included; `list_objects_recursive` walks the whole prefix. `get_object_metadata(prefix, key)` returns an `ObjectMetaData`.

### Stream a large file

`get_object` holds the whole object in memory. For a large one, read and write it in chunks:

```python
with open("report.bin", "rb") as source:
    await storage.put_object_stream("reports", "report.bin", source)

async with storage.get_object_stream("reports", "report.bin") as source:
    async for chunk in source:
        ...  # or await source.read(65536)
```

`put_object_stream` also takes an async stream of chunks, such as an app's `request.stream()`.

### Use a workspace drive

To read what members uploaded, or to put a file where they will see it, use the drive's prefix:

```python
prefix = f"naas_abi/workspace-drive/{workspace_id}/reports"
await storage.put_object(prefix, "summary.md", b"# Summary\n")
```

A prefix of the module's own, like `my_module`, is not in any drive: Files does not show it. Marketplace modules take a `datastore_path` setting for that prefix.

:::warning
Do not write to the local disk and expect Files to show it. With the `s3` adapter, the bytes are not on the disk at all.
:::

## REST API

From code that is not a module, the Files routes of the Nexus API. Auth: a Nexus session of a workspace member (`POST /api/auth/login` returns the access token).

### List a folder

```bash
curl "http://localhost:9879/api/files/?path=reports&workspace_id=$WORKSPACE_ID&scope=workspace" \
  -H "Authorization: Bearer $NEXUS_TOKEN"
```

The answer is `{files, path, total}`. `limit`, `offset`, `search` and `sort_by` (`name`, `size`, `modified`) page and filter it.

### Read a file

```http
GET /api/files/raw/reports/summary.md?workspace_id={workspace_id}&scope=workspace
```

`raw` returns the bytes. `GET /api/files/{path}` returns a text file as JSON, and `PUT /api/files/{path}` replaces a text file's content.

## Config

Not applicable. `services.object_storage` picks the store, and the code is the same for every adapter. See [Object Storage](/capabilities/get-started/configuration#object-storage).
