sqlnbfmt 0.4.1__tar.gz → 0.5.0__tar.gz

sqlnbfmt-0.5.0/.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    labels:
+      - "dependencies"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+    groups:
+      minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"

sqlnbfmt-0.5.0/.github/workflows/ci-and-publish.yml

@@ -0,0 +1,55 @@
+name: Python CI and Publish to PyPI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  release:
+    types: [created]
+  workflow_dispatch:
+    inputs:
+      run_publish:
+        description: 'Set to true to run the publish job'
+        required: false
+        default: 'false'
+
+permissions: {}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+      - run: uv python install 3.12
+      - run: uv sync --all-extras --dev --frozen
+      - run: uv run pytest
+
+  security:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - run: uvx uv-secure uv.lock
+
+  publish:
+    needs: [test, security]
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.run_publish == 'true')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          enable-cache: true
+      - run: uv python install 3.12
+      - run: uv build --no-sources
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

sqlnbfmt-0.5.0/.gitignore

@@ -0,0 +1,163 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+.DS_STORE

sqlnbfmt-0.5.0/.pre-commit-config.yaml

@@ -0,0 +1,41 @@
+repos:
+  # Linting + formatting (Astral)
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.1
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  # File quality + security
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-ast
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-added-large-files
+      - id: debug-statements
+      - id: detect-private-key
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+
+  # Validate pyproject.toml against PEP 621
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: '0.26'
+    hooks:
+      - id: validate-pyproject
+
+  # Local hooks
+  - repo: local
+    hooks:
+      # Fast unit tests
+      - id: pytest-fast
+        name: pytest (fast)
+        entry: uv run pytest tests/ -x -q --timeout=10
+        language: system
+        types: [python]
+        pass_filenames: false
+        stages: [pre-push]

sqlnbfmt-0.5.0/.pre-commit-hooks.yaml

@@ -0,0 +1,35 @@
+- id: sqlnbfmt
+  name: SQL Notebook Formatter
+  description: Format SQL queries in Jupyter notebooks
+  entry: sqlnbfmt
+  language: python
+  types: [jupyter]
+  require_serial: true
+  minimum_pre_commit_version: '3.0.0'
+
+- id: sqlnbfmt-check
+  name: SQL Notebook Formatter (check)
+  description: Check SQL formatting in Jupyter notebooks without modifying files
+  entry: sqlnbfmt --check
+  language: python
+  types: [jupyter]
+  require_serial: true
+  minimum_pre_commit_version: '3.0.0'
+
+- id: sqlnbfmt-py
+  name: SQL Python File Formatter
+  description: Format SQL queries in Python files (e.g. Marimo notebooks)
+  entry: sqlnbfmt
+  language: python
+  types: [python]
+  require_serial: true
+  minimum_pre_commit_version: '3.0.0'
+
+- id: sqlnbfmt-py-check
+  name: SQL Python File Formatter (check)
+  description: Check SQL formatting in Python files without modifying files
+  entry: sqlnbfmt --check
+  language: python
+  types: [python]
+  require_serial: true
+  minimum_pre_commit_version: '3.0.0'

sqlnbfmt-0.5.0/.python-version

@@ -0,0 +1 @@
+3.12

sqlnbfmt-0.5.0/CHANGELOG.md

