blackkube 0.1.0__tar.gz

blackkube-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marcos Gabriel Gomes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

blackkube-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: blackkube
+Version: 0.1.0
+Summary: JSONLine encrypted database with schema validation, CLI, and REST API
+Project-URL: Homepage, https://github.com/marcosgabrielgomes110-collab/kube
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: cryptography>=41
+Requires-Dist: fastapi>=0.100
+Requires-Dist: uvicorn>=0.23
+Requires-Dist: rich>=13
+Requires-Dist: python-multipart>=0.0.6
+Dynamic: license-file

blackkube-0.1.0/README.md

@@ -0,0 +1,161 @@
+# Blackkube
+
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Code style](https://img.shields.io/badge/code%20style-ruff-2ea44f)](https://github.com/astral-sh/ruff)
+
+**Blackkube** is a JSON-line encrypted database for Python. Each collection is a flat file where records are individually encrypted with AES-256-GCM + PBKDF2 (600k rounds). It features schema validation via type hints, unique constraints, optional/default values, a rich CLI, and a REST API built with FastAPI.
+
+```python
+from kube import Kube as kb, Model
+
+class User(Model):
+    name = str
+    email = str
+    age = int
+
+db = kb.storange("/tmp/db", password="minha-senha",
+    collections=[kb.define(User, unique=["email"])])
+
+users = db.collections["user"]
+uid = users.insert(name="Ana", email="ana@x.com", age=25)
+print(users.get(uid))
+```
+
+## Features
+
+- **Encrypted at rest** — AES-256-GCM, unique salt per database, PBKDF2 600k rounds
+- **Schema validation** — declare fields with Python type hints
+- **Unique constraints** — enforced on insert and update
+- **Optional & default values** — `kb.optional(str)` or `kb.default(str, "anonimo")`
+- **Media fields** — `kb.media(max="5mb")` stores files with automatic MIME detection
+- **Rich CLI** — one-shot commands and interactive REPL via `bk`
+- **REST API** — FastAPI server with CORS, multipart upload, static file serving
+- **Thread-safe** — all read/write operations protected by reentrant locks
+- **Zero config** — databases are directories; open and go
+
+## Install
+
+```bash
+pip install blackkube
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/anomalyco/blackkube.git
+cd blackkube
+pip install -e .
+```
+
+## Quickstart
+
+### Python API
+
+```python
+from kube import Kube as kb, Model
+
+class Task(Model):
+    title = str
+    done = bool
+
+with kb.storange("/tmp/tasks", password="secret",
+                 collections=[kb.define(Task)]) as db:
+    todos = db.collections["task"]
+    tid = todos.insert(title="Buy milk", done=False)
+    todos.update(tid, done=True)
+    for t in todos.find():
+        print(t)
+```
+
+### CLI
+
+```bash
+# One-shot commands
+bk --path /tmp/db --password x user insert name=Ana age=25
+bk --path /tmp/db --password x user find age__gte=18
+
+# Interactive REPL
+bk use /tmp/db
+bk> user find
+```
+
+### REST API
+
+```bash
+# Start server
+bk --path /tmp/db server start
+
+# Use the API
+curl http://localhost:8888/user -d '{"name":"Ana","age":25}'
+curl http://localhost:8888/user -X POST -F "avatar=@photo.jpg"
+```
+
+## Documentation
+
+Full documentation is available in the [docs/](docs/) directory (Portuguese):
+
+| Section | Description |
+|---------|-------------|
+| [CLI](docs/cli/) | `bk` command reference |
+| [API](docs/api/) | Python API docs (`Kube`, `Collection`, `Query`, `Model`) |
+| [Types](docs/types/) | Schema declaration (`field`, `optional`, `default`, `media`) |
+| [Modules](docs/modules/) | Internal architecture |
+| [Examples](docs/examples/) | Runnable example scripts |
+| [Web API](docs/webapi/) | REST API reference |
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest tests/
+```
+
+## How it works
+
+Each database is a directory containing:
+
+```
+/tmp/mydb/
+├── server.conf.json       # Server config (host, port, status)
+├── .key                   # Salt + verification token
+└── <collection>/
+    ├── schema.json        # Field types, defaults, optional, unique, media
+    ├── data.jsonl         # AES-256-GCM encrypted records (one per line)
+    ├── data.idx           # Binary index (by_id + unique maps)
+    └── media/             # Uploaded media files (uuid.jpg)
+```
+
+- Records are JSON, encrypted individually with AES-256-GCM, and stored one per line (`.jsonl`)
+- The index file caches `by_id` offsets and unique value → `_id` mappings for O(1) lookups
+- Media files are stored as `<uuid>.jpg`; the record contains only the filename
+- Thread-safe via `threading.RLock()` on every collection operation
+
+## Project structure
+
+```
+blackkube/
+├── kube/                  # Core library
+│   ├── _config.py         # Constants and helpers
+│   ├── _crypto.py         # AES-256-GCM + PBKDF2
+│   ├── _schema.py         # Field types and validation
+│   ├── _index.py          # In-memory index
+│   ├── _collection.py     # Collection CRUD
+│   ├── _query.py          # Query with operators
+│   ├── _storage.py        # Persistence layer
+│   └── __init__.py        # Public API (Kube, Model, query)
+├── cli/                   # CLI and REST server
+│   ├── app.py             # Argument parser and dispatch
+│   ├── commands.py        # Command handlers
+│   ├── render.py          # Rich output
+│   ├── repl.py            # Interactive REPL
+│   ├── server.py          # FastAPI application
+│   └── __main__.py        # Entry point
+├── tests/                 # Test suite (139+ tests)
+├── docs/                  # Documentation
+└── pyproject.toml         # Build configuration
+```
+
+## License
+
+[MIT](LICENSE) © Marcos Gabriel Gomes

blackkube-0.1.0/blackkube.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: blackkube
+Version: 0.1.0
+Summary: JSONLine encrypted database with schema validation, CLI, and REST API
+Project-URL: Homepage, https://github.com/marcosgabrielgomes110-collab/kube
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: cryptography>=41
+Requires-Dist: fastapi>=0.100
+Requires-Dist: uvicorn>=0.23
+Requires-Dist: rich>=13
+Requires-Dist: python-multipart>=0.0.6
+Dynamic: license-file

blackkube-0.1.0/blackkube.egg-info/SOURCES.txt

@@ -0,0 +1,32 @@
+LICENSE
+README.md
+pyproject.toml
+blackkube.egg-info/PKG-INFO
+blackkube.egg-info/SOURCES.txt
+blackkube.egg-info/dependency_links.txt
+blackkube.egg-info/entry_points.txt
+blackkube.egg-info/requires.txt
+blackkube.egg-info/top_level.txt
+cli/__init__.py
+cli/__main__.py
+cli/app.py
+cli/commands.py
+cli/render.py
+cli/repl.py
+cli/server.py
+kube/__init__.py
+kube/_collection.py
+kube/_config.py
+kube/_crypto.py
+kube/_index.py
+kube/_query.py
+kube/_schema.py
+kube/_storage.py
+tests/test_config.py
+tests/test_core.py
+tests/test_crypto.py
+tests/test_index.py
+tests/test_integration.py
+tests/test_query.py
+tests/test_schema.py
+tests/test_server.py

blackkube-0.1.0/blackkube.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

blackkube-0.1.0/blackkube.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bk = cli.__main__:main

blackkube-0.1.0/blackkube.egg-info/requires.txt

@@ -0,0 +1,5 @@
+cryptography>=41
+fastapi>=0.100
+uvicorn>=0.23
+rich>=13
+python-multipart>=0.0.6

blackkube-0.1.0/blackkube.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+cli
+kube

blackkube-0.1.0/cli/__main__.py

@@ -0,0 +1,4 @@
+from .app import main
+
+if __name__ == "__main__":
+    main()

blackkube-0.1.0/cli/app.py

@@ -0,0 +1,182 @@
+import sys, os
+from pathlib import Path
+from getpass import getpass
+from rich.traceback import install as rich_tb
+
+from kube import Kube
+from .render import console, error, info_msg, spinner, parse_keyvals
+from .commands import (
+    cmd_collections, cmd_find, cmd_get, cmd_insert, cmd_update,
+    cmd_delete, cmd_count, cmd_schema, cmd_info,
+    cmd_export, cmd_import, cmd_vacuum, cmd_server,
+)
+from .repl import Repl
+
+rich_tb(show_locals=False)
+
+
+_COLLECTION_CMDS = {
+    "find": cmd_find,
+    "get": cmd_get,
+    "insert": cmd_insert,
+    "update": cmd_update,
+    "delete": cmd_delete,
+    "count": cmd_count,
+    "schema": cmd_schema,
+    "info": cmd_info,
+    "export": cmd_export,
+    "import": cmd_import,
+}
+
+_GLOBAL_CMDS = {
+    "collections": cmd_collections,
+}
+
+
+class App:
+    def __init__(self):
+        self._db = None
+
+    @property
+    def db(self):
+        if self._db is None:
+            error("nenhum database aberto. use: bk use <path>")
+        return self._db
+
+    def connect(self, path, password=None, quiet=False):
+        if password is None:
+            password = getpass("Password: ")
+        try:
+            with spinner("conectando..."):
+                self._db = Kube(Path(path), password)
+            if not quiet:
+                info_msg(f"conectado a {path}")
+            return self._db
+        except PermissionError:
+            error("senha incorreta")
+            return None
+        except Exception as e:
+            error(str(e))
+            return None
+
+    def close(self):
+        if self._db:
+            self._db.close()
+            self._db = None
+
+    def get_collection(self, name):
+        db = self.db
+        if db is None:
+            return None
+        if name not in db.collections:
+            cols = ", ".join(db.collections.keys())
+            error(f"coleção '{name}' não encontrada. collections: {cols}")
+            return None
+        return db.collections[name]
+
+
+def _resolve_password(args_password):
+    if args_password:
+        return args_password
+    pw = os.environ.get("BK_PASSWORD")
+    if pw:
+        return pw
+    return None
+
+
+def main():
+    args = sys.argv[1:]
+    if not args:
+        Repl(App()).run()
+        return
+
+    path = None
+    password = None
+    rest = []
+
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a in ("--path", "-p"):
+            i += 1
+            if i < len(args):
+                path = args[i]
+        elif a in ("--password", "-P"):
+            i += 1
+            if i < len(args):
+                password = args[i]
+        else:
+            rest.append(a)
+        i += 1
+
+    app = App()
+    cmd = rest[0] if rest else None
+    cmd_args = rest[1:] if rest else []
+
+    if cmd == "server":
+        sub = cmd_args[0] if cmd_args else "status"
+        sub_args = cmd_args[1:] if len(cmd_args) > 1 else []
+        sub_filters = parse_keyvals(sub_args) or {}
+        if path:
+            sub_filters["_path"] = path
+        if _resolve_password(password):
+            sub_filters["_password"] = _resolve_password(password)
+        cmd_server(app, sub, sub_filters)
+        return
+
+    if path:
+        pw = _resolve_password(password)
+        quiet = bool(rest)
+        app.connect(path, pw, quiet=quiet)
+        if app._db is None:
+            return
+
+    if not rest:
+        Repl(app).run()
+        return
+
+    if cmd in _GLOBAL_CMDS:
+        if cmd == "collections":
+            if app._db is None:
+                error("nenhum database aberto. use: bk use <path> primeiro")
+                return
+            _GLOBAL_CMDS[cmd](app)
+            app.close()
+        return
+
+    if cmd == "use":
+        if not cmd_args:
+            error("uso: bk use <path>")
+            return
+        app.connect(cmd_args[0])
+        return
+
+    if cmd == "vacuum":
+        if app._db is None:
+            error("nenhum database aberto. use: bk use <path> primeiro")
+            return
+        cmd_vacuum(app, cmd_args[0] if cmd_args else None)
+        app.close()
+        return
+
+    name = cmd
+    sub = cmd_args[0] if cmd_args else None
+    sub_args = cmd_args[1:] if cmd_args else []
+
+    if not sub or sub not in _COLLECTION_CMDS and sub not in _GLOBAL_CMDS:
+        valid = ", ".join(_COLLECTION_CMDS)
+        error(f"comando inválido para coleção '{name}'. comandos: {valid}")
+        return
+
+    if sub == "collections":
+        _GLOBAL_CMDS[sub](app)
+        app.close()
+        return
+
+    filters = parse_keyvals(sub_args)
+    if filters is None:
+        return
+
+    handler = _COLLECTION_CMDS[sub]
+    handler(app, name, filters)
+    app.close()

blackkube-0.1.0/cli/commands.py

@@ -0,0 +1,188 @@
+import sys, os, json
+from kube import query as qry
+from .render import table, record, collections, schema, info as info_view, ok, error, count, spinner, confirm_action
+from . import server as srv
+
+
+def cmd_collections(app):
+    with spinner("carregando coleções..."):
+        colls = app.db.collections
+    collections(colls)
+
+
+def cmd_find(app, name, filters):
+    col = app.get_collection(name)
+    if not col:
+        return
+    try:
+        q = qry(col)
+        rs = q.find(**filters) if filters else col.find()
+    except ValueError as e:
+        error(str(e))
+        return
+    table(rs, title=name)
+
+
+def cmd_get(app, name, filters):
+    col = app.get_collection(name)
+    if not col:
+        return
+    if not filters:
+        error("uso: bk <collection> get campo=valor [...]")
+        return
+    try:
+        r = qry(col).get(**filters)
+    except ValueError as e:
+        error(str(e))
+        return
+    record(r, title=name)
+
+
+def cmd_insert(app, name, data):
+    col = app.get_collection(name)
+    if not col:
+        return
+    if not data:
+        error("uso: bk <collection> insert campo=valor [...]")
+        return
+    try:
+        with spinner("inserindo..."):
+            _id = col.insert(**data)
+    except (ValueError, TypeError) as e:
+        error(str(e))
+        return
+    ok(f"inserido [{col._name}] _id={_id}")
+
+
+def cmd_update(app, name, filters):
+    col = app.get_collection(name)
+    if not col:
+        return
+    if "_id" not in filters:
+        error("uso: bk <collection> update _id=X campo=valor [...]")
+        return
+    _id = filters.pop("_id")
+    if not filters:
+        error("forneça ao menos um campo para alterar")
+        return
+    try:
+        r = col.update(_id, **filters)
+    except ValueError as e:
+        error(str(e))
+        return
+    if r is None:
+        error("registro não encontrado")
+    else:
+        ok("atualizado")
+
+
+def cmd_delete(app, name, filters):
+    col = app.get_collection(name)
+    if not col:
+        return
+    _id = filters.get("_id")
+    if not _id:
+        error("uso: bk <collection> delete _id=X")
+        return
+    if not confirm_action(f"deletar _id={_id} em '{name}'?"):
+        return
+    ok("deletado" if col.delete(_id) else error("registro não encontrado"))
+
+
+def cmd_count(app, name, filters):
+    col = app.get_collection(name)
+    if not col:
+        return
+    try:
+        n = qry(col).count(**filters) if filters else len(col._idx.by_id)
+    except ValueError as e:
+        error(str(e))
+        return
+    count(n)
+
+
+def cmd_schema(app, name, _=None):
+    col = app.get_collection(name)
+    if not col:
+        return
+    schema(col._types, col._defaults, col._optional, col._unique)
+
+
+def cmd_info(app, name, _=None):
+    col = app.get_collection(name)
+    if not col:
+        return
+    info_view(col)
+
+
+def cmd_export(app, name, _):
+    col = app.get_collection(name)
+    if not col:
+        return
+    rs = col.find()
+    json.dump(rs, sys.stdout, indent=2, ensure_ascii=False)
+    sys.stdout.write("\n")
+
+
+def cmd_import(app, name, _):
+    col = app.get_collection(name)
+    if not col:
+        return
+    data = json.load(sys.stdin)
+    if isinstance(data, dict):
+        data = [data]
+    n = 0
+    with spinner("importando..."):
+        for item in data:
+            _id = item.pop("_id", None)
+            item.pop("created_at", None)
+            item.pop("updated_at", None)
+            try:
+                col.insert(**item)
+                n += 1
+            except (ValueError, TypeError) as e:
+                warn(f"falha ao importar: {e}")
+    ok(f"{n} registro(s) importados")
+
+
+def cmd_vacuum(app, name=None):
+    colls = [(n, c) for n, c in app.db.collections.items() if not name or n == name]
+    if name and not colls:
+        error(f"coleção '{name}' não encontrada")
+        return
+    for n, c in colls:
+        with spinner(f"vacuando {n}..."):
+            c.vacuum()
+        ok(f"{n} otimizado")
+
+
+def cmd_server(app, sub, args):
+    db_path = str(app._storage._path) if app._db else args.get("_path", "")
+    if not db_path:
+        error("uso: bk --path /db server <comando>")
+        return
+
+    if sub == "init":
+        srv.init_conf(db_path)
+    elif sub == "start":
+        conf = srv.load_conf(db_path)
+        password = args.get("_password") or os.environ.get("BK_SERVER_PASSWORD") or os.environ.get("BK_PASSWORD")
+        if not password:
+            error("forneca a senha via --password ou BK_SERVER_PASSWORD env var")
+            return
+        host = args.get("host", conf["host"])
+        port = int(args.get("port", conf["port"]))
+        srv.start(db_path, password, host, port)
+    elif sub == "stop":
+        srv.stop(db_path)
+    elif sub == "status" or not sub:
+        srv.status_cmd(db_path)
+    elif sub == "set":
+        k = args.get("key") or next((k for k in ("host", "port", "static_dir") if k in args), None)
+        v = args.get("value") or args.get(k)
+        if not k or not v:
+            error("uso: bk server set host=X|port=Y|static_dir=Z")
+            return
+        srv.set_conf(db_path, k, v)
+    else:
+        error(f"subcomando desconhecido: '{sub}'. use: init|start|stop|status|set")