Docs: add info on specifying model kinds in python models (#1518)

* Elaborate on how to specify model kinds in python models

* Add model kind specification to python models concepts doc

* Streamline model configuration ref info

Author: treysp

docs/concepts/models/python_models.md

@@ -37,6 +37,37 @@ The function takes an `ExecutionContext` that is able to run queries and to retr
 
 If the function output is too large, it can also be returned in chunks using Python generators.
 
+## `@model` specification
+
+The arguments provided in the `@model` specification have the same names as those provided in a SQL model's `MODEL` DDL.
+
+Most of the arguments are simply Python-formatted equivalents of the SQL version, but Python model `kind`s are specified with model kind objects. All model kind arguments are listed in the [models configuration reference page](../reference/model_configuration.md#model-kind-properties). A model's `kind` object must be imported at the beginning of the model definition file before use in the model specification.
+
+Supported model kind objects include:
+
+- [ViewKind()](https://sqlmesh.readthedocs.io/en/stable/_readthedocs/html/sqlmesh/core/model/kind.html#ViewKind)
+- [FullKind()](https://sqlmesh.readthedocs.io/en/stable/_readthedocs/html/sqlmesh/core/model/kind.html#FullKind)
+- [SeedKind()](https://sqlmesh.readthedocs.io/en/stable/_readthedocs/html/sqlmesh/core/model/kind.html#SeedKind)
+- [IncrementalByTimeRangeKind()](https://sqlmesh.readthedocs.io/en/stable/_readthedocs/html/sqlmesh/core/model/kind.html#IncrementalByTimeRangeKind)
+- [IncrementalByUniqueKeyKind()](https://sqlmesh.readthedocs.io/en/stable/_readthedocs/html/sqlmesh/core/model/kind.html#IncrementalByUniqueKeyKind)
+- [SCDType2Kind()](https://sqlmesh.readthedocs.io/en/stable/_readthedocs/html/sqlmesh/core/model/kind.html#SCDType2Kind)
+- [EmbeddedKind()](https://sqlmesh.readthedocs.io/en/stable/_readthedocs/html/sqlmesh/core/model/kind.html#EmbeddedKind)
+- [ExternalKind()](https://sqlmesh.readthedocs.io/en/stable/_readthedocs/html/sqlmesh/core/model/kind.html#ExternalKind)
+
+This example demonstrates how to specify an incremental by time range model kind in Python:
+
+```python linenums="1"
+from sqlmesh import ExecutionContext, model
+from sqlmesh.core.model import IncrementalByTimeRangeKind
+
+@model(
+    "docs_example.incremental_model",
+    kind=IncrementalByTimeRangeKind(
+        time_column="ds"
+    )
+)
+```
+
 ## Execution context
 Python models can do anything you want, but it is strongly recommended for all models to be [idempotent](../glossary.md#idempotency). Python models can fetch data from upstream models or even data outside of SQLMesh.
 
@@ -50,7 +81,7 @@ df = context.fetchdf("SELECT * FROM my_table")
 In order to fetch data from an upstream model, you first get the table name using `context`'s `table` method. This returns the appropriate table name for the current runtime [environment](../environments.md):
 
 ```python linenums="1"
-table = context.table("upstream_model")
+table = context.table("docs_example.upstream_model")
 df = context.fetchdf(f"SELECT * FROM {table}")
 ```
 
@@ -63,7 +94,7 @@ In this example, only `upstream_dependency` will be captured, while `another_dep
 ```python linenums="1"
 @model(
     "my_model.with_explicit_dependencies",
-    depends_on=["upstream_dependency"], # captured
+    depends_on=["docs_example.upstream_dependency"], # captured
 )
 def execute(
     context: ExecutionContext,
@@ -74,7 +105,7 @@ def execute(
 ) -> pd.DataFrame:
 
     # ignored due to @model dependency "upstream_dependency"
-    context.table("another_dependency")
+    context.table("docs_example.another_dependency")
 ```
 
 ## Examples
@@ -91,7 +122,7 @@ import pandas as pd
 from sqlmesh import ExecutionContext, model
 
 @model(
-    "basic",
+    "docs_example.basic",
     owner="janet",
     cron="@daily",
     columns={
@@ -123,7 +154,7 @@ import pandas as pd
 from sqlmesh import ExecutionContext, model
 
 @model(
-    "sql_pandas",
+    "docs_example.sql_pandas",
     columns={
         "id": "int",
         "name": "text",
@@ -161,7 +192,7 @@ from pyspark.sql import DataFrame, functions
 from sqlmesh import ExecutionContext, model
 
 @model(
-    "pyspark",
+    "docs_example.pyspark",
     columns={
         "id": "int",
         "name": "text",
@@ -194,7 +225,7 @@ This examples uses the Python generator `yield` to batch the model output:
 
 ```python linenums="1" hl_lines="20"
 @model(
-    "batching",
+    "docs_example.batching",
     columns={
         "id": "int",
     },

docs/guides/configuration.md

@@ -775,6 +775,8 @@ Example configuration specifying a Postgres default connection, in-memory DuckDB
 
 ### Models
 
+#### Model defaults
+
 The `model_defaults` key is **required** and must contain a value for the `dialect` key. All SQL dialects [supported by the SQLGlot library](https://github.com/tobymao/sqlglot/blob/main/sqlglot/dialects/dialect.py) are allowed. Other values are set automatically unless explicitly overridden in the model definition.
 
 All supported `model_defaults` keys are listed in the [models configuration reference page](../reference/model_configuration.md#model-defaults).
@@ -804,82 +806,82 @@ Example configuration:
     )
     ```
 
-#### Model Kind
-The default model kind is 'view' unless overridden with the `kind` key. For more information, refer to [model kinds](../concepts/models/model_kinds.md).
+The default model kind is `VIEW` unless overridden with the `kind` key. For more information on model kinds, refer to [model concepts page](../concepts/models/model_kinds.md).
 
-Example:
+#### Model Kinds
 
-=== "YAML"
+Model kinds are required in each model file's `MODEL` DDL statement. They may optionally be used to specify a default kind in the model defaults configuration key.
 
-    ```yaml linenums="1"
-    model_defaults:
-        dialect: snowflake
-        kind: full
-    ```
+All model kind specification keys are listed in the [models configuration reference page](../reference/model_configuration.md#model-kind-properties).
 
-=== "Python"
+The `VIEW`, `FULL`, and `EMBEDDED` model kinds are specified by name only, while other models kinds require additional parameters and are provided with an array of parameters:
 
-    ```python linenums="1"
-    from sqlmesh.core.config import Config, ModelDefaultsConfig
+=== "YAML"
 
-    config = Config(
-        model_defaults=ModelDefaultsConfig(
-            dialect="snowflake",
-            kind="full",
-        ),
-    )
-    ```
+    `FULL` model only requires a name:
 
-If a kind requires additional parameters it can be provided as an object:
+    ```sql linenums="1"
+    MODEL(
+        name docs_example.full_model,
+        kind FULL
+    );
+    ```
 
-=== "YAML"
+    `INCREMENTAL_BY_TIME_RANGE` requires an array specifying the model's `time_column`:
 
-    ```yaml linenums="1"
-    model_defaults:
-        dialect: snowflake,
-        kind:
-            name: incremental_by_time_range
-            time_column: ds
+    ```sql linenums="1"
+    MODEL(
+        name docs_example.incremental_model,
+        kind INCREMENTAL_BY_TIME_RANGE (
+            time_column ds
+        )
+    );
     ```
 
-=== "Python"
+Python model kinds are specified with model kind objects. Python model kind objects have the same arguments as their SQL counterparts, listed in the [models configuration reference page](../reference/model_configuration.md#model-kind-properties).
 
-    The Python `model_defaults` `kind` argument takes a model kind object with a value of:
+This example demonstrates how to specify an incremental by time range model kind in Python:
 
-    - EmbeddedKind
-    - ExternalKind
-    - FullKind
-    - IncrementalByTimeRangeKind
-    - IncrementalByUniqueKeyKind
-    - IncrementalUnmanagedKind
-    - SeedKind
-    - ViewKind
+=== "Python"
 
     ```python linenums="1"
-    from sqlmesh.core.config import (
-        Config,
-        ModelDefaultsConfig,
-        IncrementalByTimeRangeKind
-    )
-
-    config = Config(
-        model_defaults=ModelDefaultsConfig(
-            dialect="snowflake",
-            kind=IncrementalByTimeRangeKind(
-                time_column="ds",
-            ),
-        ),
+    from sqlmesh import ExecutionContext, model
+    from sqlmesh.core.model import IncrementalByTimeRangeKind
+
+    @model(
+        "docs_example.incremental_model",
+        kind=IncrementalByTimeRangeKind(
+            time_column="ds"
+        )
     )
     ```
 
+Learn more about specifying Python models at the [Python models concepts page](../concepts/models/python_models.md#model-specification).
+
 ### Debug mode
 
-To enable debug mode set the `SQLMESH_DEBUG` environment variable to one of the following values: `1`, `true`, `t`, `yes` or `y`.
+To enable debug mode set the `SQLMESH_DEBUG` environment variable to one of the following values: "1", "true", "t", "yes" or "y".
 
-Enabling this mode ensures that full backtraces are printed when using CLI. Additionally, the default log level is set to `DEBUG` when this mode is enabled.
+Enabling this mode ensures that full backtraces are printed when using CLI. The default log level is set to `DEBUG` when this mode is enabled.
 
 Example enabling debug mode for the CLI command `sqlmesh plan`:
 
-```bash
-$ SQLMESH_DEBUG=1 sqlmesh plan
-```
+=== "Bash"
+
+    ```bash
+    $ SQLMESH_DEBUG=1 sqlmesh plan
+    ```
+
+=== "MS Powershell"
+
+    ```powershell
+    PS> $env:SQLMESH_DEBUG=1
+    PS> sqlmesh plan
+    ```
+
+=== "MS CMD"
+
+    ```cmd
+    C:\> set SQLMESH_DEBUG=1
+    C:\> sqlmesh plan
+    ```

docs/reference/configuration.md

@@ -172,7 +172,9 @@ For example, you might have a specific connection where your tests should run re
 
 ## Debug mode
 
-To enable debug mode set the `SQLMESH_DEBUG` environment variable to one of the following values: "1", "true", "t", "yes" or "y". Enabling this mode ensures that full backtraces are printed when using CLI. The default log level is set to `DEBUG` when this mode is enabled.
+To enable debug mode set the `SQLMESH_DEBUG` environment variable to one of the following values: "1", "true", "t", "yes" or "y".
+
+Enabling this mode ensures that full backtraces are printed when using CLI. The default log level is set to `DEBUG` when this mode is enabled.
 
 Example enabling debug mode for the CLI command `sqlmesh plan`: