pyvelm 0.1.0__tar.gz

pyvelm-0.1.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: pyvelm
+Version: 0.1.0
+Summary: Odoo-style ERP framework — recordsets, declarative models, env-bound cache.
+Requires-Python: >=3.10
+Requires-Dist: psycopg[binary]>=3.2
+Requires-Dist: psycopg-pool>=3.2
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: python-multipart>=0.0.18
+Requires-Dist: bcrypt>=4.2
+Requires-Dist: uvicorn>=0.29
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.27; extra == "docs"

pyvelm-0.1.0/README.md

@@ -0,0 +1,80 @@
+# pyvelm
+
+An Odoo-style ERP framework in Python, built from first principles. The point
+isn't to reinvent Odoo — it's to keep the core ideas visible so the design
+trade-offs stay legible while the framework grows.
+
+Status: **Stage 5 Slice A complete.** Access control + HTTP Basic
+auth land on top of Stage 4's full UI: `res.groups`, `res.users`
+(bcrypt), `ir.model.access`, `ir.rule` enforce per-model CRUD perms
+and AND-inject row-level filters into every search. Anonymous reads
+are denied unless a `group_id=None` grant exists; HTTP Basic against
+`res.users.login` populates `env.uid`; superuser at uid=1 bypasses.
+On top of Stage 4 (three view types, mutations, inheritance,
+TypedDicts), Stage 3 (module loader, migrations), and Stage 2 (ORM
+with all four relational field types, computed fields, dotted-path
+traversal) — all on PostgreSQL via psycopg 3. View inheritance is dict-merge with
+Odoo XPath-position parity, addressing into list `fields` *and*
+form `sections[*].fields`. A two-mode widget registry dispatches
+rendering by `(field_type, hint, mode)`. Built on Stage 3 (module
+loader, transactional install/upgrade, hand-written migrations) and
+Stage 2 (ORM with all four relational field types, computed fields,
+dotted-path traversal in both `@depends` and domains) — all on
+PostgreSQL via psycopg 3.
+
+## Quickstart
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e .
+cp .env.example .env       # then edit PYVELM_DSN
+.venv/bin/python examples/basic.py
+```
+
+The example smoke test exercises every feature including the HTMX UI.
+The compiled CSS bundle lives at `pyvelm/static/dist/pyvelm.css` and
+is checked in, so a fresh clone runs without Node. If you want to
+hack on styling or component markup:
+
+```bash
+npm install            # installs Tailwind v4 + Flowbite into node_modules/
+npm run dev            # watch mode: rebuilds dist/pyvelm.css on save
+npm run build          # one-shot minified build + Flowbite JS copy
+```
+
+The build scans `pyvelm/templates/**/*.html` and `pyvelm/render.py`
+for utility classes (Tailwind v4 `@source` directives in
+`pyvelm/static/tailwind.css`). Add new utility classes in those files
+and the next build picks them up.
+
+The example exercises every feature: CRUD, recordset semantics, all four
+relational field types, M2o traversal, computed fields, dependency-graph
+invalidation, and the singleton guard.
+
+## Documentation
+
+- [Architecture overview](docs/architecture.md) — the big picture: why
+  recordsets, what `env.cache` is for, how the dependency graph works, the
+  multi-pass init sequence.
+- [Module loading & migrations](docs/module-loading.md) — manifest format,
+  loader lifecycle, the active-registry contextvar, writing migrations.
+- [Web layer & views as data](docs/web-layer.md) — `ir.ui.view`, the
+  `VIEWS` manifest key, the FastAPI app factory, JSON serialization
+  shape, three view types, mutations, inline edit.
+- [Access control](docs/acl.md) — the four ACL models, HTTP Basic
+  authentication, superuser bypass, record rules, anonymous access
+  conventions.
+- [Module reference](docs/modules.md) — what lives in each module, the
+  public surface, and the invariants worth knowing.
+- [Extending fields](docs/extending-fields.md) — implementing a custom field
+  type without breaking the cache contract.
+- [CONTEXT.md](CONTEXT.md) — current stage state, deferred items, and the
+  next concrete task.
+
+## What's deliberately not here yet
+
+Things deferred with eyes open, not by accident: LRU/eviction on `env.cache`,
+auto-generated schema diffs (migrations are hand-written),
+Odoo-style M2M command tuples, transaction boundaries beyond psycopg
+autocommit, schema migrations, module loading. See
+[CONTEXT.md](CONTEXT.md) for the rationale.

pyvelm-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "pyvelm"
+version = "0.1.0"
+description = "Odoo-style ERP framework — recordsets, declarative models, env-bound cache."
+requires-python = ">=3.10"
+dependencies = [
+    "psycopg[binary]>=3.2",
+    "psycopg-pool>=3.2",
+    "python-dotenv>=1.0",
+    "fastapi>=0.115",
+    "httpx>=0.27",
+    "jinja2>=3.1",
+    "python-multipart>=0.0.18",
+    "bcrypt>=4.2",
+    "uvicorn>=0.29",
+]
+
+[project.optional-dependencies]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.27",
+]
+
+[project.scripts]
+pyvelm = "pyvelm.cli:main"
+# Legacy entry — `pyvelm cron` is the canonical form going forward.
+# Kept so existing docker-compose / systemd configs survive upgrades
+# without edits.
+pyvelm-cron = "pyvelm.cli:cron_main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["pyvelm*"]
+exclude = ["examples*", "tests*"]
+
+[tool.setuptools.package-data]
+pyvelm = [
+    "templates/*.html",
+    "templates/**/*.html",
+    "static/*.css",
+    "static/dist/*",
+    # Bundled modules. The directory deliberately has no __init__.py
+    # so `pyvelm.modules.<name>` is NOT importable — the loader picks
+    # up each module via sys.path injection on `pyvelm/modules/`, the
+    # same path it uses for example addons.
+    "modules/**/*.py",
+    "modules/**/__pyvelm__.py",
+    # Scaffolder templates materialised by `pyvelm init` / `pyvelm new`.
+    # The `dot*` prefix is the rename-on-copy convention — see
+    # pyvelm/scaffolder.py for the substitution rules.
+    "scaffolds/**/*",
+]

pyvelm-0.1.0/pyvelm/__init__.py

@@ -0,0 +1,75 @@
+from pathlib import Path as _Path
+
+# Public version string. Keep in sync with ``[project].version`` in
+# ``pyproject.toml`` — the release workflow refuses to publish if
+# they diverge, but the check is only enforced in CI; bump both
+# together when cutting a release.
+__version__ = "0.1.0"
+
+from .depends import depends
+from .env import Environment
+from .fields import (
+    Boolean,
+    Char,
+    Field,
+    Float,
+    Integer,
+    Many2many,
+    Many2one,
+    One2many,
+    Text,
+)
+from . import builders
+from . import loader
+from . import types
+from .model import BaseModel
+from .registry import Registry
+# NOTE: ServerAction, AutomatedAction, CronJob, Message, MailThread are
+# NOT imported here because they define BaseModel subclasses which must
+# only be evaluated inside a `with registry.activate():` block (i.e. during
+# module loading).  Import them directly from their modules when needed:
+#   from pyvelm.actions import ServerAction
+#   from pyvelm.mail import MailThread, Message
+# The engine helpers (AutomationEngine, CronJob.run_due) are always safe
+# to import because they only touch the registry at call time.
+
+# Discovery root for the modules bundled inside the wheel. Today the
+# framework ships two: ``base`` (the primitives every app needs:
+# ir.ui.view / res.users / res.groups / ir.model.access / ir.rule /
+# ir.actions.server / base.automation / ir.cron / mail.message /
+# res.country / res.region / res.company / ir.ui.menu) and ``admin``
+# (the list/form views + sidebar menus that put a usable management
+# UI in front of those models). Apps that boot the framework should
+# include this in their ``loader.load_and_install`` call:
+#
+#     from pyvelm import BUILTIN_MODULE_ROOTS
+#     loader.load_and_install(
+#         BUILTIN_MODULE_ROOTS + [my_app_root], env,
+#     )
+#
+# ``pyvelm-cron`` prepends these automatically so the CLI sees the
+# framework modules even if the operator only set PYVELM_MODULE_ROOTS
+# to their app's addons.
+BUILTIN_MODULE_ROOTS: list[_Path] = [_Path(__file__).parent / "modules"]
+
+
+__all__ = [
+    "BUILTIN_MODULE_ROOTS",
+    "__version__",
+    "BaseModel",
+    "Boolean",
+    "Char",
+    "Environment",
+    "Field",
+    "Float",
+    "Integer",
+    "Many2many",
+    "Many2one",
+    "One2many",
+    "Registry",
+    "Text",
+    "builders",
+    "depends",
+    "loader",
+    "types",
+]

pyvelm-0.1.0/pyvelm/actions.py

@@ -0,0 +1,90 @@
+"""Server-action execution engine (Stage 6 Slice A).
+
+`ir.actions.server` records represent named, storable pieces of logic
+that can be invoked against a recordset at any time — from the API,
+from automated-action triggers, from cron jobs, or from user-facing
+buttons (future).
+
+Four action_type values are supported:
+
+  write   — write vals_json onto every record in the target recordset.
+  create  — create one new record on model with vals_json.
+  unlink  — delete every record in the target recordset.
+  code    — execute a Python snippet.  Locals: env, records, action.
+            The snippet may call any env/ORM method; write side effects
+            are the caller's responsibility to wrap in a transaction.
+
+Security note: `code` actions execute arbitrary Python.  They must only
+be created by administrators (ACL enforced at the ORM level — Admin gets
+create/write/unlink on ir.actions.server via the install hook).  Do NOT
+expose `code` contents to untrusted input.
+"""
+from __future__ import annotations
+
+import json
+
+from pyvelm import BaseModel, Boolean, Char, Many2one, Text
+
+
+class ServerAction(BaseModel):
+    _name = "ir.actions.server"
+
+    name = Char(required=True)
+    model = Char(required=True)       # target model _name
+    # One of: write / create / unlink / code
+    action_type = Char(required=True)
+    # JSON-encoded dict of field values used by write / create.
+    vals_json = Text()
+    # Python source executed for action_type == "code".
+    code = Text()
+
+    def run(self, records=None) -> None:
+        """Execute this action against *records*.
+
+        `records` should be a recordset of `self.model`.  For
+        `create`-type actions the existing recordset is ignored and a
+        new record is created.  Pass an empty recordset (or None) when
+        the target is the model itself with no pre-selected rows.
+        """
+        self.ensure_one()
+        env = self.env
+        target_model = self.model
+
+        if target_model not in env.registry:
+            raise ValueError(
+                f"ir.actions.server {self.name!r}: model {target_model!r} not in registry"
+            )
+
+        kind = self.action_type
+        if kind not in ("write", "create", "unlink", "code"):
+            raise ValueError(
+                f"ir.actions.server {self.name!r}: unknown action_type {kind!r}"
+            )
+
+        if records is None:
+            records = env[target_model]
+
+        if kind == "write":
+            if not records:
+                return
+            vals = json.loads(self.vals_json or "{}")
+            records.write(vals)
+
+        elif kind == "create":
+            vals = json.loads(self.vals_json or "{}")
+            env[target_model].create(vals)
+
+        elif kind == "unlink":
+            if not records:
+                return
+            records.unlink()
+
+        elif kind == "code":
+            code_src = self.code or ""
+            _globals: dict = {}
+            _locals: dict = {
+                "env": env,
+                "records": records,
+                "action": self,
+            }
+            exec(compile(code_src, f"<action:{self.name}>", "exec"), _globals, _locals)  # noqa: S102

pyvelm-0.1.0/pyvelm/automation.py

@@ -0,0 +1,76 @@
+"""Automated-action trigger engine (Stage 6 Slice B).
+
+`base.automation` records attach a server action to a model-level ORM
+event.  The three supported trigger values are:
+
+  on_create  — fires after every successful create() on the model.
+  on_write   — fires after every successful write() on the model.
+  on_unlink  — fires before every unlink() on the model.
+
+The ORM calls `AutomationEngine.fire(env, model_name, event, records)`
+from within `BaseModel.create / write / unlink`.  The call is a no-op
+if `base.automation` is not in the registry (e.g. during early install).
+
+`base.automation` records are active (active=True) by default.
+Deactivating a rule suppresses it without deleting it.
+"""
+from __future__ import annotations
+
+from pyvelm import BaseModel, Boolean, Char, Many2one
+
+
+# Valid trigger names.
+TRIGGERS = frozenset({"on_create", "on_write", "on_unlink"})
+
+
+class AutomatedAction(BaseModel):
+    _name = "base.automation"
+
+    name = Char(required=True)
+    model = Char(required=True)         # model _name this rule watches
+    trigger = Char(required=True)       # on_create / on_write / on_unlink
+    action_id = Many2one("ir.actions.server", ondelete="CASCADE")
+    active = Boolean(default=True)
+
+
+class AutomationEngine:
+    """Stateless helper — all state lives in the DB via base.automation."""
+
+    @staticmethod
+    def fire(env, model_name: str, event: str, records) -> None:
+        """Run all active automation rules for (model_name, event).
+
+        Failures in individual actions are logged to stderr and do NOT
+        abort the calling ORM operation; automation side effects are
+        best-effort unless the action itself raises inside a transaction
+        that the caller manages.
+        """
+        if "base.automation" not in env.registry:
+            return
+        if env._acl_bypass:
+            # Avoid recursive triggers while installing / migrating.
+            return
+
+        prev = env._acl_bypass
+        env._acl_bypass = True
+        try:
+            rules = env["base.automation"].search([
+                ("model", "=", model_name),
+                ("trigger", "=", event),
+                ("active", "=", True),
+            ])
+            for rule in rules:
+                if not rule.action_id:
+                    continue
+                action = env["ir.actions.server"].browse(rule.action_id.id)
+                try:
+                    action.run(records if event != "on_create" else records)
+                except Exception as exc:  # noqa: BLE001
+                    import sys
+                    print(
+                        f"[automation] {rule.name!r} failed on {model_name}"
+                        f" ({event}): {exc}",
+                        file=sys.stderr,
+                    )
+        finally:
+            env._acl_bypass = prev