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

package/src/components/DecoratorList.tsx

@@ -0,0 +1,50 @@
+import { Children, For } from "@alloy-js/core";
+
+/**
+ * Props for {@link DecoratorList}.
+ */
+export interface DecoratorListProps {
+  /**
+   * Decorators rendered top-to-bottom. The first entry is rendered topmost,
+   * which (by Python's bottom-up application order) is the outermost decorator
+   * — i.e. it is applied **last** and wraps the result of everything below it.
+   *
+   * Falsy entries (other than `0`) are skipped, so conditional decorators can
+   * be written inline as `condition && <Decorator/>`.
+   */
+  decorators?: Children[];
+}
+
+/**
+ * Renders a list of decorators, one per line, with a single hardline between
+ * adjacent decorators and a trailing hardline only when at least one decorator
+ * is present.
+ *
+ * This is the canonical decorator-rendering primitive for method-, function-,
+ * and property-like components. Centralizing it ensures the decorator stack
+ * composes consistently — no stray blank lines between decorators, and no
+ * trailing newline when the list is empty.
+ *
+ * @example
+ * ```tsx
+ * <DecoratorList decorators={[code`@field_validator("name")`, "@classmethod"]} />
+ * ```
+ * Renders:
+ * ```python
+ * @field_validator("name")
+ * @classmethod
+ * ```
+ *
+ * @remarks
+ * Internal helper, not exported from the package. Used by
+ * `MethodDeclarationBase`, `ClassMethodDeclaration`, `StaticMethodDeclaration`,
+ * and `PropertyDeclaration` to render their `decorators` prop above the
+ * intrinsic decorator (`@classmethod`, `@staticmethod`, `@property`) or `def`.
+ */
+export function DecoratorList(props: DecoratorListProps) {
+  return (
+    <For each={props.decorators ?? []} hardline ender={<hbr />} skipFalsy>
+      {(dec) => dec}
+    </For>
+  );
+}

package/src/components/EnumDeclaration.tsx

