gristcode 0.1.0__py3-none-any.whl

gristcode/__init__.py

@@ -0,0 +1,3 @@
+"""Render a Grist document as readable Python source, offline, from the .grist file."""
+
+__version__ = "0.1.0"

gristcode/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

gristcode/cli.py

@@ -0,0 +1,80 @@
+"""Command line entry point."""
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .doc import DocumentError, read_tables
+from .render import render
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="gristcode",
+        description="Render a Grist document as readable Python source, offline, "
+                    "from its .grist file. The document is only ever read.",
+    )
+    parser.add_argument("document", help="path to a .grist file")
+    parser.add_argument(
+        "-t", "--table", action="append", default=[], metavar="NAME",
+        help="only this table; repeat the option for several tables",
+    )
+    parser.add_argument(
+        "--include-summary", action="store_true",
+        help="also render the summary tables Grist builds from your own tables",
+    )
+    parser.add_argument(
+        "--include-hidden", action="store_true",
+        help="also render the helper columns Grist maintains for itself",
+    )
+    parser.add_argument("--no-header", action="store_true", help="drop the two header comments")
+    parser.add_argument("--json", action="store_true", help="print the schema as JSON instead")
+    parser.add_argument("--version", action="version", version="gristcode " + __version__)
+    return parser
+
+
+def select(tables, wanted, include_summary):
+    if wanted:
+        names = set(wanted)
+        return [t for t in tables if t.table_id in names]
+    return [t for t in tables if include_summary or not t.is_summary]
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    try:
+        tables = read_tables(args.document)
+    except DocumentError as exc:
+        sys.stderr.write("gristcode: %s\n" % exc)
+        return 2
+
+    chosen = select(tables, args.table, args.include_summary)
+    if args.table:
+        missing = sorted(set(args.table) - {t.table_id for t in tables})
+        if missing:
+            sys.stderr.write("gristcode: no such table: %s\n" % ", ".join(missing))
+            return 2
+
+    if args.json:
+        payload = []
+        for table in chosen:
+            entry = table.as_dict()
+            if not args.include_hidden:
+                entry["columns"] = [
+                    c.as_dict() for c in table.columns if not c.is_hidden
+                ]
+            payload.append(entry)
+        sys.stdout.write(json.dumps(payload, indent=2, sort_keys=True) + "\n")
+        return 0
+
+    sys.stdout.write(render(
+        chosen,
+        include_hidden=args.include_hidden,
+        header=not args.no_header,
+    ))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gristcode/doc.py

