schematell 0.1.0__tar.gz

schematell-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anjal Antony
+
+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.

schematell-0.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: schematell
+Version: 0.1.0
+Summary: Understand database structures in plain English without writing SQL.
+Author-email: Anjal <anjalantony1111@gmail.com>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# schematell 🔍
+
+> Understand SQLite database schemas in plain English and audit relational integrity without writing SQL.
+
+`schematell` is a lightweight Python developer tool that inspects SQLite tables, generates narrative summaries of columns and keys, audits orphaned foreign key relationships, and exports Mermaid.js ER diagrams for documentation.
+
+---
+
+## 🚀 Installation
+
+```bash
+git clone [https://github.com/](https://github.com/)<YOUR_GITHUB_USERNAME>/schematell.git
+cd schematell
+pip install -e .

schematell-0.1.0/README.md

@@ -0,0 +1,14 @@
+# schematell 🔍
+
+> Understand SQLite database schemas in plain English and audit relational integrity without writing SQL.
+
+`schematell` is a lightweight Python developer tool that inspects SQLite tables, generates narrative summaries of columns and keys, audits orphaned foreign key relationships, and exports Mermaid.js ER diagrams for documentation.
+
+---
+
+## 🚀 Installation
+
+```bash
+git clone [https://github.com/](https://github.com/)<YOUR_GITHUB_USERNAME>/schematell.git
+cd schematell
+pip install -e .

schematell-0.1.0/pyproject.toml

@@ -0,0 +1,14 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "schematell"
+version = "0.1.0"
+authors = [{ name="Anjal", email="anjalantony1111@gmail.com" }]
+description = "Understand database structures in plain English without writing SQL."
+readme = "README.md"
+requires-python = ">=3.8"
+
+[tool.setuptools]
+py-modules = ["schematell"]

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

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: schematell
+Version: 0.1.0
+Summary: Understand database structures in plain English without writing SQL.
+Author-email: Anjal <anjalantony1111@gmail.com>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# schematell 🔍
+
+> Understand SQLite database schemas in plain English and audit relational integrity without writing SQL.
+
+`schematell` is a lightweight Python developer tool that inspects SQLite tables, generates narrative summaries of columns and keys, audits orphaned foreign key relationships, and exports Mermaid.js ER diagrams for documentation.
+
+---
+
+## 🚀 Installation
+
+```bash
+git clone [https://github.com/](https://github.com/)<YOUR_GITHUB_USERNAME>/schematell.git
+cd schematell
+pip install -e .

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

@@ -0,0 +1,8 @@
+LICENSE
+README.md
+pyproject.toml
+schematell.py
+schematell.egg-info/PKG-INFO
+schematell.egg-info/SOURCES.txt
+schematell.egg-info/dependency_links.txt
+schematell.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+schematell

schematell-0.1.0/schematell.py

@@ -0,0 +1,178 @@
+
+"""
+schematell: Plain-English database introspection, relationship auditing, and ER diagram export.
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List
+
+
+@dataclass
+class ColumnMeta:
+    cid: int
+    name: str
+    data_type: str
+    not_null: bool
+    default_value: Any
+    is_pk: bool
+
+
+@dataclass
+class ForeignKeyMeta:
+    target_table: str
+    from_col: str
+    to_col: str
+
+
+@dataclass
+class TableReport:
+    name: str
+    row_count: int
+    columns: List[ColumnMeta] = field(default_factory=list)
+    foreign_keys: List[ForeignKeyMeta] = field(default_factory=list)
+    orphaned_records: Dict[str, int] = field(default_factory=dict)
+    warnings: List[str] = field(default_factory=list)
+
+    @property
+    def primary_keys(self) -> List[str]:
+        return [c.name for c in self.columns if c.is_pk]
+
+
+class Database:
+    """Read-only schema introspector and relational auditor for SQLite."""
+
+    def __init__(self, db_path: str | Path):
+        self.db_path = Path(db_path)
+        if not self.db_path.exists():
+            raise FileNotFoundError(f"Database file not found: {self.db_path}")
+
+        # Connect in strict read-only mode to prevent accidental writes
+        uri = f"file:{self.db_path.resolve()}?mode=ro"
+        self.conn = sqlite3.connect(uri, uri=True)
+        self.cursor = self.conn.cursor()
+
+    def _get_tables(self) -> List[str]:
+        query = (
+            "SELECT name FROM sqlite_master "
+            "WHERE type='table' AND name NOT LIKE 'sqlite_%' "
+            "ORDER BY name;"
+        )
+        self.cursor.execute(query)
+        return [row[0] for row in self.cursor.fetchall()]
+
+    def inspect_table(self, table_name: str) -> TableReport:
+        # Row count
+        self.cursor.execute(f'SELECT COUNT(*) FROM "{table_name}"')
+        row_count = self.cursor.fetchone()[0]
+        report = TableReport(name=table_name, row_count=row_count)
+
+        # Column metadata
+        self.cursor.execute(f'PRAGMA table_info("{table_name}")')
+        for col in self.cursor.fetchall():
+            report.columns.append(
+                ColumnMeta(
+                    cid=col[0],
+                    name=col[1],
+                    data_type=col[2] or "ANY",
+                    not_null=bool(col[3]),
+                    default_value=col[4],
+                    is_pk=bool(col[5]),
+                )
+            )
+
+        # Foreign Key mappings + Orphan Record Audit
+        self.cursor.execute(f'PRAGMA foreign_key_list("{table_name}")')
+        for fk in self.cursor.fetchall():
+            target_t, from_c, to_c = fk[2], fk[3], fk[4]
+            report.foreign_keys.append(
+                ForeignKeyMeta(target_table=target_t, from_col=from_c, to_col=to_c)
+            )
+
+            audit_query = f"""
+                SELECT COUNT(*) FROM "{table_name}"
+                WHERE "{from_c}" IS NOT NULL 
+                  AND "{from_c}" NOT IN (SELECT "{to_c}" FROM "{target_t}")
+            """
+            try:
+                self.cursor.execute(audit_query)
+                orphans = self.cursor.fetchone()[0]
+                if orphans > 0:
+                    report.orphaned_records[from_c] = orphans
+                    report.warnings.append(
+                        f"Integrity Alert: {orphans} orphaned row(s) in '{from_c}' reference missing records in '{target_t}.{to_c}'."
+                    )
+            except sqlite3.OperationalError:
+                report.warnings.append(f"Broken Reference: Target table '{target_t}' is inaccessible.")
+
+        if not report.primary_keys:
+            report.warnings.append("Design Notice: No primary key defined.")
+        if report.row_count == 0:
+            report.warnings.append("Design Notice: Table contains 0 records.")
+
+        return report
+
+    def inspect(self) -> None:
+        """Prints formatted plain-English narrative report."""
+        tables = self._get_tables()
+        size_kb = os.path.getsize(self.db_path) / 1024
+
+        print("\n" + "=" * 60)
+        print(f"SCHEMATELL DATABASE REPORT: {self.db_path.name} ({size_kb:.1f} KB)")
+        print(f"Identified {len(tables)} active table(s)")
+        print("=" * 60)
+
+        for table in tables:
+            rep = self.inspect_table(table)
+            print(f"\n📦 Table: '{rep.name}' (Records: {rep.row_count:,})")
+            
+            pk_desc = ", ".join(rep.primary_keys) if rep.primary_keys else "None"
+            print(f" • Primary Key: {pk_desc}")
+            
+            col_list = [f"{c.name} ({c.data_type})" for c in rep.columns]
+            print(f" • Attributes: {', '.join(col_list)}")
+
+            for fk in rep.foreign_keys:
+                print(f" • Relationship: Points to '{fk.target_table}' via `{fk.from_col}` → `{fk.to_col}`")
+
+            for w in rep.warnings:
+                print(f" ⚠️ {w}")
+
+        print("\n" + "=" * 60 + "\n")
+
+    def export_mermaid(self, output_file: str = "schema.md") -> None:
+        """Exports GitHub-ready Mermaid ER diagram."""
+        lines = ["```mermaid", "erDiagram"]
+        tables = self._get_tables()
+
+        for t in tables:
+            rep = self.inspect_table(t)
+            lines.append(f" {rep.name} {{")
+            for col in rep.columns:
+                pk_tag = "PK" if col.is_pk else ""
+                lines.append(f" {col.data_type} {col.name} {pk_tag}".strip())
+            lines.append(" }")
+
+        for t in tables:
+            rep = self.inspect_table(t)
+            for fk in rep.foreign_keys:
+                lines.append(f' {fk.target_table} ||--o{{ {rep.name} : "{fk.from_col}"')
+
+        lines.append("```\n")
+
+        with open(output_file, "w", encoding="utf-8") as f:
+            f.write("\n".join(lines))
+        print(f"Mermaid ER diagram saved to {output_file}")
+
+    def close(self):
+        self.conn.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()

schematell-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+