sqlc-gen-python

https://github.com/sqlc-dev/sqlc-gen-python
Admin
sqlc-gen-python is a plugin for sqlc that generates type-safe Python code from SQL queries and...
Tokens:19,025
Snippets:278
Trust Score:9.2
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Example Module Output

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Example of the Python source code generated by the printModule method.

```python
# Code generated by sqlc
# versions:
#   sqlc dev

import dataclasses
from typing import Optional

@dataclasses.dataclass()
class User:
    id: int
    name: str
```

--------------------------------

### Example sqlc.yaml Configuration

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/configuration.md

A sample configuration file demonstrating how to integrate the sqlc-gen-python plugin.

```yaml
version: "2"
sql:
  - engine: postgresql
    schema: "schema.sql"
    queries: "queries.sql"
plugins:
  - name: py
    wasm:
      url: https://downloads.sqlc.dev/plugin/sqlc-gen-python_1.3.0.wasm
      sha256: fbedae96b5ecae2380a70fb5b925fd4bff58a6cfb1f3140375d098fbab7b3a3c
codegen:
  - out: src/authors
    plugin: py
    options:
      package: authors
      emit_sync_querier: true
      emit_async_querier: true
      emit_pydantic_models: false
      emit_str_enum: false
      query_parameter_limit: 4
      inflection_exclude_table_names:
        - campus
        - meta
```

--------------------------------

### For Loop Output

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Example output for standard and asynchronous for loops.

```python
for row in result:
    yield User(row[0], row[1])

async for row in stream:
    yield User(row[0], row[1])
```

--------------------------------

### Generated Python Row Construction Examples

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Example output of the row construction logic for scalar and struct results.

```python
# Scalar result
column_value = row[0]

# Struct result
User(id=row[0], name=row[1], bio=row[2])
```

--------------------------------

### Import Statement Output

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Example output for standard and from-style import statements.

```python
import sqlalchemy

from typing import Optional, List
from models import User
```

--------------------------------

### Configure sqlc-gen-python in sqlc.yaml

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/README.md

Example configuration for the sqlc-gen-python plugin using a WASM binary.

```yaml
version: "2"
plugins:
  - name: py
    wasm:
      url: https://downloads.sqlc.dev/plugin/sqlc-gen-python_1.3.0.wasm
      sha256: fbedae96b5ecae2380a70fb5b925fd4bff58a6cfb1f3140375d098fbab7b3a3c
sql:
  - schema: "schema.sql"
    queries: "query.sql"
    engine: postgresql
    codegen:
      - out: src/authors
        plugin: py
        options:
          package: authors
          emit_sync_querier: true
          emit_async_querier: true
```

--------------------------------

### Example Usage of Annotation Method

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/public_api.md

Demonstrates how pyType configurations map to Python type annotations.

```go
t := pyType{InnerType: "int", IsArray: true, IsNull: false}
// Annotation() → Optional[List[int]]

t := pyType{InnerType: "str", IsArray: false, IsNull: true}
// Annotation() → Optional[str]
```

--------------------------------

### Example Python Type Annotations

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Demonstrates how different pyType configurations map to Python type hints.

```python
int                    # InnerType="int", IsArray=false, IsNull=false
List[int]              # InnerType="int", IsArray=true, IsNull=false
Optional[int]          # InnerType="int", IsArray=false, IsNull=true
Optional[List[int]]    # InnerType="int", IsArray=true, IsNull=true
```

--------------------------------

### Dictionary Literal Output

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Example output for dictionary literals.

```python
{"p1": id, "p2": name}
```

--------------------------------

### If Statement Output

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Example output for an if statement.

```python
if row is None:
    return None
```

--------------------------------

### SQLAlchemy Placeholder Conversion Example

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/generation_pipeline.md

Demonstrates the transformation of PostgreSQL-style placeholders to SQLAlchemy-compatible named parameters.

```sql
SELECT * FROM users WHERE id = $1 AND name = $2
↓
SELECT * FROM users WHERE id = :p1 AND name = :p2
```

--------------------------------

### Example usage of Singular function

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/public_api.md

Demonstrates singularization of standard words and special cases.

```go
Singular(SingularParams{
    Name: "users",
    Exclusions: []string{},
})
// Returns: "user"

Singular(SingularParams{
    Name: "campus",
    Exclusions: []string{},
})
// Returns: "campus" (special case)
```

--------------------------------

### Python Module Construction Pattern

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Example demonstrating the bottom-up construction of a Python module using the Poet API.

```go
// 1. Create module header
mod := &pyast.Module{
    Body: []*pyast.Node{
        poet.Comment("Code generated by sqlc"),
    },
}

// 2. Add imports
mod.Body = append(mod.Body,
    poet.Node(&pyast.ImportFrom{
        Module: "dataclasses",
        Names: []*pyast.Node{poet.Alias("dataclass")},
    }),
)

// 3. Add class definitions
classNode := &pyast.ClassDef{
    Name: "User",
    Body: []*pyast.Node{
        poet.Node(&pyast.AnnAssign{
            Target: &pyast.Name{Id: "id"},
            Annotation: poet.Name("int"),
        }),
    },
}
mod.Body = append(mod.Body, poet.Node(classNode))

// 4. Wrap in Node and return
return &ast.Node{Node: &ast.Node_Module{Module: mod}}
```

--------------------------------

### Variable Assignment Output

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Example output for standard variable assignments.

```python
CONNECTION = engine.connect()
SQL_TEXT = "SELECT * FROM users"
```

--------------------------------

### Attribute Access Output

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Example output for attribute access operations.

```python
dataclasses.dataclass
self._conn
models.User
```

--------------------------------

### Subscript Access Output

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Example output for subscript access operations.