@@ -0,0 +1,153 @@
+"""Read the schema of a Grist document out of its SQLite file.
+
+A .grist document is a SQLite database. The document's own structure lives in two metadata tables,
+`_grist_Tables` and `_grist_Tables_column`, whose shape is defined upstream in
+sandbox/grist/schema.py. Only those two tables are read here, and nothing is ever written.
+"""
+
+import os
+import sqlite3
+from urllib.parse import quote
+
+TABLES_TABLE = "_grist_Tables"
+COLUMNS_TABLE = "_grist_Tables_column"
+
+
+class DocumentError(Exception):
+    """The file is not a readable Grist document."""
+
+
+class Column:
+    """One column of one user table."""
+
+    def __init__(self, col_id, col_type, is_formula, formula, label="", description="",
+                 parent_pos=0.0, reverse_col_id=None):
+        self.col_id = col_id
+        self.col_type = col_type or "Any"
+        self.is_formula = bool(is_formula)
+        self.formula = formula or ""
+        self.label = label or ""
+        self.description = description or ""
+        self.parent_pos = parent_pos or 0.0
+        self.reverse_col_id = reverse_col_id or None
+
+    @property
+    def is_hidden(self):
+        """True for the helper columns Grist maintains for itself, which no user typed."""
+        return (
+            self.col_id == "manualSort"
+            or self.col_id.startswith("gristHelper_")
+            or self.col_id.startswith("#")
+        )
+
+    def as_dict(self):
+        return {
+            "colId": self.col_id,
+            "type": self.col_type,
+            "isFormula": self.is_formula,
+            "formula": self.formula,
+            "label": self.label,
+            "description": self.description,
+            "reverseColId": self.reverse_col_id,
+        }
+
+
+class Table:
+    """One user table of the document."""
+
+    def __init__(self, table_id, columns, summary_source=None):
+        self.table_id = table_id
+        self.columns = columns
+        self.summary_source = summary_source
+
+    @property
+    def is_summary(self):
+        return self.summary_source is not None
+
+    def as_dict(self):
+        return {
+            "tableId": self.table_id,
+            "summarySourceTable": self.summary_source,
+            "columns": [c.as_dict() for c in self.columns],
+        }
+
+
+def _column_names(conn, table_name):
+    rows = conn.execute("PRAGMA table_info(%s)" % table_name).fetchall()
+    return [row[1] for row in rows]
+
+
+def _require_metadata(conn):
+    names = {
+        row[0]
+        for row in conn.execute("SELECT name FROM sqlite_master WHERE type = 'table'")
+    }
+    missing = [t for t in (TABLES_TABLE, COLUMNS_TABLE) if t not in names]
+    if missing:
+        raise DocumentError(
+            "this SQLite file carries no Grist document metadata (missing %s)"
+            % ", ".join(missing)
+        )
+
+
+def _select(conn, table_name, wanted):
+    """Select the wanted columns, tolerating the ones an older document does not carry."""
+    present = _column_names(conn, table_name)
+    used = [name for name in wanted if name in present]
+    rows = conn.execute("SELECT %s FROM %s" % (", ".join(used), table_name)).fetchall()
+    return [dict(zip(used, row)) for row in rows]
+
+
+def read_tables(path):
+    """Return the user tables of the document at `path`, ordered by table id.
+
+    Columns are ordered the way the document orders them, data columns before formula columns.
+    """
+    # The path is percent encoded before it goes into the URI, so that a name holding `?` or `#`
+    # cannot end the query string early and drop the read only mode.
+    uri = "file:%s?mode=ro" % quote(os.path.abspath(path))
+    try:
+        conn = sqlite3.connect(uri, uri=True)
+    except sqlite3.Error as exc:
+        raise DocumentError("cannot open %s: %s" % (path, exc))
+    try:
+        try:
+            _require_metadata(conn)
+            table_rows = _select(conn, TABLES_TABLE, ["id", "tableId", "summarySourceTable"])
+            column_rows = _select(conn, COLUMNS_TABLE, [
+                "id", "parentId", "parentPos", "colId", "type", "isFormula", "formula",
+                "label", "description", "reverseCol",
+            ])
+        except sqlite3.DatabaseError as exc:
+            raise DocumentError("cannot read %s: %s" % (path, exc))
+    finally:
+        conn.close()
+
+    table_id_by_ref = {row["id"]: row["tableId"] for row in table_rows}
+    col_id_by_ref = {row["id"]: row.get("colId") for row in column_rows}
+
+    by_parent = {}
+    for row in column_rows:
+        column = Column(
+            col_id=row.get("colId") or "",
+            col_type=row.get("type"),
+            is_formula=row.get("isFormula"),
+            formula=row.get("formula"),
+            label=row.get("label"),
+            description=row.get("description"),
+            parent_pos=row.get("parentPos"),
+            reverse_col_id=col_id_by_ref.get(row.get("reverseCol")),
+        )
+        by_parent.setdefault(row.get("parentId"), []).append(column)
+
+    tables = []
+    for row in table_rows:
+        columns = by_parent.get(row["id"], [])
+        columns.sort(key=lambda c: (c.is_formula, c.parent_pos, c.col_id))
+        tables.append(Table(
+            table_id=row["tableId"],
+            columns=columns,
+            summary_source=table_id_by_ref.get(row.get("summarySourceTable")),
+        ))
+    tables.sort(key=lambda t: t.table_id)
+    return tables

gristcode/render.py

