@alloy-js/python 0.5.0-dev.0 → 0.5.0-dev.1

package/docs/api/components/ClassDeclaration.md

@@ -10,6 +10,7 @@ Create a Python class declaration.
 
   <ClassDeclaration
     bases={Children[]}
+    decorators={Children[]}
     doc={Children}
     name={string | Namekey}
     refkey={Refkey | Refkey[]}
@@ -24,6 +25,7 @@ Create a Python class declaration.
 
   ClassDeclaration({
     bases: Children[],
+    decorators: Children[],
     doc: Children,
     name: string | Namekey,
     refkey: Refkey | Refkey[],
@@ -32,13 +34,14 @@ Create a Python class declaration.
 
 ## Props
 
-|          |                                                                                            |                                                                                             |
-| -------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
-| bases    | optional [Children](../../../core/types/children/)\[]                                      | The base classes that this class inherits from.                                             |
-| children | optional [Children](../../../core/types/children/)                                         |                                                                                             |
-| doc      | optional [Children](../../../core/types/children/)                                         | Documentation for this declaration                                                          |
-| name     | string \| [Namekey](../../../core/types/namekey/)                                          | The base name of this declaration. May change depending on naming policy and any conflicts. |
-| refkey   | optional [Refkey](../../../core/types/refkey/) \| [Refkey](../../../core/types/refkey/)\[] | The refkey or array of refkeys for this declaration.                                        |
+|            |                                                                                            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ---------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| bases      | optional [Children](../../../core/types/children/)\[]                                      | The base classes that this class inherits from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| children   | optional [Children](../../../core/types/children/)                                         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| decorators | optional [Children](../../../core/types/children/)\[]                                      | Decorators rendered above the `class` keyword, in source order — `decorators[0]` is topmost. By Python’s bottom-up application order, the topmost entry is the outermost decorator (applied last). Each entry should produce a complete decorator line (typically starting with `@`). Falsy entries are skipped, so conditional decorators can be provided inline when needed. Wrappers like [`DataclassDeclaration`](DataclassDeclaration.md) build their intrinsic decorator (e.g. `@dataclass(...)`) and append it to this list at the position that keeps `@dataclass` closest to the class — i.e. user `decorators` end up **above** the intrinsic one, matching how Pydantic’s `@field_validator` sits above `@classmethod` on methods. Do **not** pass a wrapper’s intrinsic decorator here. For example, when using [`DataclassDeclaration`](DataclassDeclaration.md), do not include `@dataclass(...)` in `decorators` — the component renders it for you, and stacking it twice would produce invalid Python. |
+| doc        | optional [Children](../../../core/types/children/)                                         | Documentation for this declaration                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| name       | string \| [Namekey](../../../core/types/namekey/)                                          | The base name of this declaration. May change depending on naming policy and any conflicts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| refkey     | optional [Refkey](../../../core/types/refkey/) \| [Refkey](../../../core/types/refkey/)\[] | The refkey or array of refkeys for this declaration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 
 ## Remarks
 

package/docs/api/components/ClassEnumDeclaration.md

@@ -13,6 +13,7 @@ This generates enums using the `class Name(Enum):` syntax with member definition
   <ClassEnumDeclaration
     auto
     baseType={"Enum" | "IntEnum" | "StrEnum" | "Flag" | "IntFlag"}
+    decorators={Children[]}
     doc={Children}
     members={Array<EnumMemberProps>}
    />
@@ -27,6 +28,7 @@ This generates enums using the `class Name(Enum):` syntax with member definition
   ClassEnumDeclaration({
     auto: boolean,
     baseType: "Enum" | "IntEnum" | "StrEnum" | "Flag" | "IntFlag",
+    decorators: Children[],
     doc: Children,
     members: Array<EnumMemberProps>,
   }).children(children)
@@ -34,12 +36,13 @@ This generates enums using the `class Name(Enum):` syntax with member definition
 
 ## Props
 
-|          |                                                                  |                                                                                                         |
-| -------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| auto     | optional boolean                                                 | Indicates that the enum members should be auto-generated.                                               |
-| baseType | optional “Enum” \| “IntEnum” \| “StrEnum” \| “Flag” \| “IntFlag” | The base type of the enum. One of: ‘Enum’, ‘IntEnum’, ‘StrEnum’, ‘Flag’, ‘IntFlag’. Defaults to ‘Enum’. |
-| doc      | optional [Children](../../../core/types/children/)               | Optional docstring for the enum.                                                                        |
-| members  | optional Array<[EnumMemberProps](../enummember/)>                | Members of the enum as an array of objects.                                                             |
+|            |                                                                  |                                                                                                                                                                                                                                                           |
+| ---------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| auto       | optional boolean                                                 | Indicates that the enum members should be auto-generated.                                                                                                                                                                                                 |
+| baseType   | optional “Enum” \| “IntEnum” \| “StrEnum” \| “Flag” \| “IntFlag” | The base type of the enum. One of: ‘Enum’, ‘IntEnum’, ‘StrEnum’, ‘Flag’, ‘IntFlag’. Defaults to ‘Enum’.                                                                                                                                                   |
+| decorators | optional [Children](../../../core/types/children/)\[]            | Decorators rendered above `class <Name>(<BaseType>):`. See \[unresolved link] for the source-order and falsy skip semantics. Not available on functional-enum syntax (`Name = Enum(...)`), which is a variable assignment rather than a class definition. |
+| doc        | optional [Children](../../../core/types/children/)               | Optional docstring for the enum.                                                                                                                                                                                                                          |
+| members    | optional Array<[EnumMemberProps](../enummember/)>                | Members of the enum as an array of objects.                                                                                                                                                                                                               |
 
 ## Examples
 

package/docs/api/components/ClassMethodDeclaration.md

@@ -8,7 +8,7 @@ A Python class method declaration component.
   import { ClassMethodDeclaration } from "@alloy-js/python";
 
 
-  <ClassMethodDeclaration abstract async />
+  <ClassMethodDeclaration abstract async decorators={Children[]} />
   ```
 
 * stc
@@ -20,12 +20,14 @@ A Python class method declaration component.
   ClassMethodDeclaration({
     abstract: boolean,
     async: boolean,
+    decorators: Children[],
   }).children(children)
   ```
 
 ## Props
 
-|          |                  |                                       |
-| -------- | ---------------- | ------------------------------------- |
-| abstract | optional boolean |                                       |
-| async    | optional boolean | Indicates that the function is async. |
+|            |                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ---------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| abstract   | optional boolean                                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| async      | optional boolean                                      | Indicates that the function is async.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| decorators | optional [Children](../../../core/types/children/)\[] | Decorators rendered above `def`, in source order — `decorators[0]` is topmost. By Python’s bottom-up application order, the topmost entry is the **outermost** decorator (applied last) and wraps the result of every decorator below it. Each entry should produce a complete decorator line (typically starting with `@`). Falsy entries (other than `0`) are skipped, so conditional decorators can be provided inline when needed. When used through wrappers that emit an intrinsic decorator ([`ClassMethodDeclaration`](ClassMethodDeclaration.md) → `@classmethod`, [`StaticMethodDeclaration`](StaticMethodDeclaration.md) → `@staticmethod`, [`PropertyDeclaration`](PropertyDeclaration.md) → `@property`), these decorators are rendered **above** the intrinsic line — the correct position for Pydantic’s `@field_validator` / `@model_validator` and other wrappers that must see the underlying function, not a descriptor. When used on plain [`MethodDeclaration`](MethodDeclaration.md) / [`FunctionDeclaration`](FunctionDeclaration.md), these decorators are rendered above `@abstractmethod` (if `abstract` is set) and above `def`. Do **not** pass intrinsic decorators here — i.e. `@classmethod`, `@staticmethod`, `@property`, or `@abstractmethod`. Those are emitted by the matching component ([`ClassMethodDeclaration`](ClassMethodDeclaration.md), [`StaticMethodDeclaration`](StaticMethodDeclaration.md), [`PropertyDeclaration`](PropertyDeclaration.md), or the `abstract` flag) and would otherwise be stacked twice in the output, producing invalid Python. |

package/docs/api/components/DataclassDeclaration.md

@@ -36,7 +36,7 @@ class User:
   import { DataclassDeclaration } from "@alloy-js/python";
 
 
-  <DataclassDeclaration bases={Children[]} />
+  <DataclassDeclaration bases={Children[]} decorators={Children[]} />
   ```
 
 * stc
@@ -45,11 +45,15 @@ class User:
   import { DataclassDeclaration } from "@alloy-js/python/stc";
 
 
-  DataclassDeclaration({ bases: Children[] }).children(children)
+  DataclassDeclaration({
+    bases: Children[],
+    decorators: Children[],
+  }).children(children)
   ```
 
 ## Props
 
-|       |                                                       |                                                 |
-| ----- | ----------------------------------------------------- | ----------------------------------------------- |
-| bases | optional [Children](../../../core/types/children/)\[] | The base classes that this class inherits from. |
+|            |                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ---------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| bases      | optional [Children](../../../core/types/children/)\[] | The base classes that this class inherits from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| decorators | optional [Children](../../../core/types/children/)\[] | Decorators rendered above the `class` keyword, in source order — `decorators[0]` is topmost. By Python’s bottom-up application order, the topmost entry is the outermost decorator (applied last). Each entry should produce a complete decorator line (typically starting with `@`). Falsy entries are skipped, so conditional decorators can be provided inline when needed. Wrappers like [`DataclassDeclaration`](DataclassDeclaration.md) build their intrinsic decorator (e.g. `@dataclass(...)`) and append it to this list at the position that keeps `@dataclass` closest to the class — i.e. user `decorators` end up **above** the intrinsic one, matching how Pydantic’s `@field_validator` sits above `@classmethod` on methods. Do **not** pass a wrapper’s intrinsic decorator here. For example, when using [`DataclassDeclaration`](DataclassDeclaration.md), do not include `@dataclass(...)` in `decorators` — the component renders it for you, and stacking it twice would produce invalid Python. |

package/docs/api/components/DunderMethodDeclaration.md

@@ -8,7 +8,7 @@ A Python dunder method declaration.
   import { DunderMethodDeclaration } from "@alloy-js/python";
 
 
-  <DunderMethodDeclaration abstract async />
+  <DunderMethodDeclaration abstract async decorators={Children[]} />
   ```
 
 * stc
@@ -20,12 +20,14 @@ A Python dunder method declaration.
   DunderMethodDeclaration({
     abstract: boolean,
     async: boolean,
+    decorators: Children[],
   }).children(children)
   ```
 
 ## Props
 
-|          |                  |                                       |
-| -------- | ---------------- | ------------------------------------- |
-| abstract | optional boolean |                                       |
-| async    | optional boolean | Indicates that the function is async. |
+|            |                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ---------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| abstract   | optional boolean                                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| async      | optional boolean                                      | Indicates that the function is async.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| decorators | optional [Children](../../../core/types/children/)\[] | Decorators rendered above `def`, in source order — `decorators[0]` is topmost. By Python’s bottom-up application order, the topmost entry is the **outermost** decorator (applied last) and wraps the result of every decorator below it. Each entry should produce a complete decorator line (typically starting with `@`). Falsy entries (other than `0`) are skipped, so conditional decorators can be provided inline when needed. When used through wrappers that emit an intrinsic decorator ([`ClassMethodDeclaration`](ClassMethodDeclaration.md) → `@classmethod`, [`StaticMethodDeclaration`](StaticMethodDeclaration.md) → `@staticmethod`, [`PropertyDeclaration`](PropertyDeclaration.md) → `@property`), these decorators are rendered **above** the intrinsic line — the correct position for Pydantic’s `@field_validator` / `@model_validator` and other wrappers that must see the underlying function, not a descriptor. When used on plain [`MethodDeclaration`](MethodDeclaration.md) / [`FunctionDeclaration`](FunctionDeclaration.md), these decorators are rendered above `@abstractmethod` (if `abstract` is set) and above `def`. Do **not** pass intrinsic decorators here — i.e. `@classmethod`, `@staticmethod`, `@property`, or `@abstractmethod`. Those are emitted by the matching component ([`ClassMethodDeclaration`](ClassMethodDeclaration.md), [`StaticMethodDeclaration`](StaticMethodDeclaration.md), [`PropertyDeclaration`](PropertyDeclaration.md), or the `abstract` flag) and would otherwise be stacked twice in the output, producing invalid Python. |

package/docs/api/components/FunctionDeclaration.md

@@ -8,7 +8,7 @@ A Python function declaration.
   import { FunctionDeclaration } from "@alloy-js/python";
 
 
-  <FunctionDeclaration async />
+  <FunctionDeclaration async decorators={Children[]} />
   ```
 
 * stc
@@ -17,14 +17,18 @@ A Python function declaration.
   import { FunctionDeclaration } from "@alloy-js/python/stc";
 
 
-  FunctionDeclaration({ async: boolean }).children(children)
+  FunctionDeclaration({
+    async: boolean,
+    decorators: Children[],
+  }).children(children)
   ```
 
 ## Props
 
-|       |                  |                                       |
-| ----- | ---------------- | ------------------------------------- |
-| async | optional boolean | Indicates that the function is async. |
+|            |                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ---------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| async      | optional boolean                                      | Indicates that the function is async.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| decorators | optional [Children](../../../core/types/children/)\[] | Decorators rendered above `def`, in source order — `decorators[0]` is topmost. By Python’s bottom-up application order, the topmost entry is the **outermost** decorator (applied last) and wraps the result of every decorator below it. Each entry should produce a complete decorator line (typically starting with `@`). Falsy entries (other than `0`) are skipped, so conditional decorators can be provided inline when needed. When used through wrappers that emit an intrinsic decorator ([`ClassMethodDeclaration`](ClassMethodDeclaration.md) → `@classmethod`, [`StaticMethodDeclaration`](StaticMethodDeclaration.md) → `@staticmethod`, [`PropertyDeclaration`](PropertyDeclaration.md) → `@property`), these decorators are rendered **above** the intrinsic line — the correct position for Pydantic’s `@field_validator` / `@model_validator` and other wrappers that must see the underlying function, not a descriptor. When used on plain [`MethodDeclaration`](MethodDeclaration.md) / [`FunctionDeclaration`](FunctionDeclaration.md), these decorators are rendered above `@abstractmethod` (if `abstract` is set) and above `def`. Do **not** pass intrinsic decorators here — i.e. `@classmethod`, `@staticmethod`, `@property`, or `@abstractmethod`. Those are emitted by the matching component ([`ClassMethodDeclaration`](ClassMethodDeclaration.md), [`StaticMethodDeclaration`](StaticMethodDeclaration.md), [`PropertyDeclaration`](PropertyDeclaration.md), or the `abstract` flag) and would otherwise be stacked twice in the output, producing invalid Python. |
 
 ## Remarks
 

package/docs/api/components/FutureStatement.md

@@ -33,7 +33,7 @@ Use this in the `futureImports` prop of SourceFile to ensure proper placement.
 ## Example
 
 ```tsx
-<SourceFile path="models.py" futureImports={<FutureStatement feature="annotations" />}>
+<SourceFile path="models.py" futureImports={[<FutureStatement feature="annotations" />]}>
   <ClassDeclaration name="User">
     <PropertyDeclaration name="manager" type="User" />
   </ClassDeclaration>

package/docs/api/components/MethodDeclaration.md

@@ -10,7 +10,7 @@ Shared base props for all method-like declarations.
   import { MethodDeclaration } from "@alloy-js/python";
 
 
-  <MethodDeclaration abstract async />
+  <MethodDeclaration abstract async decorators={Children[]} />
   ```
 
 * stc
@@ -19,15 +19,20 @@ Shared base props for all method-like declarations.
   import { MethodDeclaration } from "@alloy-js/python/stc";
 
 
-  MethodDeclaration({ abstract: boolean, async: boolean }).children(children)
+  MethodDeclaration({
+    abstract: boolean,
+    async: boolean,
+    decorators: Children[],
+  }).children(children)
   ```
 
 ## Props
 
-|          |                  |                                        |
-| -------- | ---------------- | -------------------------------------- |
-| abstract | optional boolean | Indicates that the method is abstract. |
-| async    | optional boolean | Indicates that the function is async.  |
+|            |                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ---------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| abstract   | optional boolean                                      | Indicates that the method is abstract.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| async      | optional boolean                                      | Indicates that the function is async.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| decorators | optional [Children](../../../core/types/children/)\[] | Decorators rendered above `def`, in source order — `decorators[0]` is topmost. By Python’s bottom-up application order, the topmost entry is the **outermost** decorator (applied last) and wraps the result of every decorator below it. Each entry should produce a complete decorator line (typically starting with `@`). Falsy entries (other than `0`) are skipped, so conditional decorators can be provided inline when needed. When used through wrappers that emit an intrinsic decorator ([`ClassMethodDeclaration`](ClassMethodDeclaration.md) → `@classmethod`, [`StaticMethodDeclaration`](StaticMethodDeclaration.md) → `@staticmethod`, [`PropertyDeclaration`](PropertyDeclaration.md) → `@property`), these decorators are rendered **above** the intrinsic line — the correct position for Pydantic’s `@field_validator` / `@model_validator` and other wrappers that must see the underlying function, not a descriptor. When used on plain [`MethodDeclaration`](MethodDeclaration.md) / [`FunctionDeclaration`](FunctionDeclaration.md), these decorators are rendered above `@abstractmethod` (if `abstract` is set) and above `def`. Do **not** pass intrinsic decorators here — i.e. `@classmethod`, `@staticmethod`, `@property`, or `@abstractmethod`. Those are emitted by the matching component ([`ClassMethodDeclaration`](ClassMethodDeclaration.md), [`StaticMethodDeclaration`](StaticMethodDeclaration.md), [`PropertyDeclaration`](PropertyDeclaration.md), or the `abstract` flag) and would otherwise be stacked twice in the output, producing invalid Python. |
 
 ## Remarks
 

package/docs/api/components/PropertyDeclaration.md

@@ -10,6 +10,7 @@ Declares a Python property with optional getter, setter, and deleter methods.
 
   <PropertyDeclaration
     abstract
+    decorators={Children[]}
     doc={Children}
     name="string"
     refkey={Refkey}
@@ -27,6 +28,7 @@ Declares a Python property with optional getter, setter, and deleter methods.
 
   PropertyDeclaration({
     abstract: boolean,
+    decorators: Children[],
     doc: Children,
     name: string,
     refkey: Refkey,
@@ -36,11 +38,12 @@ Declares a Python property with optional getter, setter, and deleter methods.
 
 ## Props
 
-|          |                                                    |   |
-| -------- | -------------------------------------------------- | - |
-| abstract | optional boolean                                   |   |
-| children | optional [Children](../../../core/types/children/) |   |
-| doc      | optional [Children](../../../core/types/children/) |   |
-| name     | string                                             |   |
-| refkey   | optional [Refkey](../../../core/types/refkey/)     |   |
-| type     | optional [Children](../../../core/types/children/) |   |
+|            |                                                       |                                                                                                                                                                                                                |
+| ---------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| abstract   | optional boolean                                      |                                                                                                                                                                                                                |
+| children   | optional [Children](../../../core/types/children/)    |                                                                                                                                                                                                                |
+| decorators | optional [Children](../../../core/types/children/)\[] | Decorators rendered above the intrinsic `@property` line, in source order (`decorators[0]` is topmost / applied last). Use for decorators that wrap the resulting property, e.g. Pydantic’s `@computed_field`. |
+| doc        | optional [Children](../../../core/types/children/)    |                                                                                                                                                                                                                |
+| name       | string                                                |                                                                                                                                                                                                                |
+| refkey     | optional [Refkey](../../../core/types/refkey/)        |                                                                                                                                                                                                                |
+| type       | optional [Children](../../../core/types/children/)    |                                                                                                                                                                                                                |

package/docs/api/components/PydanticClassDeclaration.md

@@ -0,0 +1,146 @@
+# PydanticClassDeclaration
+
+Renders a Python class that subclasses Pydantic’s `BaseModel`: `class Name(BaseModel): ...`.
+
+When `bases` is omitted, the class extends `pydanticModule["."].BaseModel`. Pass `bases` to inherit from another generated class (or to combine bases explicitly).
+
+Optional `modelConfig={{...}}` and top-level config props (for example `frozen`, `strict`, `extra`) emit `model_config = ConfigDict(...)` for common Pydantic v2 model settings (see [PydanticModelConfigDictProps](../../types/pydanticmodelconfigdictprops/)). When both are used, top-level props override `modelConfig` keys.
+
+Fields are ordinary class body declarations; use `pydanticModule["."].Field` in initializers when you need `Field(...)`.
+
+* jsx
+
+  ```tsx
+  import { PydanticClassDeclaration } from "@alloy-js/python";
+
+
+  <PydanticClassDeclaration
+    aliasGenerator="string"
+    arbitraryTypesAllowed
+    bases={Children[]}
+    coerceNumbersToStr
+    decorators={Children[]}
+    extra={"allow" | "forbid" | "ignore"}
+    fromAttributes
+    frozen
+    hideInputInErrors
+    jsonSchemaExtra={Record<string, unknown>}
+    locByAlias
+    modelConfig={PydanticModelConfigDictProps}
+    modelConfigExpression={Children}
+    populateByName
+    revalidateInstances={"always" | "never" | "subclass-instances"}
+    serJsonBytes={"utf8" | "base64" | "hex"}
+    serJsonInfNan={"null" | "constants" | "strings"}
+    strMaxLength={number}
+    strMinLength={number}
+    strStripWhitespace
+    strToLower
+    strToUpper
+    strict
+    useEnumValues
+    valJsonBytes={"utf8" | "base64" | "hex"}
+    validateAssignment
+    validateDefault
+    validateReturn
+   />
+  ```
+
+* stc
+
+  ```ts
+  import { PydanticClassDeclaration } from "@alloy-js/python/stc";
+
+
+  PydanticClassDeclaration({
+    aliasGenerator: string,
+    arbitraryTypesAllowed: boolean,
+    bases: Children[],
+    coerceNumbersToStr: boolean,
+    decorators: Children[],
+    extra: "allow" | "forbid" | "ignore",
+    fromAttributes: boolean,
+    frozen: boolean,
+    hideInputInErrors: boolean,
+    jsonSchemaExtra: Record<string, unknown>,
+    locByAlias: boolean,
+    modelConfig: PydanticModelConfigDictProps,
+    modelConfigExpression: Children,
+    populateByName: boolean,
+    revalidateInstances: "always" | "never" | "subclass-instances",
+    serJsonBytes: "utf8" | "base64" | "hex",
+    serJsonInfNan: "null" | "constants" | "strings",
+    strMaxLength: number,
+    strMinLength: number,
+    strStripWhitespace: boolean,
+    strToLower: boolean,
+    strToUpper: boolean,
+    strict: boolean,
+    useEnumValues: boolean,
+    valJsonBytes: "utf8" | "base64" | "hex",
+    validateAssignment: boolean,
+    validateDefault: boolean,
+    validateReturn: boolean,
+  }).children(children)
+  ```
+
+## Props
+
+|                       |                                                                                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| --------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| aliasGenerator        | optional string                                                                    | Resolve field aliases from a configured alias generator.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| arbitraryTypesAllowed | optional boolean                                                                   | Allow non-pydantic/arbitrary Python types in field annotations.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| bases                 | optional [Children](../../../core/types/children/)\[]                              | The base classes that this class inherits from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| coerceNumbersToStr    | optional boolean                                                                   | Coerce numeric input values to strings for `str` fields.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| decorators            | optional [Children](../../../core/types/children/)\[]                              | Decorators rendered above the `class` keyword, in source order — `decorators[0]` is topmost. By Python’s bottom-up application order, the topmost entry is the outermost decorator (applied last). Each entry should produce a complete decorator line (typically starting with `@`). Falsy entries are skipped, so conditional decorators can be provided inline when needed. Wrappers like [`DataclassDeclaration`](DataclassDeclaration.md) build their intrinsic decorator (e.g. `@dataclass(...)`) and append it to this list at the position that keeps `@dataclass` closest to the class — i.e. user `decorators` end up **above** the intrinsic one, matching how Pydantic’s `@field_validator` sits above `@classmethod` on methods. Do **not** pass a wrapper’s intrinsic decorator here. For example, when using [`DataclassDeclaration`](DataclassDeclaration.md), do not include `@dataclass(...)` in `decorators` — the component renders it for you, and stacking it twice would produce invalid Python. |
+| extra                 | optional “allow” \| “forbid” \| “ignore”                                           | Behavior for unknown input keys: allow, forbid, or ignore.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| fromAttributes        | optional boolean                                                                   | Populate models from object attributes (ORM-style) instead of mapping keys.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| frozen                | optional boolean                                                                   | Make models immutable (`frozen=True`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| hideInputInErrors     | optional boolean                                                                   | Hide input values in validation error messages.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| jsonSchemaExtra       | optional Record\<string, unknown>                                                  | Include JSON schema extras via a plain JSON-serializable object.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| locByAlias            | optional boolean                                                                   | Use aliases in error locations instead of field names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| modelConfig           | optional [PydanticModelConfigDictProps](../../types/pydanticmodelconfigdictprops/) | Canonical structured config object for `ConfigDict(...)`. Values here are merged with top-level config props. Top-level config props take precedence over `modelConfig` when the same key is provided in both places.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| modelConfigExpression | optional [Children](../../../core/types/children/)                                 | Emits `model_config = <expression>` verbatim (use for arbitrary `ConfigDict` kwargs or dynamic config). Takes precedence over both `modelConfig` and top-level config props.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| populateByName        | optional boolean                                                                   | Allow population by field name even when aliases are defined.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| revalidateInstances   | optional “always” \| “never” \| “subclass-instances”                               | Re-validate model/dataclass instances on assignment boundaries.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| serJsonBytes          | optional “utf8” \| “base64” \| “hex”                                               | JSON serialization format for bytes values.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| serJsonInfNan         | optional “null” \| “constants” \| “strings”                                        | JSON serialization behavior for Infinity/NaN values.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| strMaxLength          | optional number                                                                    | Upper-bound for constrained string lengths at model level.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| strMinLength          | optional number                                                                    | Lower-bound for constrained string lengths at model level.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| strStripWhitespace    | optional boolean                                                                   | Strip leading/trailing whitespace from all `str` fields.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| strToLower            | optional boolean                                                                   | Convert all `str` values to lowercase.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| strToUpper            | optional boolean                                                                   | Convert all `str` values to uppercase.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| strict                | optional boolean                                                                   | Enable strict validation globally for the model.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| useEnumValues         | optional boolean                                                                   | Use enum `.value` instead of enum instances during serialization.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| valJsonBytes          | optional “utf8” \| “base64” \| “hex”                                               | JSON validation format for bytes values.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| validateAssignment    | optional boolean                                                                   | Re-validate when attributes are assigned after model creation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| validateDefault       | optional boolean                                                                   | Validate default values in addition to provided input values.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| validateReturn        | optional boolean                                                                   | Validate return values for call validators.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+
+## Example
+
+```tsx
+import { pydanticModule } from "@alloy-js/python";
+import * as py from "@alloy-js/python";
+
+<py.PydanticClassDeclaration name="User" frozen>
+  <py.VariableDeclaration instanceVariable omitNone name="id" type="int" />
+  <py.VariableDeclaration
+    instanceVariable
+    name="name"
+    type="str"
+    initializer={"Field(default=\"anonymous\")"}
+  />
+</py.PydanticClassDeclaration>
+```
+
+```py
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+class User(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    id: int
+    name: str = Field(default="anonymous")
+```

package/docs/api/components/StaticMethodDeclaration.md

@@ -8,7 +8,7 @@ A Python static method declaration component.
   import { StaticMethodDeclaration } from "@alloy-js/python";
 
 
-  <StaticMethodDeclaration abstract async />
+  <StaticMethodDeclaration abstract async decorators={Children[]} />
   ```
 
 * stc
@@ -20,12 +20,14 @@ A Python static method declaration component.
   StaticMethodDeclaration({
     abstract: boolean,
     async: boolean,
+    decorators: Children[],
   }).children(children)
   ```
 
 ## Props
 
-|          |                  |                                       |
-| -------- | ---------------- | ------------------------------------- |
-| abstract | optional boolean |                                       |
-| async    | optional boolean | Indicates that the function is async. |
+|            |                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ---------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| abstract   | optional boolean                                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| async      | optional boolean                                      | Indicates that the function is async.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| decorators | optional [Children](../../../core/types/children/)\[] | Decorators rendered above `def`, in source order — `decorators[0]` is topmost. By Python’s bottom-up application order, the topmost entry is the **outermost** decorator (applied last) and wraps the result of every decorator below it. Each entry should produce a complete decorator line (typically starting with `@`). Falsy entries (other than `0`) are skipped, so conditional decorators can be provided inline when needed. When used through wrappers that emit an intrinsic decorator ([`ClassMethodDeclaration`](ClassMethodDeclaration.md) → `@classmethod`, [`StaticMethodDeclaration`](StaticMethodDeclaration.md) → `@staticmethod`, [`PropertyDeclaration`](PropertyDeclaration.md) → `@property`), these decorators are rendered **above** the intrinsic line — the correct position for Pydantic’s `@field_validator` / `@model_validator` and other wrappers that must see the underlying function, not a descriptor. When used on plain [`MethodDeclaration`](MethodDeclaration.md) / [`FunctionDeclaration`](FunctionDeclaration.md), these decorators are rendered above `@abstractmethod` (if `abstract` is set) and above `def`. Do **not** pass intrinsic decorators here — i.e. `@classmethod`, `@staticmethod`, `@property`, or `@abstractmethod`. Those are emitted by the matching component ([`ClassMethodDeclaration`](ClassMethodDeclaration.md), [`StaticMethodDeclaration`](StaticMethodDeclaration.md), [`PropertyDeclaration`](PropertyDeclaration.md), or the `abstract` flag) and would otherwise be stacked twice in the output, producing invalid Python. |