```python
Optional[int]
List[User]
result[0]
```

--------------------------------

### Function Call Output

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Example output for function calls with various argument types.

```python
dataclasses.dataclass()
optional_call(p1, p2, name="value")
```

--------------------------------

### Generated Python Models

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/code_examples.md

Example of the Python dataclasses and enums generated by the sqlc-gen-python plugin.

```python
# Code generated by sqlc. DO NOT EDIT.
# versions:
#   sqlc dev

import dataclasses
from enum import Enum

@dataclasses.dataclass()
class Author:
    id: int
    name: str
    bio: Optional[str]

class BookStatus(str, Enum):
    DRAFT = "draft"
    PUBLISHED = "published"
    ARCHIVED = "archived"

@dataclasses.dataclass()
class Book:
    id: int
    title: str
    published_date: Optional[datetime.date]
    status: Optional[BookStatus]
```

--------------------------------

### Pydantic Model Usage

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/code_examples.md

Example of generated Pydantic models supporting validation and serialization.

```python
from pydantic import BaseModel

class Author(pydantic.BaseModel):
    id: int
    name: str
    bio: Optional[str]

# Now supports validation and serialization
author_dict = {"id": 1, "name": "Alice", "bio": None}
author = Author(**author_dict)
print(author.model_dump_json())  # {"id":1,"name":"Alice","bio":null}
```

--------------------------------

### SQL colon escaping example

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Shows how colons within string literals are escaped to prevent syntax errors.

```sql
SELECT json_key -> 'field:subfield' FROM data
↓
SELECT json_key -> 'field\:subfield' FROM data
```

--------------------------------

### Annotated Assignment Output

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Example output for annotated assignments typically used for class fields.

```python
id: int
name: Optional[str]  # Optional comment
```

--------------------------------

### Build Python AST Nodes

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Demonstrates constructing assignment and function definition nodes using the generated AST types.

```go
// Build a simple assignment: x = 5
assignmentNode := &pyast.Node{
    Node: &pyast.Node_Assign{
        Assign: &pyast.Assign{
            Targets: []*pyast.Node{
                poet.Name("x"),  // Left side: variable x
            },
            Value: poet.Constant(5),  // Right side: literal 5
        },
    },
}

// Build a method: def get_user(self, id): return None
methodNode := &pyast.FunctionDef{
    Name: "get_user",
    Args: &pyast.Arguments{
        Args: []*pyast.Arg{
            {Arg: "self"},
            {Arg: "id", Annotation: poet.Name("int")},
        },
    },
    Body: []*pyast.Node{
        poet.Return(poet.Constant(nil)),
    },
}
```

--------------------------------

### Project Dependencies

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/module_reference.md

Lists the required external Go modules for the project.

```text
github.com/google/go-cmp v0.6.0
github.com/jinzhu/inflection v1.0.0
github.com/sqlc-dev/plugin-sdk-go v1.23.0
google.golang.org/protobuf v1.34.2
```

--------------------------------

### Configure query parameter limit

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/configuration.md

Demonstrates how parameter count affects method signature generation when query_parameter_limit is set to 2.

```python
# Two parameters -> individual args
def get_user(self, id: int, name: str) -> Optional[User]: ...

# Three parameters -> struct required
def search_users(self, arg: SearchUsersParams) -> Iterator[User]: ...
```

--------------------------------

### Build Queries from SQL

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/generation_pipeline.md

Parses SQL queries into method definitions, handling parameter grouping and return type inference.

```go
func buildQueries(
    conf Config,
    req *plugin.GenerateRequest,
    structs []Struct,
) ([]Query, error)
```

--------------------------------

### Build Models AST

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/generation_pipeline.md

Constructs the AST for models.py, handling imports, enum definitions, and model class generation based on configuration flags.

```go
func buildModelsTree(ctx *pyTmplCtx, i *importer) *pyast.Node
```

--------------------------------

### Configure sqlc-gen-python in sqlc.yaml

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/INDEX.md

Define plugin options within the codegen section of the sqlc configuration file.

```yaml
codegen:
  - plugin: py
    options:
      package: "myapp.db"
      emit_sync_querier: true
      emit_async_querier: true
      emit_pydantic_models: false
      emit_str_enum: false
```

--------------------------------

### Architecture Generation Pipeline

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/INDEX.md

Visual representation of the input-to-output flow for the sqlc-gen-python plugin.

```text
User defines:
  schema.sql       (database schema)
  queries.sql      (SQL queries with :one, :many, etc.)
  sqlc.yaml        (includes plugin config)
       ↓
sqlc invokes plugin with:
  - Parsed catalog (tables, columns, enums)
  - Parsed queries (parameters, result columns)
  - Plugin options (Config struct)
       ↓
Plugin processes:
  1. Build models from catalog tables
  2. Build enums from catalog enums
  3. Build queries from parsed queries
  4. Generate models.py (enums + dataclass/Pydantic models)
  5. Generate query file per source (Querier/AsyncQuerier classes)
       ↓
Output:
  models.py        (all enums and model classes)
  <query>.py       (query methods and Querier/AsyncQuerier classes)
```

--------------------------------

### Build Query AST

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/generation_pipeline.md

Constructs the AST for query-specific Python files, including SQL constants, parameter/return structs, and Querier class definitions.

```go
func buildQueryTree(ctx *pyTmplCtx, i *importer, source string) *pyast.Node
```

--------------------------------

### Convert PostgreSQL placeholders to SQLAlchemy format

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Escapes colons and replaces PostgreSQL-style $N placeholders with SQLAlchemy-style :pN placeholders.

