Metadata-Version: 2.5
Name: sqlbased
Version: 0.2.2
Summary: Biblioteca Python para organizar bancos SQLite usando classes e geradores.
Author: João Pedro Nascimento
License-Expression: MIT
Keywords: database,orm,python,sql,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# SQLBased

SQLBased é uma biblioteca Python leve para usar SQLite com classes e geradores, sem precisar escrever `INSERT` manualmente para operações comuns.

## Requisitos

- Python 3.10 ou superior
- SQLite via `sqlite3` (incluído no Python)

## Exemplo compatível com a API 0.1.x

```python
from sqlbased import Sql, Db, Table

sql = Sql()
data = Db("jogo.db", sql())

class Jogadores(Table):
    def new_table(self):
        yield self.CTable("jogadores", tag="joga")
        yield self.IDColumn()
        yield self.Column("player", show_title="Jogador", type="str")
        yield self.Column("points", show_title="Pontos", type="int")

jogadores = data.table.new(Jogadores())

def novo_jogador(table):
    yield table.player("João Pedro")
    yield table.points(100)

jogadores.add(novo_jogador(jogadores))
print(jogadores.data().to_dict())
print(data.file.data().to_dict())
data.file.end()
```

## Novidades da 0.2.0

- Corrigida a indentação/fluxo de `add_from()` e transações atômicas para inserções em lote.
- `data(where, params, order_by=..., limit=..., offset=...)` para consultas filtradas.
- `get(id)` para buscar um registro ou retornar `None`.
- `delete(where, params)` para exclusão com filtro obrigatório.
- `transaction()` para commit/rollback explícito.
- `Db` pode ser usado como context manager; `close()` é um alias conveniente.
- Validação de identificadores e parâmetros SQL para valores.
- `TableData` é iterável e aceita `len()`.

## Consultas com filtros

```python
# Valores são passados separadamente, evitando interpolação SQL de valores.
melhores = jogadores.data(
    "points >= ?", (100,), order_by="points DESC", limit=10
)
print(melhores.to_dict())

joao = jogadores.get(1)  # dict ou None
alterados = jogadores.modify(melhores, "points", 200)
removidos = jogadores.delete("points < ?", (0,))
```

`where` e `order_by` são expressões SQL, portanto só devem conter SQL confiável escrito pelo programador. Passe os valores em `params`; nunca monte o filtro com dados não confiáveis.

## Transações e fechamento

```python
with data.table.new(Jogadores()) as_placeholder:
    pass
```

Para transação, use o handle da tabela:

```python
with jogadores.transaction():
    jogadores.add(novo_jogador(jogadores))
    # Uma exceção dentro do bloco faz rollback.
```

Ou gerencie a conexão:

```python
with Db("jogo.db") as db:
    # use db.table / db.file
    ...
```

`data.file.end()` continua disponível para compatibilidade e fecha a conexão.

## Desenvolvimento

```bash
python -m pytest
python -m build
```

## Licença

MIT. Consulte `LICENSE` no repositório.


## Filtrar e remover tabelas (0.2.0)

```python
# Retorna TableData com todos os critérios combinados por AND
joao = table.filter(person="João")
perfeitos = table.filter(person="João", score=100)
todos = table.filter()

# Remove a tabela inteira e seus dados
table.drop()
```

`filter()` valida os nomes das colunas e passa valores como parâmetros SQL; use `None` para procurar valores `NULL`. `drop()` é destrutivo e remove a tabela inteira.
