jsonbox-nosql 1.0.1

Banco de dados NoSQL simples baseado em arquivos JSON

jsonbox

Banco de dados NoSQL simples que salva tudo em arquivos JSON.

Sem servidor, sem instalação complexa. Só Python puro + arquivos.

pip install jsonbox-nosql

Depois de instalado:

from jsonbox import Database, Tables

---

Estrutura

jsonbox/
  core/
    database.py   → abrir/criar banco com senha
    tables.py     → CRUD nas tabelas (add, find, remove, view, update, schema)
  scripts/
    cli.py        → usar pelo terminal

Cada tabela vira um arquivo {nome}_tbl.json. Cada banco vira uma pasta com um {nome}_conf.json de configuração.

---

Começar rápido

import os
from dotenv import load_dotenv
from jsonbox.core.database import Database
from jsonbox.core.tables import Tables

load_dotenv()

db = Database(
    os.getenv('path'),      # pasta onde criar o banco
    os.getenv('name'),      # nome da pasta do banco
    os.getenv('user'),      # usuario
    os.getenv('passw'),     # senha
)
db.create()
database = db.open()        # retorna Path da pasta

tbl = Tables(database, ['users', 'produtos']).autocreate()

Arquivo .env obrigatório:

path=/home/voce/meuprojeto
name=meu_banco
user=admin
passw=123

---

API completa

Database

Método	O que faz	Retorna
create()	Cria a pasta do banco + config com user/senha	Path
open()	Autentica e libera acesso ao banco	Path ou False

db = Database('/pasta', 'nome_do_banco', 'admin', '123')
db.create()         # cria pasta + config se nao existir
caminho = db.open()  # autentica e devolve o Path
if not caminho:
    print('senha errada')

---

Tables

Método	O que faz	Retorna
autocreate()	Cria arquivos {tabela}_tbl.json vazios se nao existirem	self (pra encadear)
add(tabela, dados)	Insere um dict na tabela	bool
find(tabela, **filtros)	Busca registros	list[dict]
remove(tabela, **filtros)	Remove registros	list[dict] (removidos)
view(tabela)	Mostra tudo na tela	list[dict]
update(tabela, dados, **filtros)	Atualiza campos dos registros que batem	int (quantidade)
schema(tabela, campos)	Define campos obrigatorios	bool

---

autocreate()

Cria as tabelas da lista se ainda nao existirem.

tbl = Tables(database, ['users', 'produtos']).autocreate()
# Cria:  users_tbl.json  e  produtos_tbl.json

---

add()

Insere um registro. Respeita schema se tiver.

tbl.add('users', {
    'name': 'marcos',
    'email': '[e-mail]',
    'password': '123456',
})
# True  → deu certo
# False → tabela nao existe ou schema barrou

---

find()

Filtra registros. Pode ser exato ou parcial.

# Busca exata (padrao)
tbl.find('users', name='marcos')
# → [{'name': 'marcos', 'email': '...', 'password': '...'}]

# Busca parcial (pedaco do texto)
tbl.find('users', partial=True, name='mar')
# → [{'name': 'marcos', ...}]

# Multiplos filtros (match_all=True → E, match_all=False → OU)
tbl.find('users', match_all=True, name='marcos', email='x')

---

remove()

Remove registros que baterem com o filtro. Filtro obrigatorio.

removidos = tbl.remove('users', name='marcos')
# retorna a lista dos que foram removidos

removidos = tbl.remove('users', partial=True, email='test')

---

view()

Mostra todos os registros da tabela no terminal.

tbl.view('users')
# printa bonito e retorna a lista

---

update()

Altera campos de todos os registros que baterem com o filtro. Filtro obrigatorio.

qtd = tbl.update('users', {'email': '[e-mail]'}, name='marcos')
# retorna quantos registros foram alterados (int)

---

schema()

Define campos obrigatorios para add(). Se faltar, o add() rejeita.

tbl.schema('users', ['name', 'email', 'password'])

# Agora add() so aceita se tiver TODOS esses campos:
tbl.add('users', {'name': 'joao'})
# → False  (faltou email e password)

tbl.add('users', {'name': 'joao', 'email': '[e-mail]', 'password': '123'})
# → True

Schema e opcional. Se nao definir, add() aceita qualquer dict.

---

CLI (terminal)

Todos os comandos disponiveis direto no terminal:

python -m jsonbox.scripts.cli add    users  '{"name":"joao","email":"[e-mail]"}'
python -m jsonbox.scripts.cli view   users
python -m jsonbox.scripts.cli find   users  name=joao
python -m jsonbox.scripts.cli find   users  name=jo --partial
python -m jsonbox.scripts.cli remove users  name=joao
python -m jsonbox.scripts.cli update users  '{"email":"x"}' name=joao
python -m jsonbox.scripts.cli schema users  name email password

---

Como os dados ficam salvos

database_test/                    ← pasta do banco
  database_test_conf.json         ← config (user + senha)
  users_tbl.json                  ← dados da tabela "users"
  users_schema.json               ← schema da tabela "users" (opcional)
  merchant_tbl.json               ← dados da tabela "merchant"

---

Instalação via PyPI

pip install jsonbox-nosql

O nome no PyPI é jsonbox-nosql ( jsonbox já existe). O import continua sendo:

from jsonbox import Database, Tables

Licenca

MIT — use, copie, modifique, venda. So nao reclame se perder dados.