```go
func sqlalchemySQL(s, engine string) string {
    s = strings.ReplaceAll(s, ":", `\\:`)  // Escape colons
    
    if engine == "postgresql" {
        // Replace $N with :pN
        return postgresPlaceholderRegexp.ReplaceAllString(s, ":p$1")
    }
    return s
}
```

--------------------------------

### Handle Parse-Time Configuration and Query Errors

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Validates plugin configuration and query parameters, failing the generation process if errors occur.

```go
if err := json.Unmarshal(req.PluginOptions, &conf); err != nil {
    return nil, err
}

if len(query.Params) > qpl && qpl > 0 {
    return nil, errors.New("query parameter limit exceeded")
}
```

--------------------------------

### Constructing the AST for a Query

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Builds the AST structure for a query method, including the query constant, function definition, class structure, and module assembly.

```go
// 1. Query SQL constant
queryConstant := assignNode("GET_USER", poet.Constant(
    "-- name: GetUser \:one\nSELECT * FROM users WHERE id = :p1\n",
))

// 2. Query method
method := &pyast.FunctionDef{
    Name: "get_user",
    Args: &pyast.Arguments{
        Args: []*pyast.Arg{{Arg: "self"}},
        KwOnlyArgs: []*pyast.Arg{
            {Arg: "id", Annotation: poet.Name("int")},
        },
    },
    Returns: subscriptNode("Optional", poet.Name("User")),
    Body: []*pyast.Node{
        assignNode("row", poet.Node(&pyast.Call{
            Func: poet.Attribute(
                poet.Node(&pyast.Call{
                    Func: typeRefNode("self", "_conn", "execute"),
                    Args: []*pyast.Node{
                        poet.Node(&pyast.Call{
                            Func: typeRefNode("sqlalchemy", "text"),
                            Args: []*pyast.Node{poet.Name("GET_USER")},
                        }),
                        /* dict of params */
                    },
                }),
                "first",
            ),
        })),
        /* if row is None check */
        poet.Return(userRowNode("row")),
    },
}

// 3. Querier class
querier := &pyast.ClassDef{
    Name: "Querier",
    Body: []*pyast.Node{initMethod, poet.Node(method)},
}

// 4. Module
mod := &pyast.Module{
    Body: []*pyast.Node{
        /* imports */
        poet.Node(queryConstant),
        poet.Node(querier),
    },
}
```

--------------------------------

### ArgDictNode Method Signature

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/public_api.md

Generates an AST node representing a dictionary of query parameters, returning nil if no parameters exist.

```go
func (q Query) ArgDictNode() *pyast.Node
```

--------------------------------

### Configure sqlc.yaml

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/code_examples.md

Configuration file for sqlc specifying the PostgreSQL engine, schema, queries, and the Python plugin.

```yaml
version: "2"
sql:
  - engine: postgresql
    schema: "schema.sql"
    queries: "queries.sql"
plugins:
  - name: py
    wasm:
      url: https://downloads.sqlc.dev/plugin/sqlc-gen-python_1.3.0.wasm
codegen:
  - out: src/db
    plugin: py
    options:
      package: db
      emit_sync_querier: true
      emit_async_querier: true
      emit_pydantic_models: false
```

--------------------------------

### Plugin Generate Function Interface

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/README.md

The entry point for the sqlc plugin, receiving a request containing the SQL catalog and configuration, and returning the generated Python files.

```go
func Generate(
    _ context.Context,
    req *plugin.GenerateRequest,
) (*plugin.GenerateResponse, error)
```

--------------------------------

### Print AST to Python Source

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Use the Print function to convert a root AST node into a string of Python source code.

```go
moduleNode := buildModelsTree(ctx, importer)
result := printer.Print(moduleNode, printer.Options{})
pythonCode := string(result.Python)
```

--------------------------------

### Sort Structs and Queries Alphabetically

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Ensures deterministic output for generated files by sorting structs and query methods by name.

```go
sort.Slice(structs, func(i, j int) bool { return structs[i].Name < structs[j].Name })
sort.Slice(qs, func(i, j int) bool { return qs[i].MethodName < qs[j].MethodName })
```

--------------------------------

### Build Models from Tables

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/generation_pipeline.md

Extracts table definitions as model classes, applying inflection rules and mapping columns to types.

```go
func buildModels(conf Config, req *plugin.GenerateRequest) []Struct
```

--------------------------------

### Build Python Models as Strings

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Converts the models tree into a Python string representation for file output.

```go
result := pyprint.Print(buildModelsTree(&tctx, i), pyprint.Options{})
output["models.py"] = string(result.Python)
```

--------------------------------

### Common AST Constructors

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Helper functions for creating specific Python AST elements like names, constants, and operators.

```go
poet.Name("x")  // → Name node with id="x"
```

```go
poet.Constant("hello")     // → String constant
poet.Constant(42)          // → Int constant
poet.Constant(nil)         // → None constant
poet.Constant(true)        // → Bool constant
```

```go
poet.Attribute(poet.Name("obj"), "field")  // → obj.field
```

```go
poet.Return(poet.Name("value"))  // → return value
```

```go
poet.Yield(poet.Name("item"))  // → yield item
```

```go
poet.Await(poet.Call(...))  // → await some_call()
```

```go
poet.Comment("This is a comment")  // → # This is a comment
```

```go
poet.Is()  // → is operator node
```

```go
poet.Alias("ClassName")  // → ClassName
```

--------------------------------

### Define Query Parameter Methods

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/INDEX.md

Demonstrates how query parameters are handled as individual arguments or grouped into a class based on the number of parameters.

```python
# Individual (≤ limit)
def get_user(self, *, id: int) -> Optional[User]: ...

# Grouped (> limit)
class SearchParams:
    query: str
    category: str
    min_price: float

def search(self, arg: SearchParams) -> Iterator[Product]: ...
```

