django-orm-lens 1.0.0__tar.gz

django_orm_lens-1.0.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: django-orm-lens
+Version: 1.0.0
+Summary: Static analysis + MCP server for Django models. Sidebar tree, ER diagrams, and JSON output for terminals and AI coding agents.
+Author: frowningdev
+License: MIT
+Project-URL: Homepage, https://github.com/FROWNINGdev/django-orm-lens
+Project-URL: Repository, https://github.com/FROWNINGdev/django-orm-lens
+Project-URL: Bug Tracker, https://github.com/FROWNINGdev/django-orm-lens/issues
+Project-URL: Changelog, https://github.com/FROWNINGdev/django-orm-lens/blob/main/CHANGELOG.md
+Project-URL: VS Code Marketplace, https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens
+Keywords: django,orm,models,er-diagram,mermaid,mcp,ai-agents,cursor,aider,code-analysis,static-analysis
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.0
+Classifier: Framework :: Django :: 4.1
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+
+# django-orm-lens
+
+**Static analysis + MCP server for Django models.** Terminal- and AI-agent-friendly.
+
+Ships with a zero-dependency parser, a JSON/Markdown/table CLI, and an optional
+MCP (Model Context Protocol) server so any AI coding agent — Cursor, Aider,
+Continue, and any other MCP client — can navigate your Django schema without
+importing Django or spinning up your app.
+
+Companion to the [Django ORM Lens VS Code
+extension](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens).
+
+---
+
+## Install
+
+```bash
+# Core CLI (zero third-party deps)
+pip install django-orm-lens
+
+# With the MCP server (adds the `mcp` package)
+pip install "django-orm-lens[mcp]"
+```
+
+Requires Python **3.9+**. Works on Linux, macOS, and Windows.
+
+---
+
+## CLI usage
+
+```bash
+# Scan a Django project for models (JSON, Markdown, or table)
+django-orm-lens scan -f json
+django-orm-lens scan -f markdown
+django-orm-lens scan -f table
+
+# Describe one model
+django-orm-lens describe blog.Post
+django-orm-lens describe Post -f json
+
+# Compact hover card (great for pipeing into your editor)
+django-orm-lens hover blog.Post
+
+# Flat list — pipes into fzf, grep, etc.
+django-orm-lens list | fzf
+
+# Emit a Mermaid ER diagram
+django-orm-lens er > schema.mmd
+django-orm-lens er -o schema.mmd
+```
+
+Every command accepts `--path <dir>` and repeatable `--exclude <glob>`. Defaults
+skip `migrations/`, `venv/`, `.venv/`, `env/`, and `node_modules/`.
+
+---
+
+## MCP server — for AI coding agents
+
+The MCP server exposes five read-only tools that any MCP-compatible agent can
+call while it edits your Django project:
+
+| Tool | Purpose |
+| --- | --- |
+| `list_apps` | Every Django app in the workspace with model counts |
+| `list_models` | Flat `app.Model` list, optional app filter |
+| `describe_model` | Full field / relation / Meta detail for one model |
+| `find_relations` | Inbound + outbound relations for one model |
+| `er_diagram` | Mermaid `erDiagram` string for the whole workspace |
+
+### Start the server manually
+
+```bash
+django-orm-lens-mcp     # dedicated entry point
+# or
+django-orm-lens mcp     # subcommand
+```
+
+By default the server scans the current working directory. Override with
+`DJANGO_ORM_LENS_ROOT=/abs/path/to/project`.
+
+### Register it with an agent
+
+**Cursor** — add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "django-orm-lens": {
+      "command": "django-orm-lens-mcp",
+      "env": { "DJANGO_ORM_LENS_ROOT": "/abs/path/to/your/project" }
+    }
+  }
+}
+```
+
+**Aider / Continue.dev / Zed / any MCP client** — same shape, the tool is
+generic. Point `command` at the installed `django-orm-lens-mcp` binary and set
+the workspace root via env.
+
+---
+
+## Why?
+
+Django's ORM is Python, and Python is dynamic. AI agents that only see
+`models.py` as raw text miss:
+
+* which fields belong to which model;
+* the direction and cardinality of every relation;
+* what `Meta.ordering`, `unique_together`, and `constraints` actually contain;
+* which app owns which model when the project uses split `models/` packages.
+
+`django-orm-lens` gives them a **static, deterministic, JSON view** of the
+schema — no Django boot, no database, no side effects. And you get a nice CLI
+for humans too.
+
+---
+
+## Programmatic API
+
+```python
+from django_orm_lens import scan_workspace
+
+index = scan_workspace(".")
+for app in index.apps:
+    for model in app.models:
+        print(f"{app.name}.{model.name} — {len(model.fields)} fields")
+
+# The full parsed tree serialises to the same JSON schema the VS Code
+# extension emits, so tools can share it interchangeably.
+import json
+json.dumps(index.to_dict(), indent=2)
+```
+
+---
+
+## Links
+
+* Repo: <https://github.com/FROWNINGdev/django-orm-lens>
+* Issues: <https://github.com/FROWNINGdev/django-orm-lens/issues>
+* Changelog: <https://github.com/FROWNINGdev/django-orm-lens/blob/main/CHANGELOG.md>
+* VS Code extension: <https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens>
+
+MIT licensed.

django_orm_lens-1.0.0/README.md

@@ -0,0 +1,143 @@
+# django-orm-lens
+
+**Static analysis + MCP server for Django models.** Terminal- and AI-agent-friendly.
+
+Ships with a zero-dependency parser, a JSON/Markdown/table CLI, and an optional
+MCP (Model Context Protocol) server so any AI coding agent — Cursor, Aider,
+Continue, and any other MCP client — can navigate your Django schema without
+importing Django or spinning up your app.
+
+Companion to the [Django ORM Lens VS Code
+extension](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens).
+
+---
+
+## Install
+
+```bash
+# Core CLI (zero third-party deps)
+pip install django-orm-lens
+
+# With the MCP server (adds the `mcp` package)
+pip install "django-orm-lens[mcp]"
+```
+
+Requires Python **3.9+**. Works on Linux, macOS, and Windows.
+
+---
+
+## CLI usage
+
+```bash
+# Scan a Django project for models (JSON, Markdown, or table)
+django-orm-lens scan -f json
+django-orm-lens scan -f markdown
+django-orm-lens scan -f table
+
+# Describe one model
+django-orm-lens describe blog.Post
+django-orm-lens describe Post -f json
+
+# Compact hover card (great for pipeing into your editor)
+django-orm-lens hover blog.Post
+
+# Flat list — pipes into fzf, grep, etc.
+django-orm-lens list | fzf
+
+# Emit a Mermaid ER diagram
+django-orm-lens er > schema.mmd
+django-orm-lens er -o schema.mmd
+```
+
+Every command accepts `--path <dir>` and repeatable `--exclude <glob>`. Defaults
+skip `migrations/`, `venv/`, `.venv/`, `env/`, and `node_modules/`.
+
+---
+
+## MCP server — for AI coding agents
+
+The MCP server exposes five read-only tools that any MCP-compatible agent can
+call while it edits your Django project:
+
+| Tool | Purpose |
+| --- | --- |
+| `list_apps` | Every Django app in the workspace with model counts |
+| `list_models` | Flat `app.Model` list, optional app filter |
+| `describe_model` | Full field / relation / Meta detail for one model |
+| `find_relations` | Inbound + outbound relations for one model |
+| `er_diagram` | Mermaid `erDiagram` string for the whole workspace |
+
+### Start the server manually
+
+```bash
+django-orm-lens-mcp     # dedicated entry point
+# or
+django-orm-lens mcp     # subcommand
+```
+
+By default the server scans the current working directory. Override with
+`DJANGO_ORM_LENS_ROOT=/abs/path/to/project`.
+
+### Register it with an agent
+
+**Cursor** — add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "django-orm-lens": {
+      "command": "django-orm-lens-mcp",
+      "env": { "DJANGO_ORM_LENS_ROOT": "/abs/path/to/your/project" }
+    }
+  }
+}
+```
+
+**Aider / Continue.dev / Zed / any MCP client** — same shape, the tool is
+generic. Point `command` at the installed `django-orm-lens-mcp` binary and set
+the workspace root via env.
+
+---
+
+## Why?
+
+Django's ORM is Python, and Python is dynamic. AI agents that only see
+`models.py` as raw text miss:
+
+* which fields belong to which model;
+* the direction and cardinality of every relation;
+* what `Meta.ordering`, `unique_together`, and `constraints` actually contain;
+* which app owns which model when the project uses split `models/` packages.
+
+`django-orm-lens` gives them a **static, deterministic, JSON view** of the
+schema — no Django boot, no database, no side effects. And you get a nice CLI
+for humans too.
+
+---
+
+## Programmatic API
+
+```python
+from django_orm_lens import scan_workspace
+
+index = scan_workspace(".")
+for app in index.apps:
+    for model in app.models:
+        print(f"{app.name}.{model.name} — {len(model.fields)} fields")
+
+# The full parsed tree serialises to the same JSON schema the VS Code
+# extension emits, so tools can share it interchangeably.
+import json
+json.dumps(index.to_dict(), indent=2)
+```
+
+---
+
+## Links
+
+* Repo: <https://github.com/FROWNINGdev/django-orm-lens>
+* Issues: <https://github.com/FROWNINGdev/django-orm-lens/issues>
+* Changelog: <https://github.com/FROWNINGdev/django-orm-lens/blob/main/CHANGELOG.md>
+* VS Code extension: <https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens>
+
+MIT licensed.

