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

pybasedb_json-0.3.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: pybasedb-json
+Version: 0.3.0
+Summary: Banco de dados local com JSON — schemas, server REST, media, zero dependencias
+Author-email: Marcos Gomes <marcosgabrielgomes110@gmail.com>
+Maintainer-email: Marcos Gomes <marcosgabrielgomes110@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/marcosgabrielgomes110-collab/Pybase
+Project-URL: Documentation, https://github.com/marcosgabrielgomes110-collab/Pybase/tree/main/docs
+Project-URL: Repository, https://github.com/marcosgabrielgomes110-collab/Pybase
+Keywords: database,json,local,embedded,nosql,thread-safe,rest-api,schema,media
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/logo/logo.png" width="120" alt="Pybase logo">
+</p>
+
+# Pybase
+
+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 Database, Query, Server
+from pybase.validation import Schema
+
+# Banco de dados
+db = Database("./data", "mydb", "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"})
+
+# SDK client
+doc = users.doc("1").get()
+users.where("age", "==", 30).get()
+
+# Consultas
+q = Query(users)
+q.sort("name").limit(10).find(active=True)
+q.find_one(name="ana")
+q.exists(name="joao")
+
+# Servidor REST (requer Flask)
+Server(db).route("users").run(port=4560)
+# 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 | 0 |
+| Query | `pybase/query.py` | Consultas com sort/limit/offset | 0 |
+| Schema | `pybase/validation.py` | Validacao de documentos | 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 |
+
+## 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
+    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
+  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.
+
+## Licenca
+
+MIT

pybasedb_json-0.3.0/README.md

@@ -0,0 +1,108 @@
+<p align="center">
+  <img src="assets/logo/logo.png" width="120" alt="Pybase logo">
+</p>
+
+# Pybase
+
+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 Database, Query, Server
+from pybase.validation import Schema
+
+# Banco de dados
+db = Database("./data", "mydb", "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"})
+
+# SDK client
+doc = users.doc("1").get()
+users.where("age", "==", 30).get()
+
+# Consultas
+q = Query(users)
+q.sort("name").limit(10).find(active=True)
+q.find_one(name="ana")
+q.exists(name="joao")
+
+# Servidor REST (requer Flask)
+Server(db).route("users").run(port=4560)
+# 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 | 0 |
+| Query | `pybase/query.py` | Consultas com sort/limit/offset | 0 |
+| Schema | `pybase/validation.py` | Validacao de documentos | 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 |
+
+## 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
+    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
+  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.
+
+## Licenca
+
+MIT

pybasedb_json-0.3.0/pybase/__init__.py

@@ -0,0 +1,29 @@
+try:
+    from .server import Server
+except ImportError:
+    Server = None  # Flask not installed — server unavailable
+
+from .collections import Collection, DocRef, QueryBuilder, SchemaCollection
+from .database import Database
+from .exceptions import CollectionError, DatabaseError, PybaseError
+from .query import Query
+
+# Optional Lego-piece modules (import explicitly):
+#   from pybase.validation import Schema, ValidationError
+#   from pybase.index import Index
+#   from pybase.hooks import HooksCollection
+#   from pybase.backup import take, restore
+#   from pybase.media import MediaManager, MediaError
+
+__all__ = [
+    "Database",
+    "Collection",
+    "SchemaCollection",
+    "DocRef",
+    "QueryBuilder",
+    "Query",
+    "Server",
+    "PybaseError",
+    "DatabaseError",
+    "CollectionError",
+]

pybasedb_json-0.3.0/pybase/backup.py