--------------------------------

### Define Configuration Structure

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/configuration.md

The Go struct representing the available configuration options for the Python plugin.

```go
type Config struct {
    EmitExactTableNames         bool     `json:"emit_exact_table_names"`
    EmitSyncQuerier             bool     `json:"emit_sync_querier"`
    EmitAsyncQuerier            bool     `json:"emit_async_querier"`
    Package                     string   `json:"package"`
    Out                         string   `json:"out"`
    EmitPydanticModels          bool     `json:"emit_pydantic_models"`
    EmitStrEnum                 bool     `json:"emit_str_enum"`
    QueryParameterLimit         *int32   `json:"query_parameter_limit"`
    InflectionExcludeTableNames []string `json:"inflection_exclude_table_names"`
}
```

--------------------------------

### Manage conditional package imports

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Ensures SQLAlchemy is imported and conditionally adds async support modules.

```go
pkg["sqlalchemy"] = importSpec{Module: "sqlalchemy"}
```

```go
if i.C.EmitAsyncQuerier {
    pkg["sqlalchemy.ext.asyncio"] = importSpec{Module: "sqlalchemy.ext.asyncio"}
}
```

--------------------------------

### WASM Plugin Entry Point

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/module_reference.md

Main function for the WASM plugin, utilizing the plugin-sdk-go to execute the generation process.

```go
package main

import (
    "github.com/sqlc-dev/plugin-sdk-go/codegen"
    python "github.com/sqlc-dev/sqlc-gen-python/internal"
)

func main() {
    codegen.Run(python.Generate)
}
```

--------------------------------

### Detect standard library imports

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Automatically includes necessary standard library modules based on the types used in the query.

```go
func stdImports(uses func(name string) bool) map[string]importSpec {
    std := make(map[string]importSpec)
    
    if uses("decimal.Decimal") {
        std["decimal"] = importSpec{Module: "decimal"}
    }
    if uses("datetime.date") || uses("datetime.time") || 
       uses("datetime.datetime") || uses("datetime.timedelta") {
        std["datetime"] = importSpec{Module: "datetime"}
    }
    // ... etc
    
    return std
}
```

--------------------------------

### Configure Pydantic Model Generation

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/code_examples.md

Enable Pydantic model generation by setting emit_pydantic_models to true in the sqlc configuration.

```yaml
codegen:
  - out: src/db
    plugin: py
    options:
      package: db
      emit_pydantic_models: true
```

--------------------------------

### Route query commands to execution patterns

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Query commands determine the return type and execution pattern in the generated Python code.

```go
switch q.Cmd {
case ":one":
    // Return Optional[T], call execute().first()
case ":many":
    // Return Iterator[T], iterate execute()
case ":exec":
    // Return None, execute()
case ":execrows":
    // Return int, execute().rowcount
case ":execresult":
    // Return sqlalchemy.engine.Result, execute()
}
```

--------------------------------

### Core Poet Node Constructors

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Functions for wrapping proto messages into AST nodes.

```go
func Node(node proto) *ast.Node
```

```go
func Nodes(nodes ...proto) []*ast.Node
```

--------------------------------

### Project Directory Structure

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/module_reference.md

Visual representation of the repository layout, highlighting the separation between generation logic, configuration, and testing components.

```text
sqlc-gen-python/
├── go.mod                      # Go module definition
├── go.sum                       # Dependency checksums
├── README.md                    # User documentation
├── plugin/
│   └── main.go                 # WASM entry point
├── internal/
│   ├── gen.go                  # Main generation logic (1145 lines)
│   ├── config.go               # Configuration struct
│   ├── imports.go              # Import management
│   ├── postgresql_type.go      # PostgreSQL type mapping
│   ├── ast/
│   │   └── ast.pb.go          # Protobuf-generated AST types
│   ├── inflection/
│   │   └── singular.go        # Word singularization
│   ├── poet/
│   │   └── poet.go            # AST construction helpers
│   └── printer/
│       ├── printer.go          # Code generation/printing
│       └── printer_test.go     # Printer tests
├── examples/                    # Example schema and queries
├── protos/                     # Protocol buffer definitions
└── internal/endtoend/          # End-to-end tests
```

--------------------------------

### Handle Query Results

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/code_examples.md

Patterns for processing results from :one, :many, :exec, :execrows, and :execresult queries.

```python
# Handle :one results
author = q.get_author(1)
if author is None:
    print("Author not found")
else:
    print(author.name)  # Guaranteed non-None

# Handle :many results
for author in q.list_authors():
    print(author.name)  # Each author is non-None

# Handle :exec (no result)
q.delete_author(author_id=1)  # Returns None

# Handle :execrows (count)
deleted_count = q.delete_old_authors()  # Returns int
print(f"Deleted {deleted_count} authors")

# Handle :execresult (raw SQLAlchemy)
result = q.custom_query()  # Returns sqlalchemy.engine.Result
for row in result:
    print(row)
```

--------------------------------

### Configure enum handling with emit_str_enum

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/configuration.md

Shows the difference in generated enum classes based on the emit_str_enum configuration.

```python
class Status(enum.StrEnum):
    OPEN = "open"
    CLOSED = "closed"

# Allows string operations
status = Status.OPEN
message = f"Status is {status}"  # "Status is open"
```

```python
class Status(str, enum.Enum):
    OPEN = "open"
    CLOSED = "closed"

# Still works as string, but slightly different typing
```

--------------------------------

### Multiple Parameter Handling

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Adds individual parameters as keyword-only arguments in the generated Python method.

```go
q.AddArgs(f.Args)
```