@@ -0,0 +1,80 @@
+"""Turn the tables of a document into Python source text.
+
+The shape follows the class-per-table rendering the Grist sandbox uses (upstream
+sandbox/grist/gencode.py). Formula bodies are printed exactly as the document stores them, which
+is how they were typed; the sandbox rewrites them before running them, and that rewriting is not
+done here.
+"""
+
+INDENT = "  "
+
+HEADER = (
+    "# Rendered by gristcode. Formula bodies are shown exactly as stored in the document,\n"
+    "# so this text is meant to be read and compared, not executed.\n"
+)
+
+
+def grist_type(col_type, reverse_col_id=None):
+    """Return the Grist type expression for a column type string, e.g. `grist.Reference('People')`."""
+    head, _, tail = (col_type or "").partition(":")
+    name = head.strip() or "Any"
+    if name == "Ref":
+        name = "Reference"
+    elif name == "RefList":
+        name = "ReferenceList"
+    args = []
+    tail = tail.strip().replace("'", "\\'")
+    if tail:
+        args.append("'%s'" % tail)
+    if reverse_col_id and name in ("Reference", "ReferenceList"):
+        args.append("reverse_of=%r" % reverse_col_id)
+    return "grist.%s(%s)" % (name, ", ".join(args))
+
+
+def _block(text, indent):
+    """Indent a formula body, giving `pass` when the document holds no text at all."""
+    lines = (text or "").replace("\r\n", "\n").replace("\r", "\n").split("\n")
+    while lines and not lines[-1].strip():
+        lines.pop()
+    if not lines:
+        return [indent + "pass"]
+    return [(indent + line).rstrip() for line in lines]
+
+
+def render_column(column, indent=INDENT):
+    """Return the lines rendering one column."""
+    type_expr = grist_type(column.col_type, column.reverse_col_id)
+    if column.is_formula:
+        lines = [""]
+        if column.col_type != "Any":
+            lines.append("%s@grist.formulaType(%s)" % (indent, type_expr))
+        lines.append("%sdef %s(rec, table):" % (indent, column.col_id))
+        lines.extend(_block(column.formula, indent + INDENT))
+        return lines
+    lines = []
+    if column.formula:
+        lines.append("%s# trigger formula:" % indent)
+        lines.extend("%s#   %s" % (indent, line) for line in _block(column.formula, ""))
+    lines.append("%s%s = %s" % (indent, column.col_id, type_expr))
+    return lines
+
+
+def render_table(table, include_hidden=False):
+    """Return the lines rendering one table as a class."""
+    lines = ["@grist.UserTable", "class %s:" % table.table_id]
+    if table.is_summary:
+        lines.append("%s_summarySourceTable = %r" % (INDENT, table.summary_source))
+    columns = [c for c in table.columns if include_hidden or not c.is_hidden]
+    for column in columns:
+        lines.extend(render_column(column))
+    if len(lines) == 2:
+        lines.append(INDENT + "pass")
+    return lines
+
+
+def render(tables, include_hidden=False, header=True):
+    """Return the whole document as one block of Python source text."""
+    parts = [HEADER] if header else []
+    for table in tables:
+        parts.append("\n".join(render_table(table, include_hidden=include_hidden)) + "\n")
+    return "\n\n".join(parts)

