> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Python: gerenciador de arquivos da aplicação

> Liste, leia, escreva, mova e exclua os arquivos de uma aplicação com client.apps.files. O conteúdo trafega em base64, então binários chegam intactos.

O gerenciador de arquivos fica em `client.apps.files`. Todo método recebe o id da aplicação primeiro e, em seguida, um caminho dentro da aplicação. Os caminhos têm no máximo **256 caracteres**.

Os exemplos usam o `client` de [Criando o cliente](/pt-br/sdks/py/client#criando-o-cliente). `app_id` é o id de uma das suas aplicações: [`client.account.me()`](/pt-br/sdks/py/client#conta) lista todas.

## Listando um diretório

`files.list(app_id, path=None)` lista um diretório (a raiz da aplicação quando `path` é omitido). Ao contrário dos outros modificadores opcionais, `path` pode ser passado por posição.

```python theme={"system"}
for entry in client.apps.files.list(app_id, "/src"):
    print(entry["type"], entry["name"], entry.get("size"), entry.get("lastModified"))
```

| Campo | Tipo | Descrição |
| - | - | - |
| `name` | `str` | Nome da entrada |
| `type` | `"file" \| "directory"` | Tipo da entrada |
| `size` | `int`, opcional | Tamanho em bytes. Ausente em algumas entradas de diretório |
| `lastModified` | `float \| None`, opcional | Unix ms (pode ter fração); `None` quando ilegível |

Um diretório que não existe resulta em 404 `FILE_NOT_FOUND`. Um caminho que o gerenciador de arquivos não expõe resulta em 403 `BLOCKED_PATH`.

## Lendo um arquivo

`files.read(app_id, path)` retorna o conteúdo do arquivo como `bytes`. Os arquivos são limitados a **10 MB**: um maior resulta em 413 `FILE_TOO_LARGE`.

```python theme={"system"}
import json

data = client.apps.files.read(app_id, "/config.json")
text = data.decode()

print(json.loads(text))
```

## Escrevendo um arquivo

`files.write(app_id, path, content)` cria ou sobrescreve um arquivo.

* Uma `str` é enviada como texto simples.
* `bytes` são enviados como base64, então qualquer conteúdo binário chega intacto.
* Conteúdo vazio (`''` ou `b''`) cria um arquivo vazio.

```python theme={"system"}
import json
import urllib.request

# Text
client.apps.files.write(app_id, "/config.json", json.dumps({"debug": False}))

# Binary
with urllib.request.urlopen(image_url) as response:
    image = response.read()
client.apps.files.write(app_id, "/assets/logo.png", image)
```

Conteúdo acima de **10 MB** falha localmente com `FILE_TOO_LARGE` (status `0`) antes que qualquer coisa seja enviada. Conteúdo acima de **1 MiB** é enviado sem timeout depois de conectado, como um upload. Para arquivos maiores, use [`apps.commit()`](/pt-br/sdks/py/commit_and_upload).

<Note>
  Escrever não reinicia a aplicação. Chame [`apps.restart()`](/pt-br/sdks/py/managing_application#iniciar-parar-e-reiniciar) para aplicar a alteração.
</Note>

## Movendo ou renomeando um arquivo

```python theme={"system"}
client.apps.files.move(app_id, "/config.json", "/config.old.json")
```

## Excluindo um arquivo

```python theme={"system"}
client.apps.files.delete(app_id, "/config.old.json")
```

## Erros

| Status | Código | Quando |
| - | - | - |
| 0 | `FILE_TOO_LARGE` | Conteúdo de `write` acima de 10 MB (verificado localmente) |
| 400 | `INVALID_PATH` | O caminho falha na validação (travessia de diretório, caracteres inválidos, longo demais), ou `move` para o mesmo caminho |
| 400 | `DELETE_FAILED`, `RENAME_FAILED` | O cluster não conseguiu excluir ou renomear o arquivo |
| 403 | `BLOCKED_PATH` | O caminho não é exposto pelo gerenciador de arquivos |
| 403 | `PERMISSION_DENIED` | Seu cargo no workspace não pode mexer em um arquivo restrito (como `.env`) |
| 404 | `FILE_NOT_FOUND` | O arquivo ou diretório não existe |
| 413 | `FILE_TOO_LARGE` | `read` de um arquivo acima de 10 MB |
| 429 | `KEEP_CALM` | Mais de 10 escritas em 5 segundos |

Veja [Erros](/pt-br/sdks/py/errors) para os códigos que qualquer chamada pode retornar.

## Próximos passos

<CardGroup cols={3}>
  <Card title="Variáveis de ambiente" icon="key" href="/pt-br/sdks/py/environment_variables">
    Leia e altere as variáveis de uma aplicação.
  </Card>

  <Card title="Referência da API do gerenciador de arquivos" icon="code" href="/pt-br/api-reference/endpoint/apps/filemanager/list">
    Os endpoints REST por trás destes métodos.
  </Card>

  <Card title="Arquivos pela CLI" icon="terminal" href="/pt-br/cli-reference/files">
    As mesmas ações pelo terminal.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.