@@ -0,0 +1,165 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.0] - 2026-10-15
+
+### Added
+
+- **`pyproject.toml` configuration**: set options in a `[tool.sqlnbfmt]` table instead of a separate YAML file. Without `--config`, sqlnbfmt uses the nearest `pyproject.toml` that has the table, searching up to the repository root. The JupyterLab integration uses the same discovery ([#22](https://github.com/flyersworder/sqlnbfmt/issues/22))
+- `--config` accepts a `.toml` path as well as YAML
+- `dialect` config option (in `[tool.sqlnbfmt]` or YAML), so the dialect no longer has to be passed as `--dialect` on every run; `--dialect` still overrides it
+
+### Changed
+
+- Config values are now type-checked: a wrong type (e.g. a string where a list is expected) is reported as an error naming the file. Previously such values were silently mis-parsed or crashed with a traceback
+- Unknown config options now produce a warning instead of being silently ignored
+
+### Fixed
+
+- SQL passed to a function call is now indented relative to the line the call is on, and a closing `)` or remaining arguments no longer land at column 0. This was most visible in Marimo cells, where every `mo.sql(...)` sits inside a function. It had regressed in 0.3.0, when the `black` post-processing pass was removed. Code already formatted by an earlier version keeps its layout until its SQL changes
+- The Jupyter server extension no longer overrides a formatter registered in `jupyter_server_config.py` (e.g. `register(dialect="postgres")`), and it now logs configuration errors instead of silently not registering
+- An unknown dialect (e.g. `--dialect postgress`) is now rejected with a suggestion. Previously every SQL string silently failed to parse, so `--check` reported all files as properly formatted
+- The `config.yaml` template was missing the `sql` function name (default since 0.4.0). Because config lists replace the defaults, copying the template silently disabled Marimo `mo.sql()` formatting. The README now states the replace semantics explicitly
+- Upgraded locked dependencies, including sqlglot 29 → 30 (formatting output unchanged across the eval suite)
+- A skipped Jupyter extension registration is now logged at debug level instead of being silently swallowed
+
+## [0.4.2] - 2026-03-24
+
+### Added
+
+- **Jupyter server extension**: `pip install sqlnbfmt` now auto-registers with jupyterlab-code-formatter — no manual config needed
+
+### Changed
+
+- Switched build system from setuptools to hatchling
+- Updated JupyterLab docs to use `jupyter_server_config.py` (modern) instead of `jupyter_notebook_config.py` (legacy)
+
+## [0.4.0] - 2026-03-24
+
+### Added
+
+- **Marimo notebook support**: format SQL in Marimo `.py` notebooks via `mo.sql()` calls — same `sqlnbfmt` command, auto-detected by file extension
+- **Python file support**: `sqlnbfmt` now accepts `.py` files alongside `.ipynb` — works on any Python file containing SQL strings
+- **JupyterLab integration**: `sqlnbfmt.jupyterlab_integration.register()` for use with `jupyterlab-code-formatter`
+- `format_cell_source()` public API for formatting a single cell's source code
+- `_format_python_source()`, `process_python_file()`, `diff_python_file()` public API for programmatic use
+- `sql` added to default recognized function names (matches `mo.sql()`, etc.)
+- `sqlnbfmt-py` and `sqlnbfmt-py-check` pre-commit hooks for Python files
+- Marimo eval fixtures: `marimo_basic_sql`, `marimo_fstring_interpolation`, `marimo_complex_sql`, `marimo_multi_cell_mixed`, `marimo_comment_preservation`, `marimo_multi_statement`, `marimo_skip_hint`, `marimo_non_sql_unchanged`, `marimo_idempotency`
+
+### Fixed
+
+- Idempotency: already-formatted SQL in triple-quoted strings (with leading whitespace/indentation) is no longer re-formatted on every run
+
+### Changed
+
+- CLI description and help text updated to reflect multi-format support
+- Project description and keywords updated for Marimo discoverability
+
+## [0.3.2] - 2026-03-16
+
+### Fixed
+
+- Multiple SQL statements in a single cell are no longer concatenated on one line — each statement now starts on its own line after the `;` separator ([#3](https://github.com/flyersworder/sqlnbfmt/issues/3))
+
+### Changed
+
+- SQL parsing switched from `sqlglot.parse_one()` to `sqlglot.parse()` to correctly handle multi-statement inputs
+
+### Added
+
+- `multi_statement` eval fixture case covering `DROP TABLE` + `CREATE TABLE` sequences
+
+## [0.3.1] - 2026-03-15
+
+### Fixed
+
+- `diff_notebook()` no longer duplicates cell-processing logic — extracted shared `_format_cells()` helper to prevent future divergence
+- `--check --diff` combined mode no longer double-counts notebooks or processes them twice
+- Skip hint (`# sqlnbfmt: skip`) no longer triggers on string literals containing the directive — only dedicated comment lines are recognised
+- `load_config()` with a partial config file (missing keys) now falls back to built-in defaults instead of empty sets
+- `load_config()` with an empty YAML file no longer raises `AttributeError`
+- In-function SQL indentation now respects `indent_width` config instead of hardcoded 4 spaces
+
+### Added
+
+- `main()` integration tests for `--diff`, `--check`, and `--check --diff` exit code behavior
+- Docstring on `_has_skip_hint()` clarifying that inline trailing comments are intentionally ignored
+
+## [0.3.0] - 2026-03-15
+
+### Added
+
+- **Zero-config defaults**: sqlnbfmt now works out of the box without a `config.yaml` file — built-in defaults for SQL keywords, function names, and decorators
+- **`--check` mode**: verify formatting without modifying files; exits with code 1 if changes are needed (CI-friendly)
+- **`--diff` mode**: print a unified diff of formatting changes without modifying files
+- **Skip hints**: add `# sqlnbfmt: skip` to any cell to skip formatting
+- **`sqlnbfmt-check` pre-commit hook**: a read-only hook variant for CI pipelines
+- Cell index in all warning/debug messages for easier debugging
+- PyPI keywords and project URLs in package metadata
+- `skip_hint` eval fixture case
+
+### Changed
+
+- `--config` argument is now optional (defaults to built-in settings instead of requiring `config.yaml`)
+- `load_config()` accepts `None` to return defaults; passing a missing path still raises `FileNotFoundError`
+- Version bumped to 0.3.0
+
+## [0.2.0] - 2026-03-15
+
+### Fixed
+
+- Python comments in code cells are no longer stripped during formatting ([#2](https://github.com/flyersworder/sqlnbfmt/issues/2))
+
+### Changed
+
+- Replaced AST-mutation approach (`ast.NodeTransformer` + `astor` + `black`) with surgical string replacement (`ast.NodeVisitor` + offset-based text splicing), preserving all non-SQL content exactly
+- Removed `astor` and `black` from dependencies — fewer install requirements
+- CI publish now uses PyPI Trusted Publishers (OIDC) instead of API tokens
+- Migrated `tool.uv.dev-dependencies` to `dependency-groups.dev` (PEP 735)
+- Updated `actions/checkout` from v3 to v4
+
+### Added
+
+- Python 3.13 classifier
+- Comment-preservation test case
+
+### Fixed
+
+- Typo in config.yaml: `exeucte_query` → `execute_query`
+
+## [0.1.9] - 2025-01-01
+
+### Changed
+
+- Updated dependencies (attrs, black, referencing, sqlglot, typing-extensions)
+
+## [0.1.8] - 2024-12-01
+
+### Fixed
+
+- First-line indentation error for in-function SQL
+- New-line handling issues in formatted output
+- Introduced `black` formatter to resolve in-function SQL formatting edge cases
+
+## [0.1.7] - 2024-11-01
+
+### Added
+
+- Pre-commit hook support
+- F-string SQL formatting (with and without variables)
+- In-function SQL formatting (e.g., `pd.read_sql(...)`)
+
+## [0.1.0] - 2024-10-01
+
+### Added
+
+- Initial release
+- SQL formatting in Jupyter notebook code cells using sqlglot
+- Support for `%sql` / `%%sql` magic commands
+- Configurable SQL keywords, function names, and formatting options
+- GitHub Actions CI pipeline

{sqlnbfmt-0.4.1/sqlnbfmt.egg-info → sqlnbfmt-0.5.0}/PKG-INFO

@@ -1,31 +1,30 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: sqlnbfmt
-Version: 0.4.1
+Version: 0.5.0
 Summary: A tool to format SQL code in Jupyter notebooks and Marimo notebooks.
-Author-email: Qing <qingye779@gmail.com>
-License: MIT
 Project-URL: Homepage, https://github.com/flyersworder/sqlnbfmt
 Project-URL: Repository, https://github.com/flyersworder/sqlnbfmt
 Project-URL: Changelog, https://github.com/flyersworder/sqlnbfmt/blob/main/CHANGELOG.md
 Project-URL: Issues, https://github.com/flyersworder/sqlnbfmt/issues
-Keywords: sql,jupyter,marimo,notebook,formatter,sqlglot,pre-commit
+Author-email: Qing <qingye779@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: formatter,jupyter,marimo,notebook,pre-commit,sql,sqlglot
 Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Jupyter
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Framework :: Jupyter
+Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
 Requires-Dist: nbformat>=5.10.4
 Requires-Dist: pyyaml>=6.0.2
 Requires-Dist: sqlglot>=25.27.0
-Dynamic: license-file
+Description-Content-Type: text/markdown
 
 # sqlnbfmt
 
@@ -99,19 +98,18 @@ query = "select * from my_special_table where id = 1"
 
 Format SQL cells interactively with [jupyterlab-code-formatter](https://github.com/jupyterlab-contrib/jupyterlab_code_formatter):
 
-1. Install both packages:
 ```bash
 pip install sqlnbfmt jupyterlab-code-formatter
 ```
 
-2. Register the formatter in `~/.jupyter/jupyter_notebook_config.py`:
+That's it — sqlnbfmt auto-registers as a Jupyter server extension. In JupyterLab, use **Edit > Format Cell** or configure format-on-save in Settings > Code Formatter, and select "Apply SQL Notebook Formatter".
+
+The extension uses `[tool.sqlnbfmt]` (including `dialect`) from the nearest `pyproject.toml` of the directory you start Jupyter in. To set the dialect explicitly instead, add this to `~/.jupyter/jupyter_server_config.py`:
 ```python
 from sqlnbfmt.jupyterlab_integration import register
-register()                       # or: register(dialect="postgres")
+register(dialect="postgres")
 ```
 
-3. In JupyterLab, use **Edit > Format Cell** or configure format-on-save in Settings > Code Formatter.
-
 ### Pre-commit Integration
 
 1. Install pre-commit:
@@ -123,7 +121,7 @@ pip install pre-commit
 ```yaml
 repos:
   - repo: https://github.com/flyersworder/sqlnbfmt
-    rev: v0.4.0
+    rev: v0.5.0
     hooks:
       - id: sqlnbfmt
         types: [jupyter]
@@ -135,7 +133,7 @@ To also format Marimo notebooks (Python files), add the Python hook:
         files: '\.py$'  # optionally narrow with: files: 'marimo_.*\.py$'
 ```
 
-All arguments are optional. To specify a dialect or custom config:
+All arguments are optional. Settings in `[tool.sqlnbfmt]` in your `pyproject.toml` are picked up automatically (see [Configuration](#configuration)); alternatively pass them as arguments:
 ```yaml
         args: [--dialect, postgres, --config, config.yaml]
 ```
@@ -164,19 +162,38 @@ Use `--check` in GitHub Actions to enforce formatting:
 
 ## Configuration
 
-`sqlnbfmt` works without any configuration file. A `config.yaml` is only needed to override defaults.
+`sqlnbfmt` works without any configuration. To override defaults, use a `[tool.sqlnbfmt]` table in `pyproject.toml` or a separate YAML file.
+
+### pyproject.toml
 
-Create a `config.yaml` file to customize formatting behavior. [Here](https://github.com/flyersworder/sqlnbfmt/blob/main/config.yaml) is a template.
+```toml
+[tool.sqlnbfmt]
+dialect = "postgres"
+
+[tool.sqlnbfmt.formatting_options]
+indent_width = 2
+```
+
+`sqlnbfmt` searches the current directory and its parents for the nearest `pyproject.toml` with a `[tool.sqlnbfmt]` table, stopping at the repository root (the directory containing `.git`). A `pyproject.toml` without that table is skipped, so a sub-package's file doesn't hide the repository-level configuration. The JupyterLab integration does the same, starting from the Jupyter server's working directory.
+
+### YAML file
+
+Pass a YAML file with `--config config.yaml`. [Here](https://github.com/flyersworder/sqlnbfmt/blob/main/config.yaml) is a template. `--config` also accepts a `.toml` path, which is read from its `[tool.sqlnbfmt]` table.
+
+When `--config` is given, `pyproject.toml` discovery is skipped. Options you don't set keep their defaults, and unknown option names produce a warning.
 
 ### Configuration Options
 
 | Option | Description | Default |
 |--------|-------------|---------|
+| `dialect` | SQL dialect passed to sqlglot (e.g. `postgres`, `mysql`, `bigquery`); `--dialect` overrides it | none (generic SQL) |
 | `sql_keywords` | SQL keywords to recognize and format | Common SQL keywords |
-| `function_names` | Python functions containing SQL code | `read_sql`, `execute`, etc. |
+| `function_names` | Python functions containing SQL code | `read_sql`, `execute`, `sql` (Marimo's `mo.sql`), etc. |
 | `sql_decorators` | Decorators indicating SQL code | `query`, `sql_query`, etc. |
-| `single_line_threshold` | Maximum length before splitting SQL | 80 |
-| `indent_width` | Number of spaces for indentation | 4 |
+| `formatting_options.single_line_threshold` | Maximum length before splitting SQL | 80 |
+| `formatting_options.indent_width` | Number of spaces for indentation | 4 |
+
+`sql_keywords`, `function_names` and `sql_decorators` **replace** the built-in lists rather than extending them. Copy the defaults you still rely on from the [template](https://github.com/flyersworder/sqlnbfmt/blob/main/config.yaml); for example, keep `sql` in `function_names` or Marimo's `mo.sql()` calls stop being formatted.
 
 ## Examples
 
@@ -189,20 +206,20 @@ execute_sql("""SELECT a.col1, b.col2 FROM table_a a JOIN table_b b ON a.id = b.a
 
 After formatting:
 ```python
-execute_sql("""
-SELECT
-  a.col1,
-  b.col2
-FROM
-  table_a AS a
-JOIN
-  table_b AS b
-  ON a.id = b.a_id
-WHERE
-  a.status = 'active'
-ORDER BY
-  a.created_at DESC
-""")
+execute_sql(
+    """
+    SELECT
+      a.col1,
+      b.col2
+    FROM table_a AS a
+    JOIN table_b AS b
+      ON a.id = b.a_id
+    WHERE
+      a.status = 'active'
+    ORDER BY
+      a.created_at DESC
+    """
+)
 ```
 
 ### Marimo Notebook
@@ -220,17 +237,17 @@ After formatting:
 @app.cell
 def _(mo):
     _df = mo.sql(
-    f"""
-    SELECT
-      id,
-      name
-    FROM users
-    WHERE
-      active = 1
-    ORDER BY
-      name
-    """
-)
+        f"""
+        SELECT
+          id,
+          name
+        FROM users
+        WHERE
+          active = 1
+        ORDER BY
+          name
+        """
+    )
     return
 ```
 
@@ -238,7 +255,7 @@ def _(mo):
 
 **SQL not being formatted?**
 - Ensure the string contains at least 2 SQL keywords or a recognizable pattern like `SELECT...FROM`
-- Check that the function name is in the recognized list (use `--config` to add custom ones)
+- Check that the function name is in the recognized list (add custom ones via `function_names` in `[tool.sqlnbfmt]` or `--config`)
 
 **Comments being modified?**
 - Python comments (`#`) are preserved. SQL comments (`--`) inside strings are converted to `/* */` block comments by sqlglot.