@@ -0,0 +1,99 @@
+# Lego piece: optional backup / restore for Pybase databases.
+#   from pybase.backup import take, restore, list_snapshots
+#   snap = take(db)  # timestamped .json.gz
+
+from __future__ import annotations
+
+import gzip
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .database import Database
+
+_BACKUP_DIR = "backups"
+
+
+def take(
+    db: Database,
+    dest: str | Path | None = None,
+    *,
+    compress: bool = True,
+) -> 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)
+
+    ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+    ext = ".json.gz" if compress else ".json"
+    out_path = backup_dir / f"{db.name}_{ts}{ext}"
+
+    snapshot: dict[str, list[dict]] = {}
+    for name in db.collections():
+        snapshot[name] = db.collection(name).all()
+
+    raw = json.dumps(snapshot, indent=2).encode("utf-8")
+
+    if compress:
+        # mtime=0 makes the gzip deterministic (same content → same bytes)
+        with gzip.GzipFile(out_path, "wb", mtime=0) as f:
+            f.write(raw)
+    else:
+        out_path.write_bytes(raw)
+
+    return out_path
+
+
+def restore(
+    db_dir: str | Path,
+    snapshot: str | Path,
+    *,
+    merge: bool = False,
+) -> None:
+    # Restore collection data from a snapshot file (.json or .json.gz)
+    db_dir = Path(db_dir)
+    snap_path = Path(snapshot)
+
+    if snap_path.suffix == ".gz":
+        with gzip.GzipFile(snap_path, "rb") as f:
+            raw = f.read()
+    else:
+        raw = snap_path.read_bytes()
+
+    data: dict[str, list[dict]] = json.loads(raw)
+
+    for name, docs in data.items():
+        col_path = db_dir / f"{name}_table.json"
+        existing = []
+        if merge and col_path.exists():
+            existing = (json.loads(col_path.read_bytes()) if col_path.stat().st_size else [])
+        merged = existing + docs if merge else docs
+
+        # atomic write
+        tmp = col_path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(merged, indent=2), encoding="utf-8")
+        os.replace(tmp, col_path)
+
+
+def list_snapshots(backup_dir: str | Path) -> list[Path]:
+    # Return snapshots sorted newest first
+    d = Path(backup_dir)
+    if not d.exists():
+        return []
+    files = sorted(p for p in d.iterdir() if p.suffix in (".json", ".gz") and p.stem != ".tmp")
+    return list(reversed(files))
+
+
+def clean(backup_dir: str | Path, *, keep: int = 10, dry_run: bool = False) -> list[Path]:
+    # Remove old snapshots, keeping the `keep` most recent
+    snaps = list_snapshots(backup_dir)
+    if len(snaps) <= keep:
+        return []
+    to_remove = snaps[keep:]
+    if not dry_run:
+        for p in to_remove:
+            p.unlink()
+    return to_remove

pybasedb_json-0.3.0/pybase/collections.py