```python
def method(self, *, param1: Type1, param2: Type2) -> ReturnType:
    # Parameters must be passed by name
    q.method(param1=value1, param2=value2)
```

--------------------------------

### Reject unsupported CopyFrom feature

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

The plugin explicitly rejects CopyFrom commands as they are not implemented for Python.

```go
if query.Cmd == metadata.CmdCopyFrom {
    return nil, errors.New("Support for CopyFrom in Python is not implemented")
}
```

--------------------------------

### Build Enums from Catalog

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/generation_pipeline.md

Extracts enum types from the database catalog, handling schema-qualified names and sorting alphabetically.

```go
func buildEnums(req *plugin.GenerateRequest) []Enum
```

--------------------------------

### Generate Row Construction Logic

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Generates Python AST nodes for instantiating models or scalar values from database rows.

```go
func (v QueryValue) RowNode(rowVar string) *pyast.Node {
    if !v.IsStruct() {
        // Scalar: return subscript row[0]
        return subscriptNode(rowVar, constantInt(0))
    }
    
    // Struct: return Constructor(field1=row[0], field2=row[1], ...)
    call := &pyast.Call{
        Func: v.Annotation(),
    }
    for i, f := range v.Struct.Fields {
        call.Keywords = append(call.Keywords, &pyast.Keyword{
            Arg: f.Name,
            Value: subscriptNode(rowVar, constantInt(i)),
        })
    }
    return &pyast.Node{Node: &pyast.Node_Call{Call: call}}
}
```

--------------------------------

### Print Function Signature

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/public_api.md

Converts a Python AST node into formatted source code. The options parameter is currently reserved for future use.

```go
func Print(node *ast.Node, options Options) PrintResult
```

--------------------------------

### Configure StrEnum Generation

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/code_examples.md

Enable StrEnum generation for Python 3.11+ by setting emit_str_enum to true.

```yaml
codegen:
  - out: src/db
    plugin: py
    options:
      emit_str_enum: true
```

--------------------------------

### Convert method names to snake_case

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

The plugin uses regex to convert query names into snake_case format.

```go
func methodName(name string) string {
    snake := matchFirstCap.ReplaceAllString(name, "${1}_${2}")
    snake = matchAllCap.ReplaceAllString(snake, "${1}_${2}")
    return strings.ToLower(snake)
}

var matchFirstCap = regexp.MustCompile("(.)([A-Z][a-z]+)")
var matchAllCap = regexp.MustCompile("([a-z0-9])([A-Z])")
```

--------------------------------

### Printing the AST to Python Code

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Converts the constructed AST node into a string of Python source code.

```go
result := printer.Print(&ast.Node{Node: &ast.Node_Module{Module: mod}}, printer.Options{})
pythonCode := string(result.Python)
```

--------------------------------

### Create pyType from Column

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/generation_pipeline.md

Generates a pyType structure based on column metadata, including array status and nullability.

```go
func makePyType(req *plugin.GenerateRequest, col *plugin.Column) pyType
```

--------------------------------

### Define QueryValue Methods

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/public_api.md

Method signatures for handling QueryValue AST generation and metadata.

```go
func (v QueryValue) Annotation() *pyast.Node

func (v QueryValue) EmitStruct() bool

func (v QueryValue) IsStruct() bool

func (v QueryValue) RowNode(rowVar string) *pyast.Node

func (v QueryValue) isEmpty() bool
```

--------------------------------

### Define methodName function signature

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/public_api.md

Defines the signature for converting names to snake_case.

```go
func methodName(name string) string
```

--------------------------------

### func Generate

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/INDEX.md

The main entry point for the sqlc-gen-python plugin, called by the sqlc plugin SDK to process SQL and generate Python files.

```APIDOC
## func Generate(ctx context.Context, req *plugin.GenerateRequest) (*plugin.GenerateResponse, error)

### Description
Processes SQL input and generates corresponding Python files. This function is the primary entry point invoked by the sqlc plugin SDK.

### Parameters
- **ctx** (context.Context) - The execution context.
- **req** (*plugin.GenerateRequest) - The request object containing the SQL and generation configuration.

### Returns
- **(*plugin.GenerateResponse, error)** - Returns a response object containing the generated files or an error if generation fails.
```

--------------------------------

### Log Unsupported Types

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Logs warnings for unknown types during generation without halting the process.

```go
log.Println("unsupported engine type")
return "Any"

log.Printf("unknown PostgreSQL type: %s\n", columnType)
return "Any"
```

--------------------------------

### StrEnum Usage

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/code_examples.md

Generated StrEnum classes can be used directly as strings and support natural comparisons.

```python
from enum import StrEnum

class BookStatus(StrEnum):
    DRAFT = "draft"
    PUBLISHED = "published"
    ARCHIVED = "archived"

# Can be used directly as string
status: str = BookStatus.PUBLISHED
print(f"Status: {status}")  # "Status: published"

# Comparisons work naturally
if BookStatus.DRAFT in [BookStatus.DRAFT, BookStatus.PUBLISHED]:
    print("Valid status")
```

--------------------------------

### Query with Parameters within Limit

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/code_examples.md

SQL query with 4 parameters and the resulting generated Python function signature.

```sql
-- name: SearchBooks :many
SELECT * FROM books 
WHERE author_id = :author_id 
  AND status = :status 
  AND rating >= :min_rating 
  AND rating <= :max_rating
```

```python
def search_books(
    self, 
    author_id: int, 
    status: str, 
    min_rating: float, 
    max_rating: float
) -> Iterator[Book]:
    # Individual parameters because count == limit
    ...
```

--------------------------------

### Match Existing Models for Multiple Columns

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Iterates through existing structs to find a model that matches the query result columns by field count, name, type, and table.

