pybasedb-json 0.5.0

Banco de dados local com JSON — schemas, decorator API, server REST, criptografia, zero dependencias

Pybase v0.5

Base para criacao de bancos de dados locais com JSON. Zero dependencias, 100% stdlib. Operacoes de escrita atomicas, thread-safe.

Filosofia Lego: cada modulo e independente — voce monta o que precisa.

Instalacao

pip install pybasedb-json

Para o servidor REST (opcional):

pip install Flask

Uso rapido

from pybase import pybase as pb

# Banco de dados
db = pb.Database("./data/mydb")

# Schema com decorator
@db.schema.users
class User:
    name: str
    email: str
    age: int = 0
    active: bool = True
    tags: list[str] = []

# Colecao com validacao automatica
users = db["users"]
users.add({"name": "marcos", "email": "[e-mail]"})

# Operadores de query (v0.5+)
users.find(age__gt=18, name__contains="mar")

# Paginacao (v0.5+)
users.paginate(page=1, per_page=20)

# Transacao (v0.5+)
with db.transaction() as txn:
    txn["users"].add({"name": "ana"})

# Server com auth + CORS (v0.5+)
pb.Server(db, auth="token123", cors="*").run()

# CLI (v0.5+)
# $ pybase serve mydb --port=4560

Modulos

Modulo	Arquivo	Descricao	Deps
Database	pybase/database.py	Gerencia diretorio de tabelas JSON	0
Collection	pybase/collections.py	CRUD atomico + query com operadores + JSONL	0
Filter	pybase/filters.py	Motor de filtros com 13 operadores	0
Query	pybase/query.py	Thin wrapper sobre Collection	0
Schema	pybase/validation.py	Validacao com choices, min/max, email, datetime, UUID, ref, JSON Schema	0
Ref	pybase/ref.py	Referencias entre colecoes	0
Server	pybase/server.py	REST API com auth, cors, patch, batch + Swagger UI	Flask
CLI	pybase/cli/	Linha de comando: init, inspect, serve, backup (ASCII + ANSI)	0
Media	pybase/media.py	Upload/download de imagens	0
Backup	pybase/backup.py	Snapshot e restore (seletivo)	0
Crypto	pybase/crypto.py	Criptografia stdlib (scrypt + XOR)	0
Hooks	pybase/hooks.py	Lifecycle hooks para Collection	0
Plugin	pybase/plugin.py	Sistema de plugins globais	0
Transaction	pybase/transaction.py	Multi-colecao commit/rollback	0
Migration	pybase/migration.py	Migracoes versionadas	0
Async	pybase/async_.py	Wrappers assincronos	0
Index	pybase/index.py	Indices hash O(1) (memoria + persistente)	0

Novidades da v0.5

• Operadores de query — __gt, __contains, __in, __has, __regex e mais 13
• Paginacao — .paginate(page, per_page) → {items, total, pages}
• Projecao — .select("name", "age") para campos especificos
• Agregacao — .aggregate([$match, $group, $sort, ...])
• Schema avancado — choices, min/max, email, url, datetime, UUID, ref
• Ref — Ref("users", "abc").resolve(db) para referencias entre colecoes
• JSON Schema — .to_json_schema() export draft-07
• CLI — pybase init, inspect, serve, backup, query, schema, ...
• Server auth — Server(db, auth="token"), Basic Auth, callback
• Server CORS — Server(db, cors="*") ou lista de origens
• PATCH — atualizacao parcial via REST
• Batch — operacoes em lote via REST
• Transacoes — with db.transaction() as txn: commit/rollback
• Plugins — Plugin class com on_add, on_update, etc
• Migracoes — Migration(db).add(ver, fn).run()
• Async — AsyncCollection, AsyncDatabase (via asyncio.to_thread)
• Eventos — col.on("add", cb) observer pattern
• JSONL — formato linha-por-linha para append O(1)
• Lock multi-processo — Collection(lock_type="process")
• PersistentIndex — indice salvo em disco
• Clone — db.clone(dest) copia banco
• Context manager — with Database(...) as db:

Estrutura

Pybase/
  pybase/
    __init__.py       # Database, Collection, Query, Server, Schema, T, Filter, Ref
    __main__.py       # python -m pybase
    pybase.py         # from pybase import pybase
    database.py       # Database, SchemaRegistrar
    collections.py    # Collection, DocRef, QueryBuilder, SchemaCollection
    filters.py        # Filter: operadores de query
    query.py          # Query wrapper
    exceptions.py     # PybaseError > DatabaseError, CollectionError, ...
    validation.py     # Schema, T, ValidationError
    ref.py            # Ref: referencias entre colecoes
    server.py         # Server REST (Flask) com auth/cors/patch/batch
    cli/              # CLI: init, inspect, serve, backup (ASCII + ANSI)
    media.py          # MediaManager
    index.py          # Index + PersistentIndex
    hooks.py          # HooksCollection
    backup.py         # take, restore
    crypto.py         # encrypt, decrypt (stdlib)
    plugin.py         # Plugin system
    transaction.py    # Transaction commit/rollback
    migration.py      # Migration versionada
    async_.py         # AsyncCollection, AsyncDatabase
    lock.py           # FileLock multi-processo
    utils.py          # PBKDF2 encode/verify
  docs/               # Documentacao completa (23 paginas)
  index.html          # Documentacao web
  pyproject.toml

Documentacao

Veja docs/ ou index.html com referencia completa de cada classe e metodo.

Licenca

MIT