@@ -7,6 +7,7 @@ import {
 import { enumModule } from "../builtins/python.js";
 import { createPythonSymbol } from "../symbol-creation.js";
 import { BaseDeclarationProps } from "./Declaration.js";
+import { DecoratorList } from "./DecoratorList.jsx";
 import { EnumMember, EnumMemberProps } from "./EnumMember.js";
 import { MemberScope } from "./MemberScope.jsx";
 import { PythonBlock } from "./PythonBlock.jsx";
@@ -113,6 +114,15 @@ export interface ClassEnumProps extends EnumPropsBase {
    * Indicates that the enum members should be auto-generated.
    */
   auto?: boolean;
+  /**
+   * Decorators rendered above `class <Name>(<BaseType>):`. See
+   * {@link ClassDeclarationProps.decorators} 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.
+   */
+  decorators?: Children[];
 }
 
 /**
@@ -203,6 +213,7 @@ export function ClassEnumDeclaration(props: ClassEnumProps) {
   }
   return (
     <CoreDeclaration symbol={sym}>
+      <DecoratorList decorators={props.decorators} />
       class {sym.name}({enumModule["."][baseType]})
       <MemberScope ownerSymbol={sym}>
         <PythonBlock opener=":">

package/src/components/FunctionBase.tsx

@@ -1,8 +1,9 @@
-import { createContentSlot, Name, Show } from "@alloy-js/core";
+import { createContentSlot, Name, Show, type Children } from "@alloy-js/core";
 import { PythonOutputSymbol } from "../index.js";
 import { getCallSignatureProps } from "../utils.js";
 import { CallSignature, CallSignatureProps } from "./CallSignature.jsx";
 import { BaseDeclarationProps, Declaration } from "./Declaration.js";
+import { DecoratorList } from "./DecoratorList.jsx";
 import { LexicalScope } from "./LexicalScope.jsx";
 import { PythonBlock } from "./PythonBlock.jsx";
 
@@ -19,6 +20,35 @@ export interface CommonFunctionProps
     CallSignatureProps {
   /** Indicates that the function is async. */
   async?: boolean;
+  /**
+   * 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` → `@classmethod`,
+   * `StaticMethodDeclaration` → `@staticmethod`,
+   * `PropertyDeclaration` → `@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` / `FunctionDeclaration`, 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`, `StaticMethodDeclaration`,
+   * `PropertyDeclaration`, or the `abstract` flag) and would otherwise be
+   * stacked twice in the output, producing invalid Python.
+   */
+  decorators?: Children[];
 }
 
 /**
@@ -54,6 +84,7 @@ export interface BaseFunctionDeclarationProps extends CommonFunctionProps {
  * ```
  */
 export function BaseFunctionDeclaration(props: BaseFunctionDeclarationProps) {
+  const { decorators, sym, ...declarationProps } = props;
   const asyncKwd = props.async ? "async " : "";
   let parameters;
   switch (props.functionType) {
@@ -66,11 +97,11 @@ export function BaseFunctionDeclaration(props: BaseFunctionDeclarationProps) {
     default:
       parameters = props.parameters;
   }
-  const sym: PythonOutputSymbol = props.sym;
   const ContentSlot = createContentSlot();
   return (
     <>
-      <Declaration {...props} nameKind="function" symbol={sym}>
+      <DecoratorList decorators={decorators} />
+      <Declaration {...declarationProps} nameKind="function" symbol={sym}>
         {asyncKwd}def <Name />
         <LexicalScope name={sym.name}>
           <CallSignature

package/src/components/FutureStatement.tsx

@@ -18,7 +18,7 @@ export interface FutureStatementProps {
  *
  * @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/src/components/MethodBase.tsx

@@ -1,4 +1,5 @@
 import { abcModule } from "../builtins/python.js";
+import { DecoratorList } from "./DecoratorList.jsx";
 import {
   BaseFunctionDeclaration,
   BaseFunctionDeclarationProps,
@@ -36,8 +37,10 @@ export function MethodDeclarationBase(
   props: MethodDeclarationBaseProps &
     Pick<BaseFunctionDeclarationProps, "functionType" | "sym">,
 ) {
+  const { decorators, abstract, ...rest } = props;
+
   const abstractMethod =
-    props.abstract ?
+    abstract ?
       <>
         @{abcModule["."].abstractmethod}
         <hbr />
@@ -46,8 +49,9 @@ export function MethodDeclarationBase(
 
   return (
     <>
+      <DecoratorList decorators={decorators} />
       {abstractMethod}
-      <BaseFunctionDeclaration {...props} />
+      <BaseFunctionDeclaration {...rest} />
     </>
   );
 }

package/src/components/PropertyDeclaration.tsx

@@ -16,6 +16,7 @@ import { PythonOutputSymbol } from "../index.js";
 import { ParameterDescriptor } from "../parameter-descriptor.js";
 import { createMethodSymbol } from "../symbols/factories.js";
 import { Atom } from "./Atom.jsx";
+import { DecoratorList } from "./DecoratorList.jsx";
 import { CommonFunctionProps } from "./FunctionBase.js";
 import { MethodDeclarationBase } from "./MethodBase.js";
 
@@ -72,6 +73,29 @@ const PropertyContext = createContext<Children | undefined>();
  * The property must be declared within a class. The getter method is
  * automatically generated using the `@property` decorator. Use the nested
  * `Setter` and `Deleter` components to add mutators.
+ *
+ * Use **`decorators`** for decorators that must appear **above** the intrinsic
+ * `@property` (for example Pydantic `@computed_field`, `@typing.final`,
+ * `@typing.override`). The first array entry is rendered topmost, matching
+ * Python source order.
+ *
+ * @example Pydantic computed field
+ * ```tsx
+ * <py.PropertyDeclaration
+ *   name="area"
+ *   type="float"
+ *   decorators={[code`@${pydanticModule["."].computed_field}`]}
+ * >
+ *   return self.width ** 2
+ * </py.PropertyDeclaration>
+ * ```
+ * Generates:
+ * ```python
+ * @computed_field
+ * @property
+ * def area(self) -> float:
+ *     return self.width ** 2
+ * ```
  */
 export interface PropertyDeclarationProps {
   name: string;
@@ -80,6 +104,12 @@ export interface PropertyDeclarationProps {
   refkey?: Refkey;
   abstract?: boolean;
   doc?: 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`.
+   */
+  decorators?: Children[];
 }
 
 export function PropertyDeclaration(props: PropertyDeclarationProps) {
@@ -120,6 +150,7 @@ export function PropertyDeclaration(props: PropertyDeclarationProps) {
             <PropertyMethodDeclaration
               abstract={props.abstract}
               doc={props.doc}
+              decorators={props.decorators}
             >
               {unkeyedChildren}
             </PropertyMethodDeclaration>
@@ -155,13 +186,15 @@ export interface PropertyMethodDeclarationProps
 function PropertyMethodDeclaration(props: PropertyMethodDeclarationProps) {
   const propertySymbol = useContext(DeclarationContext) as PythonOutputSymbol;
   const propertyType = useContext(PropertyContext);
+  const { decorators, ...rest } = props;
 
   return (
     <>
+      <DecoratorList decorators={decorators} />
       {code`@property`}
       <hbr />
       <MethodDeclarationBase
-        {...props}
+        {...rest}
         name={propertySymbol.name}
         functionType="instance"
         returnType={propertyType}
@@ -219,6 +252,13 @@ function PropertyMethodBase(props: PropertyMethodBaseProps) {
  * def value(self, value: int) -> None:
  *     self._value = value
  * ```
+ *
+ * @remarks
+ * The intrinsic `@<name>.setter` decorator is always rendered topmost (it must
+ * remain the outermost decorator). Any `decorators` passed to this component
+ * are rendered **between** `@<name>.setter` and `def`, which is the correct
+ * position for wrappers that should decorate the underlying function before
+ * `setter` re-binds it to the property (e.g. `@deprecated`, `@abstractmethod`).
  */
 PropertyDeclaration.Setter = taggedComponent(
   setterTag,
@@ -253,6 +293,13 @@ PropertyDeclaration.Setter = taggedComponent(
  * def value(self) -> None:
  *     del self._value
  * ```
+ *
+ * @remarks
+ * The intrinsic `@<name>.deleter` decorator is always rendered topmost (it
+ * must remain the outermost decorator). Any `decorators` passed to this
+ * component are rendered **between** `@<name>.deleter` and `def`, which is
+ * the correct position for wrappers that should decorate the underlying
+ * function before `deleter` re-binds it to the property.
  */
 PropertyDeclaration.Deleter = taggedComponent(
   deleterTag,

package/src/components/PydanticClassDeclaration.tsx

@@ -0,0 +1,222 @@
+import {
+  For,
+  List,
+  childrenArray,
+  splitProps,
+  type Children,
+} from "@alloy-js/core";
+import { snakeCase } from "change-case";
+import { pydanticModule } from "../builtins/python.js";
+import { Atom } from "./Atom.jsx";
+import type { ClassDeclarationProps } from "./ClassDeclaration.js";
+import { ClassDeclaration } from "./ClassDeclaration.js";
+
+/**
+ * Keyword-style options for Pydantic v2 `ConfigDict`, using camelCase prop names
+ * that map to snake_case Python arguments (for example `validateAssignment` →
+ * `validate_assignment`).
+ */
+export interface PydanticModelConfigDictProps {
+  /** Resolve field aliases from a configured alias generator. */
+  aliasGenerator?: string;
+  /** Allow non-pydantic/arbitrary Python types in field annotations. */
+  arbitraryTypesAllowed?: boolean;
+  /** Coerce numeric input values to strings for `str` fields. */
+  coerceNumbersToStr?: boolean;
+  /** Behavior for unknown input keys: allow, forbid, or ignore. */
+  extra?: "allow" | "forbid" | "ignore";
+  /** Populate models from object attributes (ORM-style) instead of mapping keys. */
+  fromAttributes?: boolean;
+  /** Make models immutable (`frozen=True`). */
+  frozen?: boolean;
+  /** Hide input values in validation error messages. */
+  hideInputInErrors?: boolean;
+  /** Include JSON schema extras via a plain JSON-serializable object. */
+  jsonSchemaExtra?: Record<string, unknown>;
+  /** Use aliases in error locations instead of field names. */
+  locByAlias?: boolean;
+  /** Allow population by field name even when aliases are defined. */
+  populateByName?: boolean;
+  /** Re-validate model/dataclass instances on assignment boundaries. */
+  revalidateInstances?: "always" | "never" | "subclass-instances";
+  /** JSON serialization format for bytes values. */
+  serJsonBytes?: "utf8" | "base64" | "hex";
+  /** JSON serialization behavior for Infinity/NaN values. */
+  serJsonInfNan?: "null" | "constants" | "strings";
+  /** Upper-bound for constrained string lengths at model level. */
+  strMaxLength?: number;
+  /** Lower-bound for constrained string lengths at model level. */
+  strMinLength?: number;
+  /** Strip leading/trailing whitespace from all `str` fields. */
+  strStripWhitespace?: boolean;
+  /** Convert all `str` values to lowercase. */
+  strToLower?: boolean;
+  /** Convert all `str` values to uppercase. */
+  strToUpper?: boolean;
+  /** Enable strict validation globally for the model. */
+  strict?: boolean;
+  /** Use enum `.value` instead of enum instances during serialization. */
+  useEnumValues?: boolean;
+  /** JSON validation format for bytes values. */
+  valJsonBytes?: "utf8" | "base64" | "hex";
+  /** Re-validate when attributes are assigned after model creation. */
+  validateAssignment?: boolean;
+  /** Validate default values in addition to provided input values. */
+  validateDefault?: boolean;
+  /** Validate return values for call validators. */
+  validateReturn?: boolean;
+}
+
+const PydanticModelConfigKeys = [
+  "aliasGenerator",
+  "arbitraryTypesAllowed",
+  "coerceNumbersToStr",
+  "frozen",
+  "extra",
+  "fromAttributes",
+  "hideInputInErrors",
+  "jsonSchemaExtra",
+  "locByAlias",
+  "populateByName",
+  "revalidateInstances",
+  "serJsonBytes",
+  "serJsonInfNan",
+  "strMinLength",
+  "strMaxLength",
+  "strStripWhitespace",
+  "strToLower",
+  "strToUpper",
+  "strict",
+  "useEnumValues",
+  "valJsonBytes",
+  "validateAssignment",
+  "validateDefault",
+  "validateReturn",
+] as const satisfies readonly (keyof PydanticModelConfigDictProps)[];
+
+export interface PydanticClassDeclarationProps
+  extends ClassDeclarationProps,
+    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.
+   */
+  modelConfig?: PydanticModelConfigDictProps;
+  /**
+   * Emits `model_config = <expression>` verbatim (use for arbitrary `ConfigDict`
+   * kwargs or dynamic config). Takes precedence over both `modelConfig` and
+   * top-level config props.
+   *
+   * @example
+   * A typical value emits `ConfigDict(frozen=True, extra="forbid")`.
+   */
+  modelConfigExpression?: Children;
+}
+
+/**
+ * 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 {@link 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(...)`.
+ *
+ * @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")
+ * ```
+ */
+export function PydanticClassDeclaration(props: PydanticClassDeclarationProps) {
+  const [modelConfigProps, bodyProps, rest] = splitProps(
+    props,
+    PydanticModelConfigKeys,
+    ["modelConfig", "modelConfigExpression", "children"],
+  );
+  const bases = rest.bases ?? [pydanticModule["."].BaseModel];
+  const { modelConfig, modelConfigExpression, children } = bodyProps;
+
+  const configEntries: Array<[string, unknown]> = [];
+  if (modelConfigExpression === undefined) {
+    for (const key of PydanticModelConfigKeys) {
+      const value = modelConfigProps[key] ?? modelConfig?.[key];
+      if (value === undefined) continue;
+      configEntries.push([snakeCase(key), value]);
+    }
+  }
+  const hasStructuredModelConfig =
+    modelConfigExpression === undefined && configEntries.length > 0;
+  const hasExpressionModelConfig = modelConfigExpression !== undefined;
+
+  const bodyItems: Children[] = [];
+  if (hasExpressionModelConfig) {
+    bodyItems.push(
+      <>
+        {"model_config = "}
+        {modelConfigExpression}
+      </>,
+    );
+  } else if (hasStructuredModelConfig) {
+    bodyItems.push(
+      <>
+        {"model_config = "}
+        {pydanticModule["."].ConfigDict}
+        {"("}
+        <For each={configEntries} comma space>
+          {([k, v]) => (
+            <>
+              {k}=<Atom jsValue={v} />
+            </>
+          )}
+        </For>
+        {")"}
+      </>,
+    );
+  }
+  bodyItems.push(...childrenArray(() => children));
+
+  return (
+    <ClassDeclaration
+      name={rest.name}
+      bases={bases}
+      doc={rest.doc}
+      refkey={rest.refkey}
+      decorators={rest.decorators}
+    >
+      <List hardline>
+        <For each={bodyItems}>{(item) => item}</For>
+      </List>
+    </ClassDeclaration>
+  );
+}

package/src/components/StaticMethodDeclaration.tsx

@@ -1,4 +1,5 @@
 import { createMethodSymbol } from "../symbols/factories.js";
+import { DecoratorList } from "./DecoratorList.jsx";
 import type { CommonFunctionProps } from "./FunctionBase.js";
 import { MethodDeclarationBase } from "./MethodBase.js";
 
@@ -17,6 +18,9 @@ import { MethodDeclarationBase } from "./MethodBase.js";
  * def identity(value: int) -> None:
  *     return value
  * ```
+ *
+ * @remarks
+ * Use **`decorators`** for decorators that must appear above `@staticmethod`.
  */
 export interface StaticMethodDeclarationProps extends CommonFunctionProps {
   abstract?: boolean;
@@ -24,11 +28,13 @@ export interface StaticMethodDeclarationProps extends CommonFunctionProps {
 
 export function StaticMethodDeclaration(props: StaticMethodDeclarationProps) {
   const sym = createMethodSymbol(props.name, { refkeys: props.refkey });
+  const { decorators, ...rest } = props;
   return (
     <>
+      <DecoratorList decorators={decorators} />
       {"@staticmethod"}
       <hbr />
-      <MethodDeclarationBase functionType="static" {...props} sym={sym} />
+      <MethodDeclarationBase functionType="static" {...rest} sym={sym} />
     </>
   );
 }

package/src/components/index.ts

@@ -19,6 +19,7 @@ export * from "./MemberScope.jsx";
 export type { MethodDeclarationBaseProps } from "./MethodBase.js";
 export * from "./MethodDeclaration.js";
 export * from "./PropertyDeclaration.js";
+export * from "./PydanticClassDeclaration.js";
 export * from "./PyDoc.js";
 export * from "./PythonBlock.js";
 export * from "./Reference.js";