Python API¶

pgfmt can be used as a library in Python applications.

`pgfmt.format`¶

`pgfmt.format(sql, style='river')` ¶

Format SQL string according to the specified style.

Parameters:

Name	Type	Description	Default
`sql`	`str`	The SQL string to format.	required
`style`	`str`	The formatting style to use.	`'river'`

Returns:

Type	Description
`str`	The formatted SQL string.

Raises:

Type	Description
`ValueError`	If the style is not supported.

Source code in src/pgfmt/__init__.py

def format(sql: str, style: str = 'river') -> str:
    """Format SQL string according to the specified style.

    Args:
        sql: The SQL string to format.
        style: The formatting style to use.

    Returns:
        The formatted SQL string.

    Raises:
        ValueError: If the style is not supported.

    """
    match style:
        case 'river':
            from pgfmt.river import RiverFormatter

            formatter = RiverFormatter()
        case 'mozilla':
            from pgfmt.mozilla import MozillaFormatter

            formatter = MozillaFormatter()
        case 'aweber':
            from pgfmt.aweber import AWeberFormatter

            formatter = AWeberFormatter()
        case 'dbt':
            from pgfmt.dbt import DbtFormatter

            formatter = DbtFormatter()
        case 'kickstarter':
            from pgfmt.kickstarter import KickstarterFormatter

            formatter = KickstarterFormatter()
        case 'gitlab':
            from pgfmt.gitlab import GitLabFormatter

            formatter = GitLabFormatter()
        case 'mattmc3':
            from pgfmt.mattmc3 import Mattmc3Formatter

            formatter = Mattmc3Formatter()
        case _:
            raise ValueError(f'Unsupported style: {style!r}')
    return formatter.format(sql)

Usage¶

import pgfmt

# Format with the default style (river)
result = pgfmt.format("SELECT a, b FROM t WHERE x = 1")
print(result)

Output:

SELECT a,
       b
  FROM t
 WHERE x = 1;

Choosing a style¶

import pgfmt

sql = "SELECT a, b FROM t WHERE x = 1 AND y = 2"

# Mozilla style
print(pgfmt.format(sql, style='mozilla'))

# dbt style
print(pgfmt.format(sql, style='dbt'))

# mattmc3 style (lowercase river with leading commas)
print(pgfmt.format(sql, style='mattmc3'))

Available styles¶

'river' - Right-aligned keyword river (default)
'aweber' - River with JOINs as river keywords
'mattmc3' - Lowercase river with leading commas
'mozilla' - Left-aligned keywords, 4-space indent
'dbt' - Lowercase mozilla with blank lines between clauses
'gitlab' - Left-aligned keywords, 2-space indent
'kickstarter' - Left-aligned keywords, 2-space indent, ON same line as JOIN

Error handling¶

import pgparse
import pgfmt

# Invalid SQL raises pgparse.PGQueryError
try:
    pgfmt.format("SELEC broken")
except pgparse.PGQueryError as e:
    print(f"Parse error: {e.message} at position {e.position}")

# Unknown style raises ValueError
try:
    pgfmt.format("SELECT 1", style='unknown')
except ValueError as e:
    print(e)  # "Unsupported style: 'unknown'"

Multi-statement input¶

pgfmt.format handles multiple semicolon-delimited statements, returning them separated by blank lines:

import pgfmt

sql = "SELECT 1; SELECT 2; SELECT 3"
print(pgfmt.format(sql))