diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 175d8a5f..75e7dc4d 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -111,7 +111,7 @@ jobs: env: HUGO_ENVIRONMENT: production PR_NUMBER: ${{ github.event.number }} - run: hugo --minify --gc --baseURL "https://rayakame.github.io/sqlc-gen-better-python/pr-preview/pr-${PR_NUMBER}/" + run: hugo --minify --gc --baseURL "https://sqlc-gen-better-python.rayakame.dev/pr-preview/pr-${PR_NUMBER}/" - name: Deploy preview uses: rossjrw/pr-preview-action@ffa7509e91a3ec8dfc2e5536c4d5c1acdf7a6de9 # v1.8.1 diff --git a/README.md b/README.md index 635d9381..f1db9175 100644 --- a/README.md +++ b/README.md @@ -16,17 +16,17 @@ aliases and generics, and `enum.StrEnum`). > Besides the [official installation methods](https://docs.sqlc.dev/en/latest/overview/install.html), > the `sqlc` CLI itself is also pip-installable via > [`sqlc-bin`](https://pypi.org/project/sqlc-bin/), which ships the unmodified -> official binaries - no Go toolchain required: `pip install sqlc-bin` (or -> `uv add --dev sqlc-bin`) puts `sqlc` on your PATH, pinnable like any other +> official binaries - no Go toolchain required: `uv add --dev sqlc-bin` (or +> `pip install sqlc-bin`) puts `sqlc` on your PATH, pinnable like any other > Python dependency. ## Documentation -**https://rayakame.github.io/sqlc-gen-better-python/** +**https://sqlc-gen-better-python.rayakame.dev/** -- [Getting Started](https://rayakame.github.io/sqlc-gen-better-python/docs/getting-started/) - install the plugin and generate your first models. -- [Guide](https://rayakame.github.io/sqlc-gen-better-python/docs/guide/) - configuration, drivers, model types, writing queries, and every feature, each with real generated output. -- [Reference](https://rayakame.github.io/sqlc-gen-better-python/docs/reference/) - all configuration options, SQL-to-Python type mappings, and per-driver feature support. +- [Getting Started](https://sqlc-gen-better-python.rayakame.dev/docs/getting-started/) - install the plugin and generate your first models. +- [Guide](https://sqlc-gen-better-python.rayakame.dev/docs/guide/) - configuration, drivers, model types, writing queries, and every feature, each with real generated output. +- [Reference](https://sqlc-gen-better-python.rayakame.dev/docs/reference/) - all configuration options, SQL-to-Python type mappings, and per-driver feature support. Questions or feedback? Join the [Discord](https://discord.gg/hikari). @@ -75,33 +75,33 @@ sql: More options at the [`sqlc` config reference](https://docs.sqlc.dev/en/stable/reference/config.html), and the full plugin option list in the -[configuration reference](https://rayakame.github.io/sqlc-gen-better-python/docs/reference/configuration-options/). +[configuration reference](https://sqlc-gen-better-python.rayakame.dev/docs/reference/configuration-options/). ## Features - **Four model types** - `dataclass`, `attrs`, `msgspec`, or `pydantic` - ([docs](https://rayakame.github.io/sqlc-gen-better-python/docs/guide/model-types/)). + ([docs](https://sqlc-gen-better-python.rayakame.dev/docs/guide/model-types/)). - **Seven drivers** - `asyncpg`, `psycopg_async`, and `psycopg_sync` for PostgreSQL, `aiosqlite` and `sqlite3` for SQLite, plus experimental `turso_async` and `turso_sync` for [Turso](https://github.com/tursodatabase/turso) - ([docs](https://rayakame.github.io/sqlc-gen-better-python/docs/guide/drivers/)). + ([docs](https://sqlc-gen-better-python.rayakame.dev/docs/guide/drivers/)). - **Typed query functions** - one module per query file, one function per query - ([docs](https://rayakame.github.io/sqlc-gen-better-python/docs/guide/writing-queries/)). + ([docs](https://sqlc-gen-better-python.rayakame.dev/docs/guide/writing-queries/)). - **PostgreSQL enums** as `enum.StrEnum` classes - ([docs](https://rayakame.github.io/sqlc-gen-better-python/docs/guide/enums/)). + ([docs](https://sqlc-gen-better-python.rayakame.dev/docs/guide/enums/)). - **Type overrides and converters** - swap a column's Python type, or plug in your own encode/decode functions - ([overrides](https://rayakame.github.io/sqlc-gen-better-python/docs/guide/type-overrides/), - [converters](https://rayakame.github.io/sqlc-gen-better-python/docs/guide/converters/)). + ([overrides](https://sqlc-gen-better-python.rayakame.dev/docs/guide/type-overrides/), + [converters](https://sqlc-gen-better-python.rayakame.dev/docs/guide/converters/)). - **Typed JSON columns** via msgspec structs - ([docs](https://rayakame.github.io/sqlc-gen-better-python/docs/guide/working-with-json/)). + ([docs](https://sqlc-gen-better-python.rayakame.dev/docs/guide/working-with-json/)). - **Optional docstrings** in `google`, `numpy`, or `pep257` convention - ([docs](https://rayakame.github.io/sqlc-gen-better-python/docs/guide/docstrings/)). + ([docs](https://sqlc-gen-better-python.rayakame.dev/docs/guide/docstrings/)). - Generated code passes **pyright strict** and **ruff**. Every [sqlc macro](https://docs.sqlc.dev/en/latest/reference/macros.html) is supported. Which query commands are available depends on the driver - see the -[feature support matrix](https://rayakame.github.io/sqlc-gen-better-python/docs/reference/feature-support/). +[feature support matrix](https://sqlc-gen-better-python.rayakame.dev/docs/reference/feature-support/). ## Development diff --git a/docs/assets/og-image.svg b/docs/assets/og-image.svg new file mode 100644 index 00000000..acdc73de --- /dev/null +++ b/docs/assets/og-image.svg @@ -0,0 +1,20 @@ + + + + + + + + + + + -- name: GetUser :one + SELECT * FROM users WHERE id = $1; + + Type-safe Python + from your SQL + + sqlc-gen-better-python + + A sqlc plugin - typed models and query functions for PostgreSQL and SQLite + diff --git a/docs/content/_index.md b/docs/content/_index.md index 308533f1..890c50df 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -1,5 +1,7 @@ --- title: sqlc-gen-better-python +description: >- + A sqlc plugin that generates type-safe Python from SQL: dataclass, attrs, msgspec, or pydantic models plus fully typed query functions for asyncpg, psycopg, sqlite3, aiosqlite, and turso. layout: hextra-home --- @@ -183,32 +185,11 @@ Generated code is held to the same standard as hand-written code: Set up in three steps {{< /hextra/hero-section >}} -Point `sqlc` at the plugin, pick a driver and a model type, and generate: - -```yaml -# sqlc.yaml -version: "2" -plugins: - - name: python - wasm: - url: https://github.com/rayakame/sqlc-gen-better-python/releases/download/v0.7.0/sqlc-gen-better-python.wasm - sha256: 64ac923cf5f14ebc05bdeb2d1827f14d89a6f3b7180ac08964ef44ff065af5f9 -sql: - - engine: "postgresql" - queries: "query.sql" - schema: "schema.sql" - codegen: - - out: "app/db" - plugin: python - options: - package: "db" - emit_init_file: true - sql_driver: "asyncpg" -``` - -```bash -sqlc generate -``` +1. **Install** the `sqlc` CLI (`uv add --dev sqlc-bin`) and your database driver. +2. **Configure** a `sqlc.yaml` pointing at the plugin's release wasm, your + schema, and your queries. +3. **Generate** - `sqlc generate` writes typed models and one query module per + query file.
diff --git a/docs/content/docs/_index.md b/docs/content/docs/_index.md index e3c6c168..a2cad54e 100644 --- a/docs/content/docs/_index.md +++ b/docs/content/docs/_index.md @@ -1,5 +1,7 @@ --- title: Documentation +description: >- + Documentation for sqlc-gen-better-python, the sqlc plugin that turns your SQL schema and queries into modern, fully typed Python database code. weight: 1 prev: / next: getting-started diff --git a/docs/content/docs/getting-started.md b/docs/content/docs/getting-started.md index 99e294e0..8dd737a8 100644 --- a/docs/content/docs/getting-started.md +++ b/docs/content/docs/getting-started.md @@ -1,5 +1,7 @@ --- title: Getting Started +description: >- + Install sqlc and a database driver, configure sqlc.yaml, and generate your first typed Python queries - step-by-step setup for every supported driver. weight: 1 prev: /docs next: /docs/guide @@ -12,26 +14,47 @@ below and the whole page follows your choice. ## Prerequisites -You need [`sqlc`](https://docs.sqlc.dev/en/latest/overview/install.html) on your -`PATH` and **Python 3.12 or newer** (the generated code uses PEP 695 type aliases -and generics, and `enum.StrEnum`). +You need **Python 3.12 or newer** (the generated code uses PEP 695 type aliases +and generics, and `enum.StrEnum`) and the `sqlc` CLI on your `PATH` - pick +either way to install it: -{{< callout type="info" >}} - Besides the official installation methods, sqlc is also pip-installable via - [sqlc-bin](https://pypi.org/project/sqlc-bin/), which ships the unmodified - official binaries - no Go toolchain required. `uv add --dev sqlc-bin` (or - `pip install sqlc-bin`) puts `sqlc` on your PATH, and the package version - tracks the sqlc version, so you can pin it like any other dependency. -{{< /callout >}} +{{< tabs >}} + + {{< tab name="sqlc-bin (recommended)" >}} + +[sqlc-bin](https://pypi.org/project/sqlc-bin/) ships the unmodified official +`sqlc` binaries as a Python package - no Go toolchain needed, pinnable like +any other dependency: + +```bash +uv add --dev sqlc-bin +``` + + {{< /tab >}} -Then install the database driver you want to use: + {{< tab name="official installation" >}} + +Any of the [official methods](https://docs.sqlc.dev/en/latest/overview/install.html) +works just as well: + +```bash +brew install sqlc +# or +go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest +``` + + {{< /tab >}} + +{{< /tabs >}} + +Then add the database driver you want to use: {{< tabs >}} {{< tab name="asyncpg" >}} ```bash -pip install asyncpg asyncpg-stubs +uv add asyncpg asyncpg-stubs ``` asyncpg has no strict typing of its own; [asyncpg-stubs](https://pypi.org/project/asyncpg-stubs/) @@ -42,7 +65,7 @@ makes the generated annotations work under pyright and mypy. {{< tab name="psycopg_async" >}} ```bash -pip install "psycopg[binary]>=3.2" +uv add "psycopg[binary]>=3.2" ``` {{< /tab >}} @@ -50,7 +73,7 @@ pip install "psycopg[binary]>=3.2" {{< tab name="psycopg_sync" >}} ```bash -pip install "psycopg[binary]>=3.2" +uv add "psycopg[binary]>=3.2" ``` {{< /tab >}} @@ -58,7 +81,7 @@ pip install "psycopg[binary]>=3.2" {{< tab name="aiosqlite" >}} ```bash -pip install aiosqlite +uv add aiosqlite ``` {{< /tab >}} @@ -73,6 +96,8 @@ Nothing to install - sqlite3 is in the standard library. {{< /tabs >}} +Using pip instead of uv? Swap `uv add` for `pip install` in any command above. + ## 1. Configure the plugin The plugin is a WASM binary that `sqlc generate` downloads and runs. Create a diff --git a/docs/content/docs/guide/_index.md b/docs/content/docs/guide/_index.md index fd069b50..12ad2f23 100644 --- a/docs/content/docs/guide/_index.md +++ b/docs/content/docs/guide/_index.md @@ -1,5 +1,7 @@ --- title: Guide +description: >- + Feature guides for sqlc-gen-better-python: drivers, model types, writing queries, enums, type overrides, converters, JSON, docstrings, and naming. weight: 2 prev: /docs/getting-started next: /docs/guide/configuration diff --git a/docs/content/docs/guide/configuration.md b/docs/content/docs/guide/configuration.md index 60a039ed..d1fca9a8 100644 --- a/docs/content/docs/guide/configuration.md +++ b/docs/content/docs/guide/configuration.md @@ -1,5 +1,7 @@ --- title: Configuration +description: >- + How the plugin is wired into sqlc.yaml and how its options are structured, with a full annotated example configuration. weight: 10 prev: /docs/guide next: /docs/guide/drivers diff --git a/docs/content/docs/guide/converters.md b/docs/content/docs/guide/converters.md index 6bba2cee..1518dd83 100644 --- a/docs/content/docs/guide/converters.md +++ b/docs/content/docs/guide/converters.md @@ -1,5 +1,7 @@ --- title: Converters +description: >- + Plug your own encode/decode functions into the generated code to map columns onto custom Python types that a plain override cannot express. weight: 70 prev: /docs/guide/type-overrides next: /docs/guide/working-with-json diff --git a/docs/content/docs/guide/docstrings.md b/docs/content/docs/guide/docstrings.md index 21fff0c1..5c2ef3a1 100644 --- a/docs/content/docs/guide/docstrings.md +++ b/docs/content/docs/guide/docstrings.md @@ -1,5 +1,7 @@ --- title: Docstrings +description: >- + Emit google, numpy, or pep257 docstrings on every generated model, enum, and query function. weight: 80 prev: /docs/guide/working-with-json next: /docs/guide/sqlite-type-conversion diff --git a/docs/content/docs/guide/drivers.md b/docs/content/docs/guide/drivers.md index 61fee8a8..149c3cf8 100644 --- a/docs/content/docs/guide/drivers.md +++ b/docs/content/docs/guide/drivers.md @@ -1,5 +1,7 @@ --- title: Drivers +description: >- + Pick between asyncpg, psycopg_async, psycopg_sync, aiosqlite, sqlite3, and the experimental turso drivers - connection examples and per-driver behavior. weight: 20 prev: /docs/guide/configuration next: /docs/guide/model-types @@ -152,7 +154,7 @@ user = queries.get_field_naming(conn, id_=1) [Turso](https://github.com/tursodatabase/turso) is an SQLite-compatible database engine; its [pyturso](https://pypi.org/project/pyturso/) package -(`pip install pyturso`) mirrors the `sqlite3` module's API and adds a native +(`uv add pyturso`) mirrors the `sqlite3` module's API and adds a native asyncio variant. - `turso_sync` targets the `turso` module, `turso_async` the `turso.aio` module. diff --git a/docs/content/docs/guide/enums.md b/docs/content/docs/guide/enums.md index 29aa101e..5bc7693c 100644 --- a/docs/content/docs/guide/enums.md +++ b/docs/content/docs/guide/enums.md @@ -1,5 +1,7 @@ --- title: Enums +description: >- + PostgreSQL enum types become Python enum.StrEnum classes, wired through the generated models and query parameters. weight: 50 prev: /docs/guide/writing-queries next: /docs/guide/type-overrides diff --git a/docs/content/docs/guide/model-types.md b/docs/content/docs/guide/model-types.md index 0d5b14a1..efee4112 100644 --- a/docs/content/docs/guide/model-types.md +++ b/docs/content/docs/guide/model-types.md @@ -1,5 +1,7 @@ --- title: Model types +description: >- + Generate dataclass, attrs, msgspec, or pydantic models from your SQL schema - what each model type looks like and how to choose one. weight: 30 prev: /docs/guide/drivers next: /docs/guide/writing-queries diff --git a/docs/content/docs/guide/naming.md b/docs/content/docs/guide/naming.md index b2d579cb..d2b1d9cb 100644 --- a/docs/content/docs/guide/naming.md +++ b/docs/content/docs/guide/naming.md @@ -1,5 +1,7 @@ --- title: Naming and identifiers +description: >- + How SQL identifiers become Python names: singularized model classes, field naming, initialisms, and reserved-word escaping. weight: 100 prev: /docs/guide/sqlite-type-conversion --- diff --git a/docs/content/docs/guide/sqlite-type-conversion.md b/docs/content/docs/guide/sqlite-type-conversion.md index f06262ce..1ba5ef14 100644 --- a/docs/content/docs/guide/sqlite-type-conversion.md +++ b/docs/content/docs/guide/sqlite-type-conversion.md @@ -1,5 +1,7 @@ --- title: SQLite type conversion +description: >- + How the SQLite drivers convert dates, decimals, booleans, and blobs: adapters, converters, PARSE_DECLTYPES, speedups, and how turso differs. weight: 90 prev: /docs/guide/docstrings next: /docs/guide/naming diff --git a/docs/content/docs/guide/type-overrides.md b/docs/content/docs/guide/type-overrides.md index 29d6da27..1627e5cf 100644 --- a/docs/content/docs/guide/type-overrides.md +++ b/docs/content/docs/guide/type-overrides.md @@ -1,5 +1,7 @@ --- title: Type overrides +description: >- + Replace the Python type of a specific column or of every column of a SQL type, including nullable handling and custom imports. weight: 60 prev: /docs/guide/enums next: /docs/guide/converters diff --git a/docs/content/docs/guide/working-with-json.md b/docs/content/docs/guide/working-with-json.md index f02f621f..70577d10 100644 --- a/docs/content/docs/guide/working-with-json.md +++ b/docs/content/docs/guide/working-with-json.md @@ -1,5 +1,7 @@ --- title: Working with JSON +description: >- + Turn untyped json/jsonb string columns into fully typed, validated Python objects with converters and msgspec structs. weight: 75 prev: /docs/guide/converters next: /docs/guide/docstrings diff --git a/docs/content/docs/guide/writing-queries.md b/docs/content/docs/guide/writing-queries.md index de39cf50..55aadbc7 100644 --- a/docs/content/docs/guide/writing-queries.md +++ b/docs/content/docs/guide/writing-queries.md @@ -1,5 +1,7 @@ --- title: Writing queries +description: >- + How sqlc query annotations become typed Python functions: :one, :many, :exec, :execrows, :execlastid, :execresult, and :copyfrom, shown with generated code. weight: 40 prev: /docs/guide/model-types next: /docs/guide/enums diff --git a/docs/content/docs/reference/_index.md b/docs/content/docs/reference/_index.md index 9c91167a..244b6432 100644 --- a/docs/content/docs/reference/_index.md +++ b/docs/content/docs/reference/_index.md @@ -1,5 +1,7 @@ --- title: Reference +description: >- + Canonical reference for sqlc-gen-better-python: every configuration option, SQL-to-Python type mappings, and per-driver feature support. weight: 3 prev: /docs/guide sidebar: diff --git a/docs/content/docs/reference/configuration-options.md b/docs/content/docs/reference/configuration-options.md index 548c13c2..d51d2f15 100644 --- a/docs/content/docs/reference/configuration-options.md +++ b/docs/content/docs/reference/configuration-options.md @@ -1,5 +1,7 @@ --- title: Configuration options +description: >- + Every plugin option in one place: its type, default, and meaning, from sql_driver and model_type to overrides and speedups. weight: 10 prev: /docs/reference next: /docs/reference/type-mappings diff --git a/docs/content/docs/reference/feature-support.md b/docs/content/docs/reference/feature-support.md index 064fa802..206b2f75 100644 --- a/docs/content/docs/reference/feature-support.md +++ b/docs/content/docs/reference/feature-support.md @@ -1,5 +1,7 @@ --- title: Feature support +description: >- + Which sqlc macros, query commands, and features each driver supports - the full compatibility matrix. weight: 30 prev: /docs/reference/type-mappings --- diff --git a/docs/content/docs/reference/type-mappings.md b/docs/content/docs/reference/type-mappings.md index 187f05e7..c90e042b 100644 --- a/docs/content/docs/reference/type-mappings.md +++ b/docs/content/docs/reference/type-mappings.md @@ -1,5 +1,7 @@ --- title: Type mappings +description: >- + The built-in SQL-to-Python type mappings for PostgreSQL and SQLite, and what nullable columns and arrays map to. weight: 20 prev: /docs/reference/configuration-options next: /docs/reference/feature-support diff --git a/docs/hugo.yaml b/docs/hugo.yaml index c95ef1cf..d532dd0f 100644 --- a/docs/hugo.yaml +++ b/docs/hugo.yaml @@ -1,9 +1,29 @@ -baseURL: "https://rayakame.github.io/sqlc-gen-better-python/" +baseURL: "https://sqlc-gen-better-python.rayakame.dev/" title: sqlc-gen-better-python enableRobotsTXT: true enableGitInfo: true hasCJKLanguage: false +# The docs use no tags/categories; without this Hugo publishes empty +# /tags/ and /categories/ pages that end up in the sitemap as thin content. +disableKinds: + - taxonomy + - term + +# llms.txt at the site root plus a raw-Markdown render of every page +# (index.md next to each index.html) for AI tooling; both ship with hextra. +outputs: + home: + - html + - llms + page: + - html + - markdown + section: + - html + - rss + - markdown + module: imports: - path: github.com/imfing/hextra @@ -31,7 +51,12 @@ menu: icon: github params: + # params.title feeds og:site_name (the root-level title does not). + title: sqlc-gen-better-python description: A sqlc plugin that generates modern, type-safe Python database code from SQL. + # Social preview card (og:image / twitter:card); source: assets/og-image.svg. + images: + - images/og-image.png navbar: displayTitle: true displayLogo: false diff --git a/docs/layouts/_partials/opengraph.html b/docs/layouts/_partials/opengraph.html new file mode 100644 index 00000000..07914ede --- /dev/null +++ b/docs/layouts/_partials/opengraph.html @@ -0,0 +1,83 @@ +{{/* Copied from hextra's layouts/_partials/opengraph.html. Local override: +the theme emits og:description and og:type as multi-line attribute values, +which `hugo --minify` truncates at the first newline, publishing empty tags. +Keep these two on a single line; the rest matches the theme. */}} + + + + + + +{{- with $.Params.images -}} + {{- range first 6 . }} + {{- with $.Resources.GetMatch . }} + + + {{- else }} + + {{- $image := . -}} + {{- if hasPrefix $image "/" -}} + {{- $image = relURL (strings.TrimPrefix "/" $image) -}} + {{- end -}} + + {{- end }} + {{- end }} +{{- else -}} + {{- with $.Site.Params.images }} + {{- $image := index . 0 -}} + {{- if hasPrefix $image "/" -}} + {{- $image = relURL (strings.TrimPrefix "/" $image) -}} + {{- end -}} + + {{- end }} +{{- end -}} + + +{{- if .IsPage }} +{{- $iso8601 := "2006-01-02T15:04:05-07:00" -}} + +{{ with .PublishDate }} + +{{ end }} +{{ with .Lastmod }} + +{{ end }} +{{- end -}} + +{{- with .Params.audio }}{{ end }} +{{- with .Params.locale }} + +{{ end }} +{{- with .Site.Params.title }} + +{{ end }} +{{- with .Params.videos }} +{{- range . }} + +{{ end }} + +{{ end }} + +{{- /* If it is part of a series, link to related articles */}} +{{- $permalink := .Permalink }} +{{- $siteSeries := .Site.Taxonomies.series }} +{{ with .Params.series }} +{{- range $name := . }} +{{- $series := index $siteSeries ($name | urlize) }} +{{- range $page := first 6 $series.Pages }} +{{- if ne $page.Permalink $permalink }} + +{{ end }} +{{- end }} +{{ end }} + +{{ end }} + +{{- /* Facebook Page Admin ID for Domain Insights */}} +{{- with site.Params.social.facebook_admin }} + +{{ end }} diff --git a/docs/layouts/robots.txt b/docs/layouts/robots.txt new file mode 100644 index 00000000..e89778e8 --- /dev/null +++ b/docs/layouts/robots.txt @@ -0,0 +1,2 @@ +User-agent: * +Sitemap: {{ "sitemap.xml" | absURL }} diff --git a/docs/static/.nojekyll b/docs/static/.nojekyll new file mode 100644 index 00000000..e69de29b diff --git a/docs/static/CNAME b/docs/static/CNAME new file mode 100644 index 00000000..804d266b --- /dev/null +++ b/docs/static/CNAME @@ -0,0 +1 @@ +sqlc-gen-better-python.rayakame.dev diff --git a/docs/static/images/og-image.png b/docs/static/images/og-image.png new file mode 100644 index 00000000..93a98c4f Binary files /dev/null and b/docs/static/images/og-image.png differ