sqlcompose 0.0.3__tar.gz → 0.0.4__tar.gz

{sqlcompose-0.0.3 → sqlcompose-0.0.4}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Dagrofa
+Copyright (c) 2025 Anders Madsen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

sqlcompose-0.0.4/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: sqlcompose
+Version: 0.0.4
+Summary: Composition of SQL files
+Author-email: Anders Madsen <anders.madsen@alphavue.com>
+License-Expression: MIT
+Project-URL: repository, https://github.com/apmadsen/sqlcompose
+Keywords: sql,composition,windows,linux
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Development Status :: 6 - Mature
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8.3.0; extra == "test"
+Requires-Dist: pytest-cov>=6.1.0; extra == "test"
+Requires-Dist: pytest-mock>=3.15; extra == "test"
+Dynamic: license-file
+
+[![Test](https://github.com/apmadsen/sqlcompose/actions/workflows/python-test.yml/badge.svg)](https://github.com/apmadsen/sqlcompose/actions/workflows/python-test.yml)
+[![Coverage](https://github.com/apmadsen/sqlcompose/actions/workflows/python-test-coverage.yml/badge.svg)](https://github.com/apmadsen/sqlcompose/actions/workflows/python-test-coverage.yml)
+[![Stable Version](https://img.shields.io/pypi/v/sqlcompose?label=stable&sort=semver&color=blue)](https://github.com/apmadsen/sqlcompose/releases)
+![Pre-release Version](https://img.shields.io/github/v/release/apmadsen/sqlcompose?label=pre-release&include_prereleases&sort=semver&color=blue)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sqlcompose)
+[![PyPI Downloads](https://static.pepy.tech/badge/sqlcompose/week)](https://pepy.tech/projects/sqlcompose)
+
+# SQLCompose
+
+Composable SQL for Python — designed to make large queries easier to structure, reuse, and maintain.
+
+## 🚀 Why this exists
+
+As SQL queries grow, they tend to become difficult to manage:
+
+- Large queries turn into monolithic files
+- Logic gets duplicated across transformations
+- Small changes become risky and time-consuming
+- Reusability is limited
+
+👉 Over time, SQL becomes harder to understand, evolve, and maintain.
+
+This project introduces a simple idea:
+
+**Treat SQL as composable building blocks instead of monolithic scripts.**
+
+
+## ✨ Features
+
+- 🧩 Split SQL into reusable components
+- 🔗 Compose queries from smaller building blocks
+- ♻️ Reduce duplication across pipelines
+- 🧠 Improve readability and structure
+- ⚡ Lightweight and framework-agnostic
+
+
+## 📦 Use cases
+
+This library is especially useful when working with:
+
+- Data pipelines
+- ETL/ELT workflows
+- Analytics transformations
+- Data warehouse queries
+- Systems with repeated SQL logic
+
+👉 Particularly valuable in environments where SQL is a core part of the architecture.
+
+
+## 🏗 Core idea
+
+Traditional SQL workflows rely on large, self-contained query files.
+
+SQLCompose takes a different approach:
+
+- Break queries into smaller, focused pieces
+- Reuse common logic across multiple queries
+- Assemble final queries through composition
+
+👉 This enables a more modular and maintainable way of working with SQL.
+
+
+## 🔄 Reusability & maintainability
+
+By introducing composition:
+
+- Shared logic can be defined once and reused
+- Changes can be made in one place instead of many
+- Query structure becomes easier to reason about
+
+👉 This reduces both duplication and long-term maintenance cost.
+
+
+## 🧠 Design philosophy
+
+This project is built around a few key principles:
+
+### 1. Modularity over monoliths
+Large SQL files should be broken into smaller, understandable units.
+
+### 2. Reusability by design
+Common logic should be shareable across queries and pipelines.
+
+### 3. Simplicity over abstraction
+The goal is not to hide SQL, but to organize it better.
+
+### 4. Fit into existing workflows
+The library works alongside existing tools and data platforms.
+
+
+## 🔗 What this enables
+
+With composable SQL, you can:
+
+- Build more maintainable data pipelines
+- Reduce duplication across transformations
+- Standardize common query patterns
+- Improve collaboration across teams
+
+👉 Particularly useful in growing data platforms.
+
+
+## ⚖️ Trade-offs
+
+| Focus ✅ | Not a goal ❌ |
+|---------|--------------|
+| SQL composability | Full query engine abstraction |
+| Maintainability | Replacing SQL with another DSL |
+| Simplicity | Complex orchestration frameworks |
+
+👉 The goal is not to replace SQL —
+but to make it **easier to structure at scale**.
+
+
+## 🧠 Context
+
+This library fits into a broader focus on:
+
+- Data engineering workflows
+- Clean architecture principles
+- Composable systems
+- Reducing duplication in large codebases
+
+
+## 🎯 When to use
+
+Use this library if you:
+
+- Work with large or growing SQL codebases
+- Reuse logic across multiple queries
+- Maintain data pipelines or transformations
+- Want cleaner, more modular SQL
+
+
+## 🚫 When not to use
+
+This library may not be necessary if:
+
+- Your SQL queries are small and simple
+- Reusability is not a concern
+- Query complexity is low
+
+
+## 🔗 Related projects
+
+Part of a broader focus on:
+
+- Runtime abstractions
+- Developer tooling
+- Structured Python systems
+
+👉 https://github.com/apmadsen
+
+
+## 🤝 Contributing
+
+Feedback, ideas, and contributions are welcome!
+
+## ⚙️ Examples
+
+### 1. Execute the script with the filename as an argument and output to the console:
+```bash
+sqlcompose query.sql
+```
+
+### 2. Pipe data into application and output to a file
+```bash
+cat query.sql | sqlcompose > output.sql
+```
+
+### 3. Execute the script with SQL string as argument
+```bash
+sqlcompose 'select * from $INCLUDE(included-query1.sql)'
+```
+> NOTE: Different consoles have different limitations, so you may have to switch from single to double quotes to allow for using the dollar sign.
+
+### 4. Import it in another python application or package
+```python
+from sqlcompose import load, loads
+# method 1 : loading from a file
+sql1 = load("query.sql")
+
+# method 2 : loading from an SQL string
+sql2 = loads("""
+    select *
+      from dataset.table main
+inner join $INCLUDE(other.sql) other
+        on other.field = main.field
+  """)
+```
+
+## Preparing SQL scripts
+Insert a `$INCLUDE(filename)` where the reference to the file should be in the resulting SQL, keeping in mind that references are loaded relative to the file loaded or the current working dir in case of an SQL string.
+
+```sql
+--main-query.sql
+select * from $INCLUDE(includes\included-query2.sql)
+```
+```sql
+--included-query1.sql
+select 1 as test
+```
+```sql
+--included-query2.sql
+select * from $INCLUDE(included-query1.sql)
+union all
+select * from $INCLUDE(nested\included-query3.sql)
+```
+```sql
+--nested\included-query3.sql
+select 1 as test
+```
+Which outputs:
+```sql
+WITH Q_1_1 AS (
+  WITH Q_2_1 AS (
+    --includes\included-query1.sql
+    select 1 as test
+  ), Q_2_2 AS (
+    --includes\nested\included-query3.sql
+    select 1 as test
+  ), Q_2 AS (
+    --includes\included-query2.sql
+    select * from Q_2_1
+    union all
+    select * from Q_2_2
+  )
+  SELECT * FROM Q_2
+), Q_1 AS (
+  --test\main-query.sql
+  select * from Q_1_1
+)
+SELECT * FROM Q_1
+```

sqlcompose-0.0.4/README.md

@@ -0,0 +1,234 @@
+[![Test](https://github.com/apmadsen/sqlcompose/actions/workflows/python-test.yml/badge.svg)](https://github.com/apmadsen/sqlcompose/actions/workflows/python-test.yml)
+[![Coverage](https://github.com/apmadsen/sqlcompose/actions/workflows/python-test-coverage.yml/badge.svg)](https://github.com/apmadsen/sqlcompose/actions/workflows/python-test-coverage.yml)
+[![Stable Version](https://img.shields.io/pypi/v/sqlcompose?label=stable&sort=semver&color=blue)](https://github.com/apmadsen/sqlcompose/releases)
+![Pre-release Version](https://img.shields.io/github/v/release/apmadsen/sqlcompose?label=pre-release&include_prereleases&sort=semver&color=blue)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sqlcompose)
+[![PyPI Downloads](https://static.pepy.tech/badge/sqlcompose/week)](https://pepy.tech/projects/sqlcompose)
+
+# SQLCompose
+
+Composable SQL for Python — designed to make large queries easier to structure, reuse, and maintain.
+
+## 🚀 Why this exists
+
+As SQL queries grow, they tend to become difficult to manage:
+
+- Large queries turn into monolithic files
+- Logic gets duplicated across transformations
+- Small changes become risky and time-consuming
+- Reusability is limited
+
+👉 Over time, SQL becomes harder to understand, evolve, and maintain.
+
+This project introduces a simple idea:
+
+**Treat SQL as composable building blocks instead of monolithic scripts.**
+
+
+## ✨ Features
+
+- 🧩 Split SQL into reusable components
+- 🔗 Compose queries from smaller building blocks
+- ♻️ Reduce duplication across pipelines
+- 🧠 Improve readability and structure
+- ⚡ Lightweight and framework-agnostic
+
+
+## 📦 Use cases
+
+This library is especially useful when working with:
+
+- Data pipelines
+- ETL/ELT workflows
+- Analytics transformations
+- Data warehouse queries
+- Systems with repeated SQL logic
+
+👉 Particularly valuable in environments where SQL is a core part of the architecture.
+
+
+## 🏗 Core idea
+
+Traditional SQL workflows rely on large, self-contained query files.
+
+SQLCompose takes a different approach:
+
+- Break queries into smaller, focused pieces
+- Reuse common logic across multiple queries
+- Assemble final queries through composition
+
+👉 This enables a more modular and maintainable way of working with SQL.
+
+
+## 🔄 Reusability & maintainability
+
+By introducing composition:
+
+- Shared logic can be defined once and reused
+- Changes can be made in one place instead of many
+- Query structure becomes easier to reason about
+
+👉 This reduces both duplication and long-term maintenance cost.
+
+
+## 🧠 Design philosophy
+
+This project is built around a few key principles:
+
+### 1. Modularity over monoliths
+Large SQL files should be broken into smaller, understandable units.
+
+### 2. Reusability by design
+Common logic should be shareable across queries and pipelines.
+
+### 3. Simplicity over abstraction
+The goal is not to hide SQL, but to organize it better.
+
+### 4. Fit into existing workflows
+The library works alongside existing tools and data platforms.
+
+
+## 🔗 What this enables
+
+With composable SQL, you can:
+
+- Build more maintainable data pipelines
+- Reduce duplication across transformations
+- Standardize common query patterns
+- Improve collaboration across teams
+
+👉 Particularly useful in growing data platforms.
+
+
+## ⚖️ Trade-offs
+
+| Focus ✅ | Not a goal ❌ |
+|---------|--------------|
+| SQL composability | Full query engine abstraction |
+| Maintainability | Replacing SQL with another DSL |
+| Simplicity | Complex orchestration frameworks |
+
+👉 The goal is not to replace SQL —
+but to make it **easier to structure at scale**.
+
+
+## 🧠 Context
+
+This library fits into a broader focus on:
+
+- Data engineering workflows
+- Clean architecture principles
+- Composable systems
+- Reducing duplication in large codebases
+
+
+## 🎯 When to use
+
+Use this library if you:
+
+- Work with large or growing SQL codebases
+- Reuse logic across multiple queries
+- Maintain data pipelines or transformations
+- Want cleaner, more modular SQL
+
+
+## 🚫 When not to use
+
+This library may not be necessary if:
+
+- Your SQL queries are small and simple
+- Reusability is not a concern
+- Query complexity is low
+
+
+## 🔗 Related projects
+
+Part of a broader focus on:
+
+- Runtime abstractions
+- Developer tooling
+- Structured Python systems
+
+👉 https://github.com/apmadsen
+
+
+## 🤝 Contributing
+
+Feedback, ideas, and contributions are welcome!
+
+## ⚙️ Examples
+
+### 1. Execute the script with the filename as an argument and output to the console:
+```bash
+sqlcompose query.sql
+```
+
+### 2. Pipe data into application and output to a file
+```bash
+cat query.sql | sqlcompose > output.sql
+```
+
+### 3. Execute the script with SQL string as argument
+```bash
+sqlcompose 'select * from $INCLUDE(included-query1.sql)'
+```
+> NOTE: Different consoles have different limitations, so you may have to switch from single to double quotes to allow for using the dollar sign.
+
+### 4. Import it in another python application or package
+```python
+from sqlcompose import load, loads
+# method 1 : loading from a file
+sql1 = load("query.sql")
+
+# method 2 : loading from an SQL string
+sql2 = loads("""
+    select *
+      from dataset.table main
+inner join $INCLUDE(other.sql) other
+        on other.field = main.field
+  """)
+```
+
+## Preparing SQL scripts
+Insert a `$INCLUDE(filename)` where the reference to the file should be in the resulting SQL, keeping in mind that references are loaded relative to the file loaded or the current working dir in case of an SQL string.
+
+```sql
+--main-query.sql
+select * from $INCLUDE(includes\included-query2.sql)
+```
+```sql
+--included-query1.sql
+select 1 as test
+```
+```sql
+--included-query2.sql
+select * from $INCLUDE(included-query1.sql)
+union all
+select * from $INCLUDE(nested\included-query3.sql)
+```
+```sql
+--nested\included-query3.sql
+select 1 as test
+```
+Which outputs:
+```sql
+WITH Q_1_1 AS (
+  WITH Q_2_1 AS (
+    --includes\included-query1.sql
+    select 1 as test
+  ), Q_2_2 AS (
+    --includes\nested\included-query3.sql
+    select 1 as test
+  ), Q_2 AS (
+    --includes\included-query2.sql
+    select * from Q_2_1
+    union all
+    select * from Q_2_2
+  )
+  SELECT * FROM Q_2
+), Q_1 AS (
+  --test\main-query.sql
+  select * from Q_1_1
+)
+SELECT * FROM Q_1
+```

{sqlcompose-0.0.3 → sqlcompose-0.0.4}/pyproject.toml

@@ -1,13 +1,14 @@
 [project]
 name = "sqlcompose"
 dynamic = ["version"]
-description = "Composition of linked SQL files"
+description = "Composition of SQL files"
 keywords = ["sql", "composition", "windows", "linux"]
 readme = "README.md"
 authors = [
     { name = "Anders Madsen", email = "anders.madsen@alphavue.com" }
 ]
-license = { text = "MIT" }
+license = "MIT"
+license-files = [ "LICENSE"]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
     "Development Status :: 6 - Mature",
@@ -21,13 +22,16 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Programming Language :: Python",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Software Development :: Libraries",
     "Typing :: Typed"
 ]
-dependencies = []
-requires-python = ">=3.10"
+dependencies = [
+
+]
+requires-python = ">= 3.10, < 3.15"
 
 [project.urls]
 repository = "https://github.com/apmadsen/sqlcompose"
@@ -39,11 +43,12 @@ repository = "https://github.com/apmadsen/sqlcompose"
 test = [
     "pytest>=8.3.0",
     "pytest-cov>=6.1.0",
+    "pytest-mock>=3.15"
 ]
 
-[tool.setuptools.dynamic]
-version = { attr = 'sqlcompose.__init__.__version__' }
+[tool.setuptools-git-versioning]
+enabled = true
 
 [build-system]
-requires = ["setuptools >= 77.0.3"]
-build-backend = "setuptools.build_meta"
+requires = ["setuptools >= 77.0.3", "setuptools-git-versioning >= 2.1.0"]
+build-backend = "setuptools.build_meta"

{sqlcompose-0.0.3 → sqlcompose-0.0.4}/src/sqlcompose/__init__.py

@@ -1,10 +1,10 @@
 from sqlcompose.core.functions import load, loads
 from sqlcompose.core.circular_dependency_error import CircularDependencyError
+from sqlcompose.core.file_not_found_err import FileNotFoundErr
 
 __all__ = [
     'load',
     'loads',
     'CircularDependencyError',
-]
-__package_name__ = "sqlcompose"
-__version__ = "0.0.3"
+    'FileNotFoundErr',
+]

sqlcompose-0.0.4/src/sqlcompose/core/app.py

@@ -0,0 +1,30 @@
+from argparse import ArgumentParser
+
+from sqlcompose.core.functions import load, loads
+from sqlcompose.core.compat import is_file, get_piped_input
+from sqlcompose.core.file_not_found_err import FileNotFoundErr
+
+
+def app(args: list[str]) -> tuple[str, int]:
+    try:
+        from sys import stdin # iport must be done here to allow for test patching
+
+        if not stdin.isatty() and ( piped := get_piped_input(stdin) ):
+            sql = loads(piped)
+        else:
+            parser = ArgumentParser(prog = "sqlcompose")
+            parser.add_argument("input", type=str, help = "SQL expression or location of an SQL file")
+            pargs = parser.parse_args(args)
+
+            if is_file(pargs.input):
+                sql = load(pargs.input)
+            else:
+                sql = loads(pargs.input)
+
+        return sql, 0
+    except SystemExit as ex:
+        return str(ex), 2
+    except (FileNotFoundErr, FileNotFoundError) as ex:
+        return str(ex), 3
+    except Exception as ex: # pragma: no cover
+        return f"Unexpected error: {ex}", 1

sqlcompose-0.0.4/src/sqlcompose/core/compat.py

@@ -0,0 +1,75 @@
+from os import path, sep
+from typing import TextIO
+from re import compile
+from threading import Thread, Event
+
+RX_FILE = compile(r"^[\w,\s-]+\.[A-Za-z]{3}$")
+WINDOWS_PATH_SEP = "\\"
+UNIX_PATH_SEP = "/"
+
+def fix_path(file_path: str) -> str:
+    """Replaces all path separators, be they Linux or Windows style
+    to the standard path separator of the system.
+
+    Args:
+        file_path (str): The file path to fix.
+    """
+    for str in [ WINDOWS_PATH_SEP, UNIX_PATH_SEP ]:
+        if str != path.sep:
+            file_path = file_path.replace(str, path.sep)
+
+    return file_path
+
+def get_relative_path(file_path: str, root: str) -> str:
+    """Get the path relative to root path.
+
+    Args:
+        file_path (str): The path.
+        root (str): The root path.
+
+    Returns:
+        str: The relative path.
+    """
+    if root == file_path:
+        return file_path
+    else:
+        return path.relpath(file_path, path.commonprefix([root, file_path]))
+
+def is_file(text: str) -> bool:
+    if path.isfile(text):
+        return True
+    elif sep in text and is_file(path.basename(text)):
+        return True
+    elif RX_FILE.match(text):
+        return True
+
+    return False
+
+def get_piped_input(pipe: TextIO) -> str:
+    """Reads input from pipe (usually sys.stdin) without blocking.
+    """
+    output: list[str] = []
+    ev_started = Event()
+    ev_done = Event()
+
+    def fn(output: list[str]):
+        try:
+            ev_started.set()
+            output.append(pipe.read())
+        except OSError:
+            pass
+        finally:
+            ev_done.set()
+
+    thread = Thread(target = fn, args = (output,))
+    thread.start()
+
+    ev_started.wait()
+
+    if ev_done.wait(0.1): # if there is in fact anything in the pipe, we expect it to be read within 0.1 second
+        thread.join()
+    else:
+        pass # pragma: no cover
+        # the thread will block indefinitely, nothing to do about it
+
+    return output[0] if any(output) else ""

sqlcompose-0.0.4/src/sqlcompose/core/file_not_found_err.py

@@ -0,0 +1,11 @@
+
+class FileNotFoundErr(Exception):
+    __slots__ = [ "__filename" ]
+
+    def __init__(self, filename: str, error: str | None = None):
+        super().__init__(error or f"File {filename} not found")
+        self.__filename = filename
+
+    @property
+    def filename(self) -> str:
+        return self.__filename # pragma: no cover