sqlinclude 0.1.0__tar.gz

sqlinclude-0.1.0/LICENSE

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

sqlinclude-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: sqlinclude
+Version: 0.1.0
+Summary: Tiny SQL source preprocessor: expand @include directives and @define variables.
+Author-email: lukasburski <lukasbursky@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/lukasbursky/sqlinclude
+Project-URL: Source, https://github.com/lukasbursky/sqlinclude
+Project-URL: Issues, https://github.com/lukasbursky/sqlinclude/issues
+Keywords: sql,preprocessor,include,bigquery,templating
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Pre-processors
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# sqlinclude
+
+Tiny SQL source preprocessor. Expands `@include` directives and `@define`
+variables recursively. No SQL parsing, no opinion about any database. Intended
+to be piped into a query tool:
+
+```console
+sqlinclude analysis.sql | bq query
+bq query "$(sqlinclude analysis.sql)"
+```
+
+Written for Unix and Windows alike: it is a single dependency-free Python
+package and installs a `sqlinclude` console command (a `sqlinclude.exe` on
+Windows).
+
+## Install
+
+```console
+pipx install sqlinclude
+```
+
+or, into the current environment:
+
+```console
+pip install sqlinclude
+```
+
+Requires Python 3.12+.
+
+## Directives
+
+Line-oriented, leading whitespace allowed:
+
+```
+@include file.sql
+@include "file.sql"
+@define name = value        (the `= ` is optional; value is the rest of the
+                             line, kept verbatim including quotes)
+```
+
+Include paths are resolved relative to the including file. Includes may nest;
+cycles are detected and reported as errors.
+
+Variables form a single environment filled in expansion order: the first
+`@define name ...` seen anywhere in the tree wins, and later definitions of the
+same name are ignored (so a parent file's definition always overrides an
+included fragment's default). Definitions from an included file leak back to
+the including file. A `@name` with no definition passes through unchanged --
+BigQuery's native `@param` syntax is never touched.
+
+Each include block is bracketed with `-- #line N "file"` markers (with forward
+slashes on every platform) so error messages from downstream tools point at the
+originating source file and line. Use `-n`/`--no-markers` to suppress them.
+
+## Example
+
+`analysis.sql`:
+
+```sql
+@define start = '2024-01-01'
+@define end = '2024-12-31'
+
+WITH users AS (
+    @include "users.sql"
+),
+
+orders AS (
+    @include orders.sql
+)
+
+SELECT ... WHERE created BETWEEN @start AND @end
+```
+
+Run:
+
+```console
+sqlinclude analysis.sql | bq query
+sqlinclude --vars start='2024-06-01' analysis.sql | bq query
+sqlinclude --tree analysis.sql          # show the include tree, not SQL
+sqlinclude --tree --ascii analysis.sql  # ASCII box characters instead of Unicode
+```
+
+## Options
+
+| Option | Description |
+| --- | --- |
+| `file` | SQL file to preprocess (default: read stdin) |
+| `-n`, `--no-markers` | do not emit `-- #line` markers around includes |
+| `--vars name=value` | set a variable (repeatable); wins over `@define` |
+| `-e`, `--edit` | open the editor even when no variable is undefined |
+| `--no-edit` | never open the editor; leave undefined `@name`s as-is |
+| `-t`, `--tree` | print the `@include` dependency tree instead of SQL |
+| `--ascii` | use ASCII box characters in the include tree |
+| `--version` | show the version |
+
+## Editing undefined variables
+
+When a variable is undefined, `sqlinclude` opens the editor named by
+`$VISUAL`/`$EDITOR` on the controlling terminal, even when its output is piped.
+Edit values, or delete a line to leave that variable undefined. Blank lines and
+`#` comments are ignored. On Windows the same variables are honored, falling
+back to `notepad`. With `-e`/`--edit` the buffer also shows the `@include`
+tree. Undefined variables are always reported on stderr; pass `--no-edit` to
+silence everything and pass undefined names through untouched.
+
+## Development
+
+```console
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

sqlinclude-0.1.0/README.md

@@ -0,0 +1,117 @@
+# sqlinclude
+
+Tiny SQL source preprocessor. Expands `@include` directives and `@define`
+variables recursively. No SQL parsing, no opinion about any database. Intended
+to be piped into a query tool:
+
+```console
+sqlinclude analysis.sql | bq query
+bq query "$(sqlinclude analysis.sql)"
+```
+
+Written for Unix and Windows alike: it is a single dependency-free Python
+package and installs a `sqlinclude` console command (a `sqlinclude.exe` on
+Windows).
+
+## Install
+
+```console
+pipx install sqlinclude
+```
+
+or, into the current environment:
+
+```console
+pip install sqlinclude
+```
+
+Requires Python 3.12+.
+
+## Directives
+
+Line-oriented, leading whitespace allowed:
+
+```
+@include file.sql
+@include "file.sql"
+@define name = value        (the `= ` is optional; value is the rest of the
+                             line, kept verbatim including quotes)
+```
+
+Include paths are resolved relative to the including file. Includes may nest;
+cycles are detected and reported as errors.
+
+Variables form a single environment filled in expansion order: the first
+`@define name ...` seen anywhere in the tree wins, and later definitions of the
+same name are ignored (so a parent file's definition always overrides an
+included fragment's default). Definitions from an included file leak back to
+the including file. A `@name` with no definition passes through unchanged --
+BigQuery's native `@param` syntax is never touched.
+
+Each include block is bracketed with `-- #line N "file"` markers (with forward
+slashes on every platform) so error messages from downstream tools point at the
+originating source file and line. Use `-n`/`--no-markers` to suppress them.
+
+## Example
+
+`analysis.sql`:
+
+```sql
+@define start = '2024-01-01'
+@define end = '2024-12-31'
+
+WITH users AS (
+    @include "users.sql"
+),
+
+orders AS (
+    @include orders.sql
+)
+
+SELECT ... WHERE created BETWEEN @start AND @end
+```
+
+Run:
+
+```console
+sqlinclude analysis.sql | bq query
+sqlinclude --vars start='2024-06-01' analysis.sql | bq query
+sqlinclude --tree analysis.sql          # show the include tree, not SQL
+sqlinclude --tree --ascii analysis.sql  # ASCII box characters instead of Unicode
+```
+
+## Options
+
+| Option | Description |
+| --- | --- |
+| `file` | SQL file to preprocess (default: read stdin) |
+| `-n`, `--no-markers` | do not emit `-- #line` markers around includes |
+| `--vars name=value` | set a variable (repeatable); wins over `@define` |
+| `-e`, `--edit` | open the editor even when no variable is undefined |
+| `--no-edit` | never open the editor; leave undefined `@name`s as-is |
+| `-t`, `--tree` | print the `@include` dependency tree instead of SQL |
+| `--ascii` | use ASCII box characters in the include tree |
+| `--version` | show the version |
+
+## Editing undefined variables
+
+When a variable is undefined, `sqlinclude` opens the editor named by
+`$VISUAL`/`$EDITOR` on the controlling terminal, even when its output is piped.
+Edit values, or delete a line to leave that variable undefined. Blank lines and
+`#` comments are ignored. On Windows the same variables are honored, falling
+back to `notepad`. With `-e`/`--edit` the buffer also shows the `@include`
+tree. Undefined variables are always reported on stderr; pass `--no-edit` to
+silence everything and pass undefined names through untouched.
+
+## Development
+
+```console
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

sqlinclude-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sqlinclude"
+dynamic = ["version"]
+description = "Tiny SQL source preprocessor: expand @include directives and @define variables."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "lukasburski", email = "lukasbursky@gmail.com" }]
+keywords = ["sql", "preprocessor", "include", "bigquery", "templating"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Database",
+    "Topic :: Software Development :: Pre-processors",
+]
+
+[project.scripts]
+sqlinclude = "sqlinclude.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/lukasbursky/sqlinclude"
+Source = "https://github.com/lukasbursky/sqlinclude"
+Issues = "https://github.com/lukasbursky/sqlinclude/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "build>=1.2"]
+
+[tool.setuptools.dynamic]
+version = { attr = "sqlinclude.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sqlinclude-0.1.0/setup.cfg

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

sqlinclude-0.1.0/src/sqlinclude/__init__.py

@@ -0,0 +1,7 @@
+"""sqlinclude -- tiny SQL source preprocessor.
+
+Expands @include directives and @define variables recursively. No SQL
+parsing, no opinion about any database.
+"""
+
+__version__ = "0.1.0"

sqlinclude-0.1.0/src/sqlinclude/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for ``python -m sqlinclude``."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

sqlinclude-0.1.0/src/sqlinclude/cli.py

@@ -0,0 +1,226 @@
+"""Command-line interface for sqlinclude."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+
+from . import __version__
+from .editor import (
+    edit_buffer,
+    have_ctrl_tty,
+    parse_buffer,
+    render_buffer,
+    resolve_editor,
+    undefined_count,
+)
+from .preprocess import (
+    ORIGIN_UNDEFINED,
+    STDIN_NAME,
+    collect_tree,
+    collect_vars,
+    render_tree,
+    walk,
+)
+
+
+def _stdout_can_encode(text: str) -> bool:
+    enc = getattr(sys.stdout, "encoding", None) or "ascii"
+    try:
+        text.encode(enc)
+    except (UnicodeEncodeError, LookupError):
+        return False
+    return True
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sqlinclude",
+        description="Expand @include directives and @define variables in SQL source "
+        "(no SQL parsing).",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "example (analysis.sql):\n"
+            "\n"
+            "  @define start = '2024-01-01'\n"
+            "  @define end = '2024-12-31'\n"
+            "\n"
+            "  WITH users AS (\n"
+            '      @include "users.sql"\n'
+            "  ),\n"
+            "\n"
+            "  orders AS (\n"
+            "      @include orders.sql\n"
+            "  )\n"
+            "\n"
+            "  SELECT ... WHERE created BETWEEN @start AND @end\n"
+            "\n"
+            "run:\n"
+            "\n"
+            "  sqlinclude analysis.sql | bq query\n"
+            "  sqlinclude --vars start='2024-06-01' analysis.sql | bq query\n"
+            "  sqlinclude --tree analysis.sql   # show the include tree, not SQL\n"
+            "\n"
+            "variables:\n"
+            "\n"
+            "  @define name = value   set a variable in a file (first definition wins)\n"
+            "  --vars name=value      set a variable from the command line (repeatable)\n"
+            "  @name                  substituted where defined; undefined names pass\n"
+            "                         through unchanged (BigQuery @params stay intact)\n"
+            "  -e, --edit             open the editor even when nothing is undefined\n"
+            "  --no-edit              never open the editor; no stderr notes\n"
+            "\n"
+            "editing:\n"
+            "\n"
+            "  When a variable is undefined, sqlinclude opens $VISUAL/$EDITOR (or vim,\n"
+            "  notepad on Windows) on the controlling terminal, even if its output is\n"
+            "  piped. Edit values; delete a line to leave that variable undefined; blank\n"
+            "  and # lines are ignored. With -e/--edit the buffer also shows the @include\n"
+            "  tree. Undefined variables are always reported on stderr -- use\n"
+            "  --no-edit to silence everything.\n"
+        ),
+    )
+    parser.add_argument(
+        "file",
+        nargs="?",
+        default="-",
+        help="SQL file to preprocess (default: read stdin)",
+    )
+    parser.add_argument(
+        "-n",
+        "--no-markers",
+        action="store_true",
+        help="do not emit -- #line markers around includes",
+    )
+    parser.add_argument(
+        "--vars",
+        action="append",
+        default=[],
+        metavar="name=value",
+        help="set a variable (repeatable); wins over @define",
+    )
+    parser.add_argument(
+        "-e",
+        "--edit",
+        action="store_true",
+        help="open the editor even when no variable is undefined",
+    )
+    parser.add_argument(
+        "--no-edit",
+        action="store_true",
+        help="never open the editor; leave undefined @names as-is (no stderr notes)",
+    )
+    parser.add_argument(
+        "-t",
+        "--tree",
+        action="store_true",
+        help="print the @include dependency tree as ASCII on stdout instead of expanding SQL",
+    )
+    parser.add_argument(
+        "--ascii",
+        action="store_true",
+        help="use ASCII (not Unicode) box characters in the include tree",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv
+    args = build_parser().parse_args(argv[1:])
+
+    cli_vars: dict[str, str] = {}
+    for pair in args.vars:
+        if "=" not in pair:
+            sys.stderr.write(f"sqlinclude: --vars expects name=value, got {pair!r}\n")
+            return 2
+        name, value = pair.split("=", 1)
+        if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name):
+            sys.stderr.write(f"sqlinclude: invalid variable name in --vars: {name!r}\n")
+            return 2
+        cli_vars[name] = value
+
+    if args.file == "-":
+        source = sys.stdin.read()
+        top = None
+    else:
+        try:
+            with open(args.file, encoding="utf-8") as fh:
+                source = fh.read()
+        except OSError as exc:
+            sys.stderr.write(f"sqlinclude: {args.file}: {exc}\n")
+            return 1
+        top = args.file
+    if source and not source.endswith("\n"):
+        source += "\n"
+
+    top_disp = (
+        os.path.relpath(os.path.realpath(top), os.getcwd()).replace("\\", "/")
+        if top
+        else STDIN_NAME
+    )
+
+    if args.tree:
+        root = collect_tree(source, top)
+        if root is None:
+            return 1
+        ascii_only = args.ascii or not _stdout_can_encode("└──")
+        sys.stdout.write(render_tree(root, ascii_only=ascii_only))
+        return 0
+
+    collected = collect_vars(source, top, cli_vars)
+    if collected is None:
+        return 1
+    order, values, sources = collected
+    undefined_present = any(values[n] is None for n in order)
+
+    if (
+        top is not None
+        and not args.no_edit
+        and (undefined_present or args.edit)
+        and have_ctrl_tty()
+    ):
+        editor = resolve_editor()
+        if undefined_present:
+            sys.stderr.write(
+                f"sqlinclude: opening {editor} for {undefined_count(order, values)} "
+                "undefined variable(s)\n"
+            )
+        tree = None
+        if args.edit:
+            tree = collect_tree(source, top)
+            if tree is None:
+                return 1
+        edited = edit_buffer(render_buffer(top_disp, order, values, sources, tree), editor)
+        if edited is None:
+            return 1
+        env = parse_buffer(edited)
+        blocked = set(order) - set(env)
+    else:
+        env = dict(cli_vars)
+        blocked = set()
+        if not args.no_edit and undefined_present:
+            names = [n for n in order if values[n] is None]
+            sys.stderr.write(
+                "sqlinclude: undefined variables "
+                f"({len(names)}): {', '.join('@' + n for n in names)} "
+                "-- left as @name\n"
+            )
+
+    out: list[str] = []
+    stack: list[tuple[str, str]] = []
+    if walk(source, top, out, stack, args.no_markers, env, blocked):
+        return 1
+    sys.stdout.write("".join(out))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())