django_orm_lens-1.0.0/django_orm_lens/__init__.py

@@ -0,0 +1,20 @@
+"""Django ORM Lens — sidebar tree, ER diagrams, and JSON for Django models.
+
+Terminal / editor-agnostic parser for Django models.py files.
+Ships a CLI and an optional MCP server for AI coding agents.
+"""
+
+__version__ = "1.0.0"
+
+from .models import ParsedApp, ParsedField, ParsedModel, WorkspaceIndex
+from .parser import parse_models_file, scan_workspace
+
+__all__ = [
+    "ParsedApp",
+    "ParsedField",
+    "ParsedModel",
+    "WorkspaceIndex",
+    "parse_models_file",
+    "scan_workspace",
+    "__version__",
+]

django_orm_lens-1.0.0/django_orm_lens/cli.py

@@ -0,0 +1,238 @@
+"""Command-line entry point for ``django-orm-lens``.
+
+Zero-dep argparse CLI. Commands mirror what the VS Code extension does:
+
+  django-orm-lens scan       — walk workspace, list every model
+  django-orm-lens describe   — one model in detail
+  django-orm-lens er         — Mermaid ER diagram (stdout or file)
+  django-orm-lens hover      — compact hover card for one model
+  django-orm-lens list       — flat list ``app.Model`` for shell piping
+  django-orm-lens mcp        — start the MCP stdio server (extras required)
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional, Sequence
+
+from . import __version__
+from .formatters import format_hover, format_index, format_model
+from .models import ParsedModel, WorkspaceIndex
+from .parser import DEFAULT_EXCLUDES, scan_workspace
+
+
+def _add_scan_flags(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "--path",
+        "-p",
+        default=".",
+        help="Workspace root to scan (default: current directory)",
+    )
+    p.add_argument(
+        "--exclude",
+        "-x",
+        action="append",
+        default=None,
+        help="Glob to exclude, repeatable (default: migrations/, venv/, node_modules/)",
+    )
+
+
+def _resolve_excludes(cli_excludes: Optional[Sequence[str]]) -> Sequence[str]:
+    return tuple(cli_excludes) if cli_excludes else DEFAULT_EXCLUDES
+
+
+def _find_model(index: WorkspaceIndex, ref: str) -> Optional[ParsedModel]:
+    if "." in ref:
+        app_name, model_name = ref.split(".", 1)
+        for app in index.apps:
+            if app.name == app_name:
+                for m in app.models:
+                    if m.name == model_name:
+                        return m
+    for app in index.apps:
+        for m in app.models:
+            if m.name == ref:
+                return m
+    return None
+
+
+def _cmd_scan(args: argparse.Namespace) -> int:
+    idx = scan_workspace(args.path, _resolve_excludes(args.exclude))
+    print(format_index(idx, args.format))
+    return 0
+
+
+def _cmd_describe(args: argparse.Namespace) -> int:
+    idx = scan_workspace(args.path, _resolve_excludes(args.exclude))
+    model = _find_model(idx, args.model)
+    if model is None:
+        print(f"error: model {args.model!r} not found", file=sys.stderr)
+        return 2
+    print(format_model(model, args.format))
+    return 0
+
+
+def _cmd_hover(args: argparse.Namespace) -> int:
+    idx = scan_workspace(args.path, _resolve_excludes(args.exclude))
+    model = _find_model(idx, args.model)
+    if model is None:
+        print(f"error: model {args.model!r} not found", file=sys.stderr)
+        return 2
+    print(format_hover(model))
+    return 0
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    idx = scan_workspace(args.path, _resolve_excludes(args.exclude))
+    for app in idx.apps:
+        for m in app.models:
+            print(f"{app.name}.{m.name}")
+    return 0
+
+
+def _cmd_er(args: argparse.Namespace) -> int:
+    idx = scan_workspace(args.path, _resolve_excludes(args.exclude))
+    mermaid = _build_mermaid(idx)
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as fh:
+            fh.write(mermaid)
+        print(f"Wrote {args.output}", file=sys.stderr)
+    else:
+        print(mermaid)
+    return 0
+
+
+def _build_mermaid(index: WorkspaceIndex) -> str:
+    lines: List[str] = ["erDiagram"]
+    model_names = {m.name for app in index.apps for m in app.models}
+
+    def safe(s: str) -> str:
+        return "".join(ch if (ch.isalnum() or ch == "_") else "_" for ch in s)
+
+    for app in index.apps:
+        for model in app.models:
+            lines.append(f"  {safe(model.name)} {{")
+            for f in model.fields:
+                if f.is_relation:
+                    continue
+                type_safe = "".join(ch for ch in f.type if ch.isalnum())
+                name_safe = safe(f.name)
+                lines.append(f"    {type_safe} {name_safe}")
+            lines.append("  }")
+
+    for app in index.apps:
+        for model in app.models:
+            for f in model.fields:
+                if not f.is_relation or not f.related_model:
+                    continue
+                target = (
+                    model.name
+                    if f.related_model == "self"
+                    else f.related_model.split(".")[-1]
+                )
+                if target not in model_names:
+                    continue
+                if f.relation_kind == "ManyToManyField":
+                    arrow = "}o--o{"
+                elif f.relation_kind == "OneToOneField":
+                    arrow = "||--||"
+                else:
+                    arrow = "}o--||"
+                lines.append(
+                    f'  {safe(model.name)} {arrow} {safe(target)} : "{f.name}"'
+                )
+    return "\n".join(lines)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="django-orm-lens",
+        description="Static analysis for Django models. Terminal + AI agent friendly.",
+    )
+    p.add_argument(
+        "--version", action="version", version=f"django-orm-lens {__version__}"
+    )
+    sub = p.add_subparsers(dest="command", required=True)
+
+    scan = sub.add_parser("scan", help="Scan a workspace for Django models")
+    _add_scan_flags(scan)
+    scan.add_argument(
+        "--format", "-f", choices=("json", "markdown", "table"), default="json"
+    )
+    scan.set_defaults(func=_cmd_scan)
+
+    describe = sub.add_parser(
+        "describe", help="Describe a single model (app.Model or Model)"
+    )
+    _add_scan_flags(describe)
+    describe.add_argument("model", help="Model reference, e.g. blog.Post or Post")
+    describe.add_argument(
+        "--format", "-f", choices=("json", "markdown", "table"), default="markdown"
+    )
+    describe.set_defaults(func=_cmd_describe)
+
+    hover = sub.add_parser("hover", help="Compact hover-card markdown for a model")
+    _add_scan_flags(hover)
+    hover.add_argument("model", help="Model reference, e.g. blog.Post or Post")
+    hover.set_defaults(func=_cmd_hover)
+
+    lst = sub.add_parser("list", help="Flat list of app.Model — pipes well into shell")
+    _add_scan_flags(lst)
+    lst.set_defaults(func=_cmd_list)
+
+    er = sub.add_parser("er", help="Emit a Mermaid ER diagram (stdout or file)")
+    _add_scan_flags(er)
+    er.add_argument(
+        "--output", "-o", default=None, help="Write diagram to file instead of stdout"
+    )
+    er.set_defaults(func=_cmd_er)
+
+    mcp = sub.add_parser(
+        "mcp",
+        help="Run the MCP stdio server (requires 'pip install django-orm-lens[mcp]')",
+    )
+    mcp.set_defaults(func=_cmd_mcp)
+
+    return p
+
+
+def _cmd_mcp(_args: argparse.Namespace) -> int:
+    try:
+        from . import mcp_server
+    except ImportError as e:
+        print(
+            "error: MCP server dependencies not installed.\n"
+            "install with: pip install 'django-orm-lens[mcp]'\n"
+            f"({e})",
+            file=sys.stderr,
+        )
+        return 3
+    return mcp_server.main()
+
+
+def _force_utf8_stdio() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            try:
+                reconfigure(encoding="utf-8", errors="replace")
+            except (OSError, ValueError):
+                pass
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    _force_utf8_stdio()
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except KeyboardInterrupt:
+        return 130
+    except Exception as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())