@@ -0,0 +1,218 @@
+import json
+import os
+import threading
+from pathlib import Path
+
+from .exceptions import CollectionError
+
+
+class Collection:
+    def __init__(self, file_path: str | Path) -> None:
+        self.file_path = Path(file_path)
+        self._lock = threading.Lock()
+
+    def __str__(self) -> str:
+        return str(self.file_path)
+
+    def __len__(self) -> int:
+        return len(self._load())
+
+    def __iter__(self):
+        return iter(self._load())
+
+    def __getitem__(self, index: int | slice) -> dict | list[dict]:
+        return self._load()[index]
+
+    # -- internal I/O (unsafe -- caller must hold lock) --
+
+    def _load_nolock(self) -> list:
+        if not self.file_path.exists():
+            return []
+        try:
+            with open(self.file_path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+        except json.JSONDecodeError:
+            raise CollectionError(f"corrupted file: {self.file_path}")
+        if not isinstance(data, list):
+            raise CollectionError(
+                f"expected a list, got {type(data).__name__}: {self.file_path}"
+            )
+        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)
+        os.replace(tmp, self.file_path)
+
+    def _load(self) -> list:
+        with self._lock:
+            return self._load_nolock()
+
+    # -- reads (thread-safe via _load) --
+
+    def all(self) -> list[dict]:
+        return list(self._load())
+
+    def count(self, **match) -> int:
+        if not match:
+            return len(self._load())
+        docs = self._load()
+        return sum(
+            1
+            for doc in docs
+            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()
+        for doc in self._load():
+            if doc.get(key) == doc_id:
+                return doc
+        return None
+
+    # -- SDK-style helpers --
+
+    def doc(self, doc_id: str) -> "DocRef":
+        return DocRef(self, doc_id)
+
+    def where(self, field: str, op: str, value) -> "QueryBuilder":
+        return QueryBuilder(self).where(field, op, value)
+
+    # -- writes (atomic: single lock for read-modify-write) --
+
+    def add(self, data: dict) -> dict:
+        doc = dict(data)
+        with self._lock:
+            docs = self._load_nolock()
+            docs.append(doc)
+            self._save_nolock(docs)
+        return doc
+
+    def add_many(self, items: list[dict]) -> list[dict]:
+        if not isinstance(items, list):
+            raise TypeError("add_many() expects a list of dicts")
+        with self._lock:
+            docs = self._load_nolock()
+            added = [dict(item) for item in items]
+            docs.extend(added)
+            self._save_nolock(docs)
+        return added
+
+    def actualize(self, data: dict, **match) -> int:
+        if not match:
+            raise CollectionError(
+                "provide at least one filter field, "
+                "e.g. actualize({'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:
+        if not match:
+            raise CollectionError(
+                "provide at least one filter field, "
+                "e.g. rem(name='marcos')"
+            )
+        with self._lock:
+            docs = self._load_nolock()
+            kept = [
+                doc
+                for doc in docs
+                if not all(doc.get(k) == v for k, v in match.items())
+            ]
+            removed = len(docs) - len(kept)
+            if removed:
+                self._save_nolock(kept)
+        return removed
+
+    def drop(self) -> None:
+        with self._lock:
+            self._save_nolock([])
+
+
+class DocRef:
+    def __init__(self, collection: Collection, doc_id: str) -> None:
+        self._col = collection
+        self._id = doc_id
+
+    def get(self) -> dict | None:
+        return self._col.get(self._id)
+
+    def update(self, data: dict) -> int:
+        return self._col.actualize(data, id=self._id)
+
+    def delete(self) -> int:
+        return self._col.rem(id=self._id)
+
+
+class QueryBuilder:
+    def __init__(self, collection: Collection) -> None:
+        self._col = collection
+        self._filters: list[tuple[str, str]] = []
+
+    def where(self, field: str, op: str, value) -> "QueryBuilder":
+        if op != "==":
+            raise ValueError(f"unsupported operator: {op!r} (only '==' for now)")
+        self._filters.append((field, value))
+        return self
+
+    def get(self) -> list[dict]:
+        docs = self._col.all()
+        for field, value in self._filters:
+            docs = [d for d in docs if d.get(field) == value]
+        return docs
+
+
+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
+
+    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)
+
+    def add_many(self, items: list[dict]) -> list[dict]:
+        if self._schema:
+            items = [self._schema.validate(d) for d in items]
+        return self._col.add_many(items)
+
+    def actualize(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) --
+
+    def __getattr__(self, name: str):
+        return getattr(self._col, name)
+
+    def __str__(self) -> str:
+        return str(self._col)
+    def __len__(self) -> int:
+        return len(self._col)
+    def __iter__(self):
+        return iter(self._col)
+    def __getitem__(self, i):
+        return self._col[i]

{pybasedb_json-0.2.0 → pybasedb_json-0.3.0}/pybase/database.py

@@ -1,11 +1,14 @@
 import json
+import re
 import shutil
 from pathlib import Path
 
-from .collections import Collection
+from .collections import Collection, SchemaCollection
 from .exceptions import DatabaseError
 from .utils import Utils
 
+_COLLECTION_NAME_RE = re.compile(r"^[a-zA-Z0-9_-]+$")
+
 
 class Database:
     def __init__(self, local: str | Path, name: str, password: str) -> None:
@@ -27,14 +30,14 @@ class Database:
     def _verify_password(self, password: str) -> dict:
         try:
             with open(self.path_conf, "r", encoding="utf-8") as f:
-                dados = json.load(f)
+                data = json.load(f)
         except (FileNotFoundError, json.JSONDecodeError):
             raise DatabaseError(
-                f"database '{self.name}' corrompido ou inexistente"
+                f"database '{self.name}' is corrupted or does not exist"
             )
-        if str(Utils.encode(password)) != dados.get("password"):
-            raise DatabaseError("senha incorreta")
-        return dados
+        if str(Utils.encode(password)) != data.get("password"):
+            raise DatabaseError("incorrect password")
+        return data
 
     def open(self, password: str) -> "Database":
         self._verify_password(password)
@@ -59,12 +62,43 @@ class Database:
     def collections(self) -> list[str]:
         return [p.stem.removesuffix("_table") for p in self._table_paths()]
 
-    def collection(self, name: str) -> Collection:
+    def collection(self, name: str) -> SchemaCollection | Collection:
+        # Returns a SchemaCollection if a schema file exists, plain Collection otherwise.
+        if not _COLLECTION_NAME_RE.match(name):
+            raise ValueError(
+                f"invalid collection name: {name!r}. "
+                "Use only letters, digits, hyphens, and underscores."
+            )
         path = self.path_dir / f"{name}_table.json"
         if not path.exists():
             with open(path, "w", encoding="utf-8") as f:
                 json.dump([], f, indent=4)
-        return Collection(path)
+
+        col = Collection(path)
+
+        # Auto-wrap if a schema file exists
+        schema_path = self.path_dir / f"{name}_schema.json"
+        if schema_path.exists():
+            from .validation import Schema
+            data = json.loads(schema_path.read_text())
+            return SchemaCollection(col, Schema.from_dict(data))
+
+        return col
+
+    def schema(self, name: str, schema) -> "Database":
+        # Register a persistent schema for a collection.
+        # Returns self for fluent chaining.
+        if not _COLLECTION_NAME_RE.match(name):
+            raise ValueError(
+                f"invalid collection name: {name!r}. "
+                "Use only letters, digits, hyphens, and underscores."
+            )
+        schema_path = self.path_dir / f"{name}_schema.json"
+        schema_path.write_text(
+            json.dumps(schema.to_dict(), indent=2),
+            encoding="utf-8",
+        )
+        return self
 
     def drop(self, password: str) -> None:
         self._verify_password(password)