pybasedb-json 0.3.0__tar.gz → 0.4.0__tar.gz

{pybasedb_json-0.3.0 → pybasedb_json-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pybasedb-json
-Version: 0.3.0
-Summary: Banco de dados local com JSON — schemas, server REST, media, zero dependencias
+Version: 0.4.0
+Summary: Banco de dados local com JSON — schemas, decorator API, server REST, criptografia, zero dependencias
 Author-email: Marcos Gomes <marcosgabrielgomes110@gmail.com>
 Maintainer-email: Marcos Gomes <marcosgabrielgomes110@gmail.com>
 License: MIT
@@ -28,7 +28,7 @@ Description-Content-Type: text/markdown
   <img src="assets/logo/logo.png" width="120" alt="Pybase logo">
 </p>
 
-# Pybase
+# Pybase v0.4
 
 Base para criacao de bancos de dados locais com JSON. Zero dependencias, 100% stdlib.
 Operacoes de escrita atomicas, thread-safe.
@@ -49,32 +49,39 @@ pip install Flask
 ## Uso rapido
 
 ```python
-from pybase import Database, Query, Server
-from pybase.validation import Schema
+from pybase import pybase as pb
 
-# Banco de dados
-db = Database("./data", "mydb", "senha").open("senha")
+# Banco de dados (sem senha ou com senha)
+db = pb.Database("./data/mydb")
+# db = pb.Database("./data/mydb", password="senha").open("senha")
 
-# Colecao com schema (opcional)
-db.schema("users", Schema({
-    "id": str, "name": str, "email": str,
-    "age": (int, 0), "active": (bool, True),
-}))
-users = db.collection("users")
-users.add({"id": "1", "name": "marcos", "email": "m@m.com"})
+# Schema com decorator (v0.4+)
+@db.schema.users
+class User:
+    name: str
+    email: str
+    age: int = 0
+    active: bool = True
+
+# Ou com T() explicito
+# from pybase.validation import T
+# db.schema.users = pb.Schema({"name": pb.T(str), "age": pb.T(int, default=0)})
+
+# Colecao com validacao automatica
+users = db["users"]
+users.add({"name": "marcos", "email": "m@m.com"})  # auto-ID
 
 # SDK client
-doc = users.doc("1").get()
-users.where("age", "==", 30).get()
+doc = users["1"].get()
+users.find(age=0)
 
-# Consultas
-q = Query(users)
-q.sort("name").limit(10).find(active=True)
-q.find_one(name="ana")
-q.exists(name="joao")
+# Consultas direto na colecao (v0.4+)
+users.sort("name").limit(10).find(active=True)
+users.find_one(name="ana")
+users.exists(name="joao")
 
 # Servidor REST (requer Flask)
-Server(db).route("users").run(port=4560)
+pb.Server(db).run(port=4560)  # auto-detecta colecoes
 # Swagger UI: http://localhost:4560/mydb/docs/
 ```
 
@@ -83,48 +90,53 @@ Server(db).route("users").run(port=4560)
 | Modulo | Arquivo | Descricao | Deps |
 |--------|---------|-----------|------|
 | Database | `pybase/database.py` | Gerencia diretorio de tabelas JSON | 0 |
-| Collection | `pybase/collections.py` | CRUD atomico thread-safe | 0 |
-| Query | `pybase/query.py` | Consultas com sort/limit/offset | 0 |
-| Schema | `pybase/validation.py` | Validacao de documentos | 0 |
+| Collection | `pybase/collections.py` | CRUD atomico thread-safe + query integrado | 0 |
+| Query | `pybase/query.py` | Thin wrapper sobre Collection | 0 |
+| Schema | `pybase/validation.py` | Validacao com T(), decorator, from_example | 0 |
 | Server | `pybase/server.py` | REST API automatica + Swagger UI | Flask |
 | Media | `pybase/media.py` | Upload/download de imagens | 0 |
-| Backup | `pybase/backup.py` | Snapshot e restore | 0 |
+| Backup | `pybase/backup.py` | Snapshot e restore (seletivo) | 0 |
+| Crypto | `pybase/crypto.py` | Criptografia stdlib (scrypt + XOR) | 0 |
+
+## Novidades da v0.4
+
+- **API simplificada** — `Database("./data/mydb")` sem senha obrigatoria
+- **`update`/`delete`** — nomes em ingles, sem aliases pt-br
+- **Auto-ID** — `users.add({"name": "x"})` gera UUID automatico
+- **`db["colecao"]`** — acesso direto via `__getitem__`
+- **Query integrado** — `collection.sort().limit().find()` direto
+- **`@db.schema.nome`** — schema via decorator de classe
+- **`T()`** — nova API de tipos com kwargs (`T(int, default=0)`)
+- **`Schema.from_example()`** — schema inferido de dados reais
+- **`import global`** — `from pybase import pybase`
+- **PBKDF2** — hashing de senha com salt (600k iteracoes)
+- **Criptografia** — `encrypt()`/`decrypt()` stdlib puro
+- **Server auto-detect** — `Server(db).run()` descobre colecoes
+- **Erros descritivos** — com path + valor + sugestao
 
 ## Estrutura
 
 ```
 Pybase/
   pybase/
-    __init__.py       # Database, Collection, Query, Server, ...
-    database.py       # Database: init, open, collection, schema, drop
-    collections.py    # Collection, SchemaCollection, DocRef, QueryBuilder
-    query.py          # Query: find/find_one/exists + sort/limit/offset
-    exceptions.py     # PybaseError > DatabaseError, CollectionError
-    validation.py     # Schema, ValidationError
+    __init__.py       # Database, Collection, Query, Server, Schema, T
+    pybase.py         # from pybase import pybase
+    database.py       # Database, SchemaRegistrar
+    collections.py    # Collection, DocRef, QueryBuilder, SchemaCollection
+    query.py          # Query wrapper
+    exceptions.py     # PybaseError > DatabaseError, CollectionError, ...
+    validation.py     # Schema, T, ValidationError
     server.py         # Server REST (Flask)
     media.py          # MediaManager
     index.py          # Index (hash O(1))
     hooks.py          # HooksCollection
     backup.py         # take, restore
-    utils.py          # Utils: sha256 encode
+    crypto.py         # encrypt, decrypt (stdlib)
+    utils.py          # PBKDF2 encode/verify
   docs/               # Documentacao completa
   pyproject.toml
 ```
 
-## Novidades da versao (0.3+)
-
-- **Schema validation** — defina schemas opcionais por colecao, persistidos em disco, validacao automatica em `add`/`add_many`/`actualize`
-- **Server REST** — `Server(db).route("x").run()` gera CRUD automatico com Swagger UI e OpenAPI spec
-- **MediaManager** — upload de imagens (path, bytes, base64), CRUD de metadados, serve files via HTTP
-- **SDK client** — `doc("id").get()`, `where("f", "==", "v").get()`
-- **SchemaCollection** — auto-wrap quando schema existe, validacao parcial em updates
-- **Backup** — `take()`/`restore()` com snapshot gzip atomico
-- **Escrita atomica** — `.tmp` + `os.replace()` protege contra corrupcao
-- **Path traversal fix** — nomes de colecao sanitizados com regex
-- **Sort seguro** — tipos mistos (int + str) nao quebram mais
-- **Indices em memoria** — `Index(field)` para lookups O(1)
-- **Lifecycle hooks** — `HooksCollection` com callbacks before/after
-
 ## Documentacao
 
 Veja [docs/](docs/index.md) com referencia completa de cada classe e metodo.

pybasedb_json-0.4.0/README.md

@@ -0,0 +1,120 @@
+<p align="center">
+  <img src="assets/logo/logo.png" width="120" alt="Pybase logo">
+</p>
+
+# Pybase v0.4
+
+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
+
+```bash
+pip install pybasedb-json
+```
+
+Para o servidor REST (opcional):
+```bash
+pip install Flask
+```
+
+## Uso rapido
+
+```python
+from pybase import pybase as pb
+
+# Banco de dados (sem senha ou com senha)
+db = pb.Database("./data/mydb")
+# db = pb.Database("./data/mydb", password="senha").open("senha")
+
+# Schema com decorator (v0.4+)
+@db.schema.users
+class User:
+    name: str
+    email: str
+    age: int = 0
+    active: bool = True
+
+# Ou com T() explicito
+# from pybase.validation import T
+# db.schema.users = pb.Schema({"name": pb.T(str), "age": pb.T(int, default=0)})
+
+# Colecao com validacao automatica
+users = db["users"]
+users.add({"name": "marcos", "email": "m@m.com"})  # auto-ID
+
+# SDK client
+doc = users["1"].get()
+users.find(age=0)
+
+# Consultas direto na colecao (v0.4+)
+users.sort("name").limit(10).find(active=True)
+users.find_one(name="ana")
+users.exists(name="joao")
+
+# Servidor REST (requer Flask)
+pb.Server(db).run(port=4560)  # auto-detecta colecoes
+# Swagger UI: http://localhost:4560/mydb/docs/
+```
+
+## Modulos
+
+| Modulo | Arquivo | Descricao | Deps |
+|--------|---------|-----------|------|
+| Database | `pybase/database.py` | Gerencia diretorio de tabelas JSON | 0 |
+| Collection | `pybase/collections.py` | CRUD atomico thread-safe + query integrado | 0 |
+| Query | `pybase/query.py` | Thin wrapper sobre Collection | 0 |
+| Schema | `pybase/validation.py` | Validacao com T(), decorator, from_example | 0 |
+| Server | `pybase/server.py` | REST API automatica + Swagger UI | Flask |
+| 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 |
+
+## Novidades da v0.4
+
+- **API simplificada** — `Database("./data/mydb")` sem senha obrigatoria
+- **`update`/`delete`** — nomes em ingles, sem aliases pt-br
+- **Auto-ID** — `users.add({"name": "x"})` gera UUID automatico
+- **`db["colecao"]`** — acesso direto via `__getitem__`
+- **Query integrado** — `collection.sort().limit().find()` direto
+- **`@db.schema.nome`** — schema via decorator de classe
+- **`T()`** — nova API de tipos com kwargs (`T(int, default=0)`)
+- **`Schema.from_example()`** — schema inferido de dados reais
+- **`import global`** — `from pybase import pybase`
+- **PBKDF2** — hashing de senha com salt (600k iteracoes)
+- **Criptografia** — `encrypt()`/`decrypt()` stdlib puro
+- **Server auto-detect** — `Server(db).run()` descobre colecoes
+- **Erros descritivos** — com path + valor + sugestao
+
+## Estrutura
+
+```
+Pybase/
+  pybase/
+    __init__.py       # Database, Collection, Query, Server, Schema, T
+    pybase.py         # from pybase import pybase
+    database.py       # Database, SchemaRegistrar
+    collections.py    # Collection, DocRef, QueryBuilder, SchemaCollection
+    query.py          # Query wrapper
+    exceptions.py     # PybaseError > DatabaseError, CollectionError, ...
+    validation.py     # Schema, T, ValidationError
+    server.py         # Server REST (Flask)
+    media.py          # MediaManager
+    index.py          # Index (hash O(1))
+    hooks.py          # HooksCollection
+    backup.py         # take, restore
+    crypto.py         # encrypt, decrypt (stdlib)
+    utils.py          # PBKDF2 encode/verify
+  docs/               # Documentacao completa
+  pyproject.toml
+```
+
+## Documentacao
+
+Veja [docs/](docs/index.md) com referencia completa de cada classe e metodo.
+
+## Licenca
+
+MIT

pybasedb_json-0.4.0/pybase/__init__.py

@@ -0,0 +1,44 @@
+try:
+    from .server import Server
+except ImportError:
+    Server = None
+
+from .collections import Collection, DocRef, QueryBuilder, SchemaCollection
+from .database import Database
+from .exceptions import (
+    CollectionError,
+    DatabaseError,
+    DocumentNotFoundError,
+    EncryptionError,
+    MediaError,
+    PybaseError,
+    QueryError,
+    ValidationError,
+)
+from .query import Query
+
+try:
+    from .validation import Schema, T
+except ImportError:
+    Schema = None
+    T = None
+
+__all__ = [
+    "Collection",
+    "Database",
+    "DocRef",
+    "DocumentNotFoundError",
+    "EncryptionError",
+    "MediaError",
+    "PybaseError",
+    "DatabaseError",
+    "CollectionError",
+    "Query",
+    "QueryBuilder",
+    "QueryError",
+    "Schema",
+    "SchemaCollection",
+    "Server",
+    "T",
+    "ValidationError",
+]

{pybasedb_json-0.3.0 → pybasedb_json-0.4.0}/pybase/backup.py

@@ -22,8 +22,8 @@ def take(
     dest: str | Path | None = None,
     *,
     compress: bool = True,
+    collections: list[str] | None = None,
 ) -> Path:
-    # Snapshot every collection into one timestamped file
     backup_dir = Path(dest) if dest else (db.path_dir / _BACKUP_DIR)
     backup_dir.mkdir(parents=True, exist_ok=True)
 
@@ -31,8 +31,9 @@ def take(
     ext = ".json.gz" if compress else ".json"
     out_path = backup_dir / f"{db.name}_{ts}{ext}"
 
+    names = collections if collections else db.collections
     snapshot: dict[str, list[dict]] = {}
-    for name in db.collections():
+    for name in names:
         snapshot[name] = db.collection(name).all()
 
     raw = json.dumps(snapshot, indent=2).encode("utf-8")

{pybasedb_json-0.3.0 → pybasedb_json-0.4.0}/pybase/collections.py

@@ -1,6 +1,8 @@
 import json
 import os
 import threading
+import uuid
+from collections.abc import Callable
 from pathlib import Path
 
 from .exceptions import CollectionError
@@ -10,6 +12,10 @@ class Collection:
     def __init__(self, file_path: str | Path) -> None:
         self.file_path = Path(file_path)
         self._lock = threading.Lock()
+        self._limit: int | None = None
+        self._offset: int | None = None
+        self._sort_key: str | None = None
+        self._sort_reverse: bool = False
 
     def __str__(self) -> str:
         return str(self.file_path)
@@ -20,8 +26,21 @@ class Collection:
     def __iter__(self):
         return iter(self._load())
 
-    def __getitem__(self, index: int | slice) -> dict | list[dict]:
-        return self._load()[index]
+    def __getitem__(self, key: str | int | slice) -> dict | list[dict] | None:
+        if isinstance(key, str):
+            return self.get(key)
+        return self._load()[key]
+
+    def __setitem__(self, doc_id: str, data: dict) -> None:
+        if not isinstance(doc_id, str):
+            raise TypeError("key must be a string document ID")
+        data = dict(data)
+        data["id"] = doc_id
+        existing = self.get(doc_id)
+        if existing:
+            self.update(data, id=doc_id)
+        else:
+            self.add(data)
 
     # -- internal I/O (unsafe -- caller must hold lock) --
 
@@ -40,7 +59,6 @@ class Collection:
         return data
 
     def _save_nolock(self, data: list) -> None:
-        # write to .tmp then rename — atomic on POSIX / Windows
         tmp = self.file_path.with_suffix(".tmp")
         with open(tmp, "w", encoding="utf-8") as f:
             json.dump(data, f, indent=4)
@@ -65,15 +83,89 @@ class Collection:
             if all(doc.get(k) == v for k, v in match.items())
         )
 
-    # .get() without args returns all docs; with args returns by id/key
-    def get(self, doc_id=None, key="id"):
-        if doc_id is None:
-            return self.all()
+    def get(self, doc_id: str) -> dict | None:
         for doc in self._load():
-            if doc.get(key) == doc_id:
+            if doc.get("id") == doc_id:
                 return doc
         return None
 
+    # -- query methods (fluent, chained directly on Collection) --
+
+    def sort(self, key: str, reverse: bool = False) -> "Collection":
+        self._sort_key = key
+        self._sort_reverse = reverse
+        return self
+
+    def limit(self, n: int) -> "Collection":
+        self._limit = n
+        return self
+
+    def offset(self, n: int) -> "Collection":
+        self._offset = n
+        return self
+
+    def _make_sort_key(self) -> Callable[[dict], tuple]:
+        key = self._sort_key
+        type_order = {int: 0, float: 0, bool: 1, str: 2}
+        def _key(doc: dict) -> tuple:
+            val = doc.get(key)
+            if val is None:
+                return (1, 0, 0)
+            priority = type_order.get(type(val), 99)
+            return (0, priority, val)
+        return _key
+
+    def _apply(self, docs: list[dict]) -> list[dict]:
+        if self._sort_key:
+            docs = sorted(docs, key=self._make_sort_key(), reverse=self._sort_reverse)
+        if self._offset is not None:
+            docs = docs[self._offset:]
+        if self._limit is not None:
+            docs = docs[: self._limit]
+        return docs
+
+    def _reset_query(self) -> None:
+        self._limit = None
+        self._offset = None
+        self._sort_key = None
+        self._sort_reverse = False
+
+    def find(self, **match) -> list[dict]:
+        try:
+            docs = self.all()
+            if match:
+                docs = [
+                    doc for doc in docs
+                    if all(doc.get(k) == v for k, v in match.items())
+                ]
+            return self._apply(docs)
+        finally:
+            self._reset_query()
+
+    def find_one(self, **match) -> dict | None:
+        try:
+            docs = self.all()
+            if match:
+                docs = [
+                    doc for doc in docs
+                    if all(doc.get(k) == v for k, v in match.items())
+                ]
+            result = self._apply(docs)
+            return result[0] if result else None
+        finally:
+            self._reset_query()
+
+    def exists(self, **match) -> bool:
+        try:
+            if not match:
+                return len(self) > 0
+            for doc in self.all():
+                if all(doc.get(k) == v for k, v in match.items()):
+                    return True
+            return False
+        finally:
+            self._reset_query()
+
     # -- SDK-style helpers --
 
     def doc(self, doc_id: str) -> "DocRef":
@@ -86,6 +178,8 @@ class Collection:
 
     def add(self, data: dict) -> dict:
         doc = dict(data)
+        if "id" not in doc:
+            doc["id"] = str(uuid.uuid4())
         with self._lock:
             docs = self._load_nolock()
             docs.append(doc)
@@ -97,34 +191,38 @@ class Collection:
             raise TypeError("add_many() expects a list of dicts")
         with self._lock:
             docs = self._load_nolock()
-            added = [dict(item) for item in items]
+            added = []
+            for item in items:
+                doc = dict(item)
+                if "id" not in doc:
+                    doc["id"] = str(uuid.uuid4())
+                added.append(doc)
             docs.extend(added)
             self._save_nolock(docs)
         return added
 
-    def actualize(self, data: dict, **match) -> int:
+    def update(self, data: dict, **match) -> int:
         if not match:
             raise CollectionError(
                 "provide at least one filter field, "
-                "e.g. actualize({'age': 20}, name='marcos')"
+                "e.g. update({'age': 20}, name='marcos')"
             )
         with self._lock:
             docs = self._load_nolock()
             updated = 0
             for i, doc in enumerate(docs):
                 if all(doc.get(k) == v for k, v in match.items()):
-                    # defensive copy — don't mutate original dicts in memory
                     docs[i] = {**doc, **data}
                     updated += 1
             if updated:
                 self._save_nolock(docs)
         return updated
 
-    def rem(self, **match) -> int:
+    def delete(self, **match) -> int:
         if not match:
             raise CollectionError(
                 "provide at least one filter field, "
-                "e.g. rem(name='marcos')"
+                "e.g. delete(name='marcos')"
             )
         with self._lock:
             docs = self._load_nolock()
@@ -152,10 +250,10 @@ class DocRef:
         return self._col.get(self._id)
 
     def update(self, data: dict) -> int:
-        return self._col.actualize(data, id=self._id)
+        return self._col.update(data, id=self._id)
 
     def delete(self) -> int:
-        return self._col.rem(id=self._id)
+        return self._col.delete(id=self._id)
 
 
 class QueryBuilder:
@@ -177,18 +275,13 @@ class QueryBuilder:
 
 
 class SchemaCollection:
-    # Wraps a Collection + optional Schema.
-    # Validates all writes against the schema before delegating.
-
     def __init__(self, collection: Collection, schema=None) -> None:
         self._col = collection
-        self._schema = schema  # None = passthrough, no validation
+        self._schema = schema
 
     def set_schema(self, schema) -> None:
         self._schema = schema
 
-    # -- schema-aware writes --
-
     def add(self, data: dict) -> dict:
         doc = self._schema.validate(data) if self._schema else dict(data)
         return self._col.add(doc)
@@ -198,12 +291,10 @@ class SchemaCollection:
             items = [self._schema.validate(d) for d in items]
         return self._col.add_many(items)
 
-    def actualize(self, data: dict, **match) -> int:
+    def update(self, data: dict, **match) -> int:
         if self._schema:
-            self._schema.validate(data, partial=True)  # partial update — only check types
-        return self._col.actualize(data, **match)
-
-    # -- delegation (reads + rem + drop + SDK helpers) --
+            self._schema.validate(data, partial=True)
+        return self._col.update(data, **match)
 
     def __getattr__(self, name: str):
         return getattr(self._col, name)

pybasedb_json-0.4.0/pybase/crypto.py

@@ -0,0 +1,59 @@
+import base64
+import hashlib
+import os
+
+from .exceptions import EncryptionError
+
+
+def _derive_key(password: str, salt: bytes, key_len: int = 32) -> bytes:
+    return hashlib.scrypt(
+        password.encode("utf-8"),
+        salt=salt,
+        n=16384,
+        r=8,
+        p=1,
+        dklen=key_len,
+    )
+
+
+def encrypt(data: str | bytes, password: str) -> str:
+    if isinstance(data, str):
+        data = data.encode("utf-8")
+    salt = os.urandom(16)
+    key = _derive_key(password, salt, len(data))
+    encrypted = bytes(a ^ b for a, b in zip(data, key))
+    payload = salt + encrypted
+    return base64.urlsafe_b64encode(payload).decode("ascii")
+
+
+def decrypt(payload: str, password: str) -> str:
+    try:
+        raw = base64.urlsafe_b64decode(payload.encode("ascii"))
+    except Exception as e:
+        raise EncryptionError(f"invalid encrypted payload: {e}")
+    if len(raw) < 16:
+        raise EncryptionError("payload too short")
+    salt = raw[:16]
+    encrypted = raw[16:]
+    key = _derive_key(password, salt, len(encrypted))
+    decrypted = bytes(a ^ b for a, b in zip(encrypted, key))
+    try:
+        return decrypted.decode("utf-8")
+    except UnicodeDecodeError:
+        raise EncryptionError("incorrect password or corrupted data")
+
+
+def encrypt_bytes(data: bytes, password: str) -> bytes:
+    salt = os.urandom(16)
+    key = _derive_key(password, salt, len(data))
+    encrypted = bytes(a ^ b for a, b in zip(data, key))
+    return salt + encrypted
+
+
+def decrypt_bytes(payload: bytes, password: str) -> bytes:
+    if len(payload) < 16:
+        raise EncryptionError("payload too short")
+    salt = payload[:16]
+    encrypted = payload[16:]
+    key = _derive_key(password, salt, len(encrypted))
+    return bytes(a ^ b for a, b in zip(encrypted, key))