Metadata-Version: 2.5
Name: shade-plugins-planilhas
Version: 0.1.0
Summary: Ler Excel e CSV como lista de itens e escrever planilha sem deixar texto virar fórmula.
Author: ShadeOne
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: openpyxl>=3.1
Requires-Dist: shade-sdk<0.23,>=0.12.0
Description-Content-Type: text/markdown

# shade-plugins-planilhas

Lê Excel e CSV como lista de itens e escreve planilha sem deixar o texto virar fórmula. É um
plugin do [`shade-sdk`](https://pypi.org/project/shade-sdk/); roda offline, sem credencial e sem
nenhuma operação com efeito.

No `shade.toml` do robô:

```toml
[plugins]
planilhas = "0.1.0"
```

```python
import shade_plugins_planilhas as planilhas

itens = planilhas.ler("pedidos.xlsx", aba="Abril")   # [{"cliente": "Acme", "valor": "10.5"}, ...]
planilhas.escrever_xlsx("saida.xlsx", itens)
planilhas.escrever_csv("saida.csv", itens)
item.anexar("saida.xlsx")                            # leva o arquivo para a saída do run
```

| Operação | O que faz |
| --- | --- |
| `ler(caminho, aba=None)` | Itens de `.xlsx`/`.xlsm` (a aba pedida ou a primeira) ou `.csv`. A primeira linha é o cabeçalho; tudo vem em texto, e o mesmo dado em XLSX e em CSV dá os mesmos itens. |
| `abas(caminho)` | Nomes das abas de um `.xlsx`/`.xlsm`. |
| `escrever_xlsx(caminho, itens, aba="Planilha1")` | Grava os itens; o cabeçalho é a união das chaves. |
| `escrever_csv(caminho, itens, delimitador=";")` | Grava UTF-8 com BOM, que o Excel brasileiro abre sem estragar acento. |

- **CSV:** o delimitador (`;`, `,`, tab ou `|`) é detectado; UTF-8 e, se não for, Windows-1252.
- **Fórmula:** texto que começa com `=`, `+`, `-`, `@`, tab ou CR é gravado como texto. No XLSX
  a célula é de texto; no CSV o valor sai com um `'` na frente. Número, booleano e data não são
  texto e passam como vieram.
- **Não lê** `.xls` antigo: salve como `.xlsx` ou `.csv`. Fórmula de uma planilha lida vale o
  último valor que o Excel calculou.