gristcode-0.1.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: gristcode
+Version: 0.1.0
+Summary: Render a Grist document as readable Python source, offline, straight from the .grist file. Standard library only.
+Author: Younes Z.
+License: MIT
+Project-URL: Homepage, https://github.com/Rezarys/gristcode
+Project-URL: Issues, https://github.com/Rezarys/gristcode/issues
+Keywords: grist,spreadsheet,schema,formulas,sqlite,code view,documentation,self hosted
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# gristcode
+
+```
+pip install gristcode
+```
+
+Not affiliated with Grist Labs. "Grist" is used here only to say which file this tool reads.
+
+Print a Grist document as readable Python source, offline, straight from the `.grist` file, so you can read it in your editor, diff it, and commit it.
+
+Grist already shows a rendering of your document as Python in its Code view panel, but there is no way to get that text out of the browser other than selecting the page, pasting it somewhere, and deleting everything that came along with it. `gristcode` gives you the same shape of text on standard output, from the file, with nothing to trim.
+
+## Use
+
+```
+gristcode mydoc.grist
+gristcode mydoc.grist --table People --table Orders
+gristcode mydoc.grist --json
+```
+
+A `.grist` file is what the Download button gives you in the document menu, and it is also the file a self-hosted instance keeps on disk. The document is opened read only and is never written to.
+
+Output on a small document with two tables:
+
+```
+# Rendered by gristcode. Formula bodies are shown exactly as stored in the document,
+# so this text is meant to be read and compared, not executed.
+
+
+@grist.UserTable
+class Orders:
+  Customer = grist.Reference('People')
+  Amount = grist.Numeric()
+  # trigger formula:
+  #   NOW()
+  Placed = grist.DateTime('UTC')
+
+
+@grist.UserTable
+class People:
+  Name = grist.Text()
+  Age = grist.Int()
+
+  @grist.formulaType(grist.Text())
+  def Greeting(rec, table):
+    return "Hi " + $Name
+```
+
+## Options
+
+- `-t NAME`, `--table NAME`: render only this table, and repeat the option for several tables. Naming a summary table explicitly works too.
+- `--include-summary`: also render the summary tables Grist builds from your own tables. They are left out by default.
+- `--include-hidden`: also render the helper columns Grist maintains for itself. The rule used here is that a column is a helper when its identifier is `manualSort`, or starts with `gristHelper_`, or starts with `#`.
+- `--no-header`: drop the two header comment lines, which is handy when the output goes into version control.
+- `--json`: print the schema as JSON instead of Python, with one entry per table and the column identifier, type, formula, label and description of each column.
+- `--version`: print the version and exit.
+
+Exit code is 0 on success and 2 when the file cannot be read as a Grist document or when a table named with `--table` does not exist.
+
+## What this is not
+
+The Code view panel inside Grist shows formula bodies **after** the sandbox has rewritten them, which is where `$field` becomes `rec.field` and a `return` gets inserted. `gristcode` does not do that rewriting: it prints each formula exactly as the document stores it, which is how you typed it. The output is therefore made to be read and compared, not executed, and the sample above shows `$Name` for that reason.
+
+Only the two metadata tables `_grist_Tables` and `_grist_Tables_column` are read. Your data rows, your attachments and your access rules are never opened and never printed.
+
+## Honest limits
+
+This tool has never been run against a real Grist document. It is tested against small SQLite files written by its own test suite, shaped after the document metadata schema published in the Grist source tree. If you run it on a real document and something comes out wrong, please open an issue and paste what you got.
+
+The shape of the output follows the schema as of Grist schema version 46. A document saved by a much older or much newer version may carry columns this tool does not know about, and those are ignored rather than guessed at.
+
+## Install from source
+
+```
+git clone https://github.com/Rezarys/gristcode
+pip install ./gristcode
+```
+
+Python 3.9 or newer. No dependencies outside the standard library.
+
+Tests, once the package is installed:
+
+```
+python -m unittest discover -s tests -t tests
+```
+
+## Background
+
+Built after a request on the Grist issue tracker for an easier way to get the document as code out of the Code view panel: https://github.com/gristlabs/grist-core/issues/2574
+
+Built with AI assistance, reviewed and tested by me.
+
+## License
+
+MIT. Younes Z.

gristcode-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+gristcode/__init__.py,sha256=jm3AOHCwZdG7rMA_txwXmyvUe0wvrY2GKpTG5tvs5bw,111
+gristcode/__main__.py,sha256=4JMK66Wj4uLZTKbF-sT3LAxOsr6buig77PmOkJCRRxw,83
+gristcode/cli.py,sha256=Z41JB2q7mGq8A5upZka-rSZEdiI2Iy06ji5N89h7pxs,2593
+gristcode/doc.py,sha256=_b8ZYGH6LqFdbjZYbc4dxlP8lBYtyG51b9KLlArj9T4,5307
+gristcode/render.py,sha256=aavsbAL8t-aYb5xtGWvqg3dG3LpZB8KGtaSv3nAqaDU,3090
+gristcode-0.1.0.dist-info/licenses/LICENSE,sha256=Y2A2qHmmnYqakqTX3wPyhl2UBUwP8eCtG7yH1ylrWRI,1066
+gristcode-0.1.0.dist-info/METADATA,sha256=DpA0Bi28rjwbHszS_mWnckOUhXXKU5VfhVRuJwaU8y0,5056
+gristcode-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+gristcode-0.1.0.dist-info/entry_points.txt,sha256=CSkt7lzAuX8UNcTmSExbB78HE-IIkGqSSo1fNlwS9sM,49
+gristcode-0.1.0.dist-info/top_level.txt,sha256=3j6MDB3FMwnZhLZe5ikKBiertzv3CZHBOI3eSkrYFp4,10
+gristcode-0.1.0.dist-info/RECORD,,

gristcode-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gristcode-0.1.0.dist-info/entry_points.txt

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

gristcode-0.1.0.dist-info/licenses/LICENSE

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

gristcode-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gristcode