```go
for _, s := range structs {
    // Check if model matches this result
    if len(s.Fields) != len(query.Columns) {
        continue
    }
    
    // Check field count, names, types, and table
    same := true
    for i, f := range s.Fields {
        c := query.Columns[i]
        
        sameName := f.Name == columnName(c, i)
        sameType := f.Type == trimmedPyType
        sameTable := sdk.SameTableName(c.Table, &s.Table, defaultSchema)
        
        if !sameName || !sameType || !sameTable {
            same = false
            break
        }
    }
    
    if same {
        gs = &s  // Found matching model
        break
    }
}
```

--------------------------------

### Single-Parameter Struct Generation

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Configures the argument structure when a query is forced to use a struct, and shows the resulting Python method signature.

```go
gq.Args = []QueryValue{{
    Emit:   true,
    Name:   "arg",  // Struct goes as positional argument
    Struct: columnsToStruct(req, query.Name+"Params", cols),
}}
```

```python
def query_name(self, arg: QueryNameParams) -> ReturnType: ...
```

--------------------------------

### Track Imports with Importer Struct

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/generation_pipeline.md

Method signature for retrieving required imports for a specific file.

```go
func (i *importer) Imports(fileName string) []string
```

--------------------------------

### HashComment Function Usage

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/module_reference.md

Converts input strings into Python-compatible comment formats.

```go
HashComment("This is a comment
on multiple lines")
// Returns: "# This is a comment
# on multiple lines"
```

--------------------------------

### Define Query Internal Structure

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/types.md

Represents a generated query method.

```go
type Query struct {
    Cmd          string       // Query command (:one, :many, :exec, :execrows, :execresult)
    Comments     []string     // SQL comments
    MethodName   string       // Generated method name
    FieldName    string       // SQL text field name
    ConstantName string       // SQL text constant name
    SQL          string       // Processed SQL with SQLAlchemy placeholders
    SourceName   string       // Source SQL file name
    Ret          QueryValue   // Return value type
    Args         []QueryValue // Parameter types
}

// Methods:
// - AddArgs(args *pyast.Arguments) - adds parameters to function signature
// - ArgDictNode() *pyast.Node - generates dict for parameter passing
```

--------------------------------

### Define SQL Queries

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/code_examples.md

SQL queries annotated with sqlc tags to define execution types and parameter mapping.

```sql
-- name: CreateAuthor :exec
INSERT INTO authors (name, bio) VALUES (:name, :bio);

-- name: GetAuthor :one
SELECT id, name, bio FROM authors WHERE id = :author_id;

-- name: ListAuthors :many
SELECT id, name, bio FROM authors ORDER BY name;

-- name: GetAuthorBooks :many
SELECT b.id, b.title, b.published_date, b.status FROM books b WHERE b.author_id = :author_id;
```

--------------------------------

### Single Parameter Python Method

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/code_examples.md

Generated Python method signature for a single parameter query.

```python
def get_author(self, id: int) -> Optional[Author]: ...
```

--------------------------------

### Generate Parameter Name

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/generation_pipeline.md

Retrieves the parameter column name or provides a numbered fallback.

```go
func paramName(p *plugin.Parameter) string
```

--------------------------------

### Define Field Struct

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/public_api.md

Represents a column or field within a generated model.

```go
type Field struct {
    Name    string
    Type    pyType
    Comment string
}
```

--------------------------------

### Define StrEnum

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/types.md

StrEnum implementation for Python 3.11+ when emit_str_enum is enabled.

```python
from enum import StrEnum

class Status(StrEnum):
    OPEN = "open"
    CLOSED = "closed"
```

--------------------------------

### Generated Python Query Interface

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/code_examples.md

Contains the Querier and AsyncQuerier classes for executing SQL operations. Requires sqlalchemy and the corresponding models module.

```python
# Code generated by sqlc. DO NOT EDIT.
# versions:
#   sqlc dev
# source: queries.sql

from typing import Iterator, Optional
import sqlalchemy

from db import models

CREATE_AUTHOR = """-- name: CreateAuthor \:exec
INSERT INTO authors (name, bio) VALUES (:p1, :p2)
"""

GET_AUTHOR = """-- name: GetAuthor \:one
SELECT id, name, bio FROM authors WHERE id = :p1
"""

LIST_AUTHORS = """-- name: ListAuthors \:many
SELECT id, name, bio FROM authors ORDER BY name
"""

GET_AUTHOR_BOOKS = """-- name: GetAuthorBooks \:many
SELECT b.id, b.title, b.published_date, b.status FROM books b WHERE b.author_id = :p1
"""

class Querier:
    def __init__(self, conn: sqlalchemy.engine.Connection):
        self._conn = conn

    def create_author(self, *, name: str, bio: Optional[str]) -> None:
        self._conn.execute(sqlalchemy.text(CREATE_AUTHOR), {"p1": name, "p2": bio})

    def get_author(self, author_id: int) -> Optional[models.Author]:
        row = self._conn.execute(sqlalchemy.text(GET_AUTHOR), {"p1": author_id}).first()
        if row is None:
            return None
        return models.Author(row[0], row[1], row[2])

    def list_authors(self) -> Iterator[models.Author]:
        result = self._conn.execute(sqlalchemy.text(LIST_AUTHORS))
        for row in result:
            yield models.Author(row[0], row[1], row[2])

    def get_author_books(self, author_id: int) -> Iterator[models.Book]:
        result = self._conn.execute(sqlalchemy.text(GET_AUTHOR_BOOKS), {"p1": author_id})
        for row in result:
            yield models.Book(row[0], row[1], row[2], row[3])

class AsyncQuerier:
    def __init__(self, conn: sqlalchemy.ext.asyncio.AsyncConnection):
        self._conn = conn

    async def create_author(self, *, name: str, bio: Optional[str]) -> None:
        await self._conn.execute(sqlalchemy.text(CREATE_AUTHOR), {"p1": name, "p2": bio})

    async def get_author(self, author_id: int) -> Optional[models.Author]:
        row = (await self._conn.execute(sqlalchemy.text(GET_AUTHOR), {"p1": author_id})).first()
        if row is None:
            return None
        return models.Author(row[0], row[1], row[2])

    async def list_authors(self) -> AsyncIterator[models.Author]:
        result = await self._conn.stream(sqlalchemy.text(LIST_AUTHORS))
        async for row in result:
            yield models.Author(row[0], row[1], row[2])

    async def get_author_books(self, author_id: int) -> AsyncIterator[models.Book]:
        result = await self._conn.stream(sqlalchemy.text(GET_AUTHOR_BOOKS), {"p1": author_id})
        async for row in result:
            yield models.Book(row[0], row[1], row[2], row[3])
```

--------------------------------

### Define Individual Query Arguments

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/types.md

Use individual arguments for queries with a parameter count below the query_parameter_limit.

```python
def get_user(self, id: int, name: str) -> Optional[User]: ...
```

--------------------------------

### Execute Only Query Result

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/types.md

Signature for :exec queries returning None.

```python
def delete_user(self, id: int) -> None: ...
```

--------------------------------

### Define modelName function signature

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/public_api.md

Defines the signature for converting underscore-separated names to PascalCase.

```go
func modelName(name string, settings *plugin.Settings) string
```

--------------------------------

### Handle singular inflection exceptions

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Specific table names can be excluded from singularization logic to prevent incorrect transformations.

```go
if strings.ToLower(s.Name) == "campus" {
    return s.Name  // campus → campus (not campi)
}
if strings.ToLower(s.Name) == "meta" {
    return s.Name  // meta → meta (not singular)
}
return upstream.Singular(s.Name)
```

--------------------------------

### Multiple Individual Parameters Python Method

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/code_examples.md

Generated Python method signature for multiple parameters when the count is within the limit.

```python
def search_authors(
    self, 
    query: str, 
    start_date: datetime.date
) -> Iterator[Author]: ...
```

--------------------------------

### Customize Enum Generation with emit_str_enum

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/README.md

Comparison of generated enum code when using enum.StrEnum versus standard Enum classes.

```py
class Status(enum.StrEnum):
    """Venues can be either open or closed"""
    OPEN = "op!en"
    CLOSED = "clo@sed"
```

```py
class Status(str, enum.Enum):
    """Venues can be either open or closed"""
    OPEN = "op!en"
    CLOSED = "clo@sed"
```

--------------------------------

### Customize Model Generation with emit_pydantic_models

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/README.md

Comparison of generated model code when using Pydantic versus standard dataclasses.

```py
from pydantic import BaseModel

class Author(pydantic.BaseModel):
    id: int
    name: str
```

```py
import dataclasses

@dataclasses.dataclass()
class Author:
    id: int
    name: str
```

--------------------------------

### Engine-Specific Type Mapping

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Determines the type mapping strategy based on the database engine, defaulting to 'Any' for non-PostgreSQL engines.

```go
switch req.Settings.Engine {
case "postgresql":
    return postgresType(req, col)
default:
    log.Println("unsupported engine type")
    return "Any"
}
```

--------------------------------

### Define HashComment function signature

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/public_api.md

Defines the signature for converting text into a Python-style hash comment.

```go
func HashComment(s string) string
```

--------------------------------

### Class Definition Printer Method

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Method signature for printing class definitions including decorators, base classes, and body statements.

```go
func (w *writer) printClassDef(cls *ast.ClassDef, indent int32)
```

--------------------------------

### Define postgresType function signature

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/public_api.md

Defines the signature for mapping PostgreSQL column types to Python type strings.

```go
func postgresType(req *plugin.GenerateRequest, col *plugin.Column) string
```

--------------------------------

### Define SingularParams struct

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/public_api.md

Defines the structure for singularization parameters, including the word to process and a list of exclusions.

```go
type SingularParams struct {
    Name       string
    Exclusions []string
}
```

--------------------------------

### Schema-Qualified Table Naming

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Prefixes table names with the schema name if the table resides outside the default schema.

```go
if schema.Name == req.Catalog.DefaultSchema {
    tableName = table.Rel.Name
} else {
    tableName = schema.Name + "_" + table.Rel.Name
}
```

--------------------------------

### Query Parameter Limit Logic

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Determines whether to group query parameters into a struct or use individual arguments based on the QueryParameterLimit configuration.

```go
qpl := 4  // Default
if conf.QueryParameterLimit != nil {
    qpl = int(*conf.QueryParameterLimit)
}

if qpl < 0 {
    return nil, errors.New("invalid query parameter limit")
}

if len(query.Params) > qpl || qpl == 0 {
    // Create params struct
} else {
    // Create individual parameters
}
```

--------------------------------

### Define Synchronous Querier Class

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/generation_pipeline.md

Structure for the synchronous Querier class using sqlalchemy.engine.Connection.

```python
class Querier:
    def __init__(self, conn: sqlalchemy.engine.Connection):
        self._conn = conn

    def method_name(self, ...) -> ReturnType: ...
```

--------------------------------

### Define pyType Struct

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/public_api.md

Represents Python type annotations including array and nullability metadata.

```go
type pyType struct {
    InnerType string
    IsArray   bool
    IsNull    bool
}
```

--------------------------------

### Grouped Parameters Python Class and Method

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/code_examples.md

Generated Python parameter class and method signature for queries exceeding the parameter limit.

```python
class ComplexSearchParams:
    name: str
    start_date: datetime.date
    end_date: datetime.date
    country: str
    verified: bool

def complex_search(self, arg: ComplexSearchParams) -> Iterator[Author]: ...
```

--------------------------------

### Synchronous Database Interaction

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/code_examples.md

Uses the Querier class with a standard SQLAlchemy engine connection to perform CRUD operations.

```python
from sqlalchemy import create_engine
from db.queries import Querier
from db.models import Author

# Create connection
engine = create_engine("postgresql://user:pass@localhost/mydb")

with engine.connect() as conn:
    # Create querier
    q = Querier(conn)
    
    # Insert author
    q.create_author(name="Alice Smith", bio="Science fiction author")
    
    # Fetch single author
    author: Optional[Author] = q.get_author(1)
    if author:
        print(f"Author: {author.name}")
        print(f"Bio: {author.bio}")
    
    # List all authors
    for author in q.list_authors():
        print(f"- {author.name}")
    
    # Fetch books by author
    for book in q.get_author_books(author_id=1):
        print(f"Book: {book.title} ({book.status})")
        if book.published_date:
            print(f"  Published: {book.published_date}")
```

--------------------------------

### Define SQL query constant

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Stores SQL queries as module-level constants with preserved comment headers.

```python
GET_USER = """-- name: GetUser \:one
SELECT * FROM users WHERE id = :p1
"""
```

--------------------------------

### Define Field Internal Structure

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/types.md

Represents a single model field.

```go
type Field struct {
    Name    string  // Field name
    Type    pyType  // Field type with annotations
    Comment string  // SQL comment/documentation
}
```

--------------------------------

### Determine Python Inner Type

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/generation_pipeline.md

Routes column definitions to engine-specific type mappers, defaulting to 'Any' for unsupported engines.

```go
func pyInnerType(req *plugin.GenerateRequest, col *plugin.Column) string
```

--------------------------------

### Define Annotation Method Signature

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/public_api.md

Signature for generating a Python AST node for type annotations.

```go
func (t pyType) Annotation() *pyast.Node
```

--------------------------------

### Generate Anonymous Structs

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/implementation_notes.md

Creates an anonymous struct inline in the query file if no existing model matches the query columns.

```go
if gs == nil {
    gs = columnsToStruct(req, query.Name+"Row", columns)
    emit = true  // Emit the struct in query file
}
```

--------------------------------

### Function Definition Printer Method

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/ast_and_printer.md

Method signature for printing function definitions including arguments, annotations, and body statements.

```go
func (w *writer) printFunctionDef(fn *ast.FunctionDef, indent int32)
```

--------------------------------

### Multiple Individual Parameters SQL Query

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/code_examples.md

SQL definition for a query with multiple parameters below the generation limit.

```sql
-- name: SearchAuthors :many
SELECT * FROM authors 
WHERE name LIKE :query 
  AND created_at >= :start_date
```

--------------------------------

### Define Struct Arguments

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/types.md

Use a struct class for queries exceeding the parameter limit or for single parameter queries requiring a struct.

```python
class GetUsersParams:
    id: int
    name: str
    status: str
    active: bool

def get_users(self, arg: GetUsersParams) -> Iterator[User]: ...
```

```python
class SearchUsersParams:
    query: str

def search_users(self, arg: SearchUsersParams) -> Iterator[User]: ...
```

--------------------------------

### Query Struct Definition

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/public_api.md

Defines the structure of a SQL query within the generator, including metadata, SQL text, and type specifications.

```go
type Query struct {
    Cmd          string
    Comments     []string
    MethodName   string
    FieldName    string
    ConstantName string
    SQL          string
    SourceName   string
    Ret          QueryValue
    Args         []QueryValue
}
```

--------------------------------

### AddArgs Method Signature

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/public_api.md

Modifies a function's argument list to include query parameters based on the query definition.

```go
func (q Query) AddArgs(args *pyast.Arguments) void
```

--------------------------------

### Generate Column Name

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/generation_pipeline.md

Retrieves the column name or provides a fallback identifier based on position.

```go
func columnName(c *plugin.Column, pos int) string
```

--------------------------------

### Configure Inflection Exclusions

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/code_examples.md

Prevent incorrect inflection of specific table names by adding them to inflection_exclude_table_names.

```yaml
codegen:
  - out: src/db
    plugin: py
    options:
      inflection_exclude_table_names:
        - campus
        - meta
        - series
```

--------------------------------

### Type Safety with Type Checkers

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/code_examples.md

Utilize generated type hints to catch errors during static analysis.

```python
# Type checker catches mistakes
author: Author = q.get_author(1)  # OK - returns Optional[Author]
name: str = author.name           # OK - Field is str

# These would be caught by type checker
bad: int = author.name            # Type error: str is not int
bad2 = q.list_authors().id        # Type error: Iterator has no 'id'
```

--------------------------------

### Query with Parameters Exceeding Limit

Source: https://github.com/sqlc-dev/sqlc-gen-python/blob/main/_autodocs/code_examples.md

SQL query with 5 parameters and the resulting generated Python struct parameter.

```sql
-- name: AdvancedSearch :many
SELECT * FROM books 
WHERE author_id = :author_id 
  AND status = :status 
  AND rating >= :min_rating 
  AND rating <= :max_rating
  AND published_date >= :start_date
```

```python
class AdvancedSearchParams:
    author_id: int
    status: str
    min_rating: float
    max_rating: float
    start_date: datetime.date

def advanced_search(self, arg: AdvancedSearchParams) -> Iterator[Book]:
    # Struct parameter because count > limit
    ...
```
Tokens:
Raw