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

package/src/builtins/python.ts

@@ -1,5 +1,5 @@
 import { SymbolCreator } from "@alloy-js/core";
-import { createModule } from "../create-module.js";
+import { createModule, type ModuleDescriptor } from "../create-module.js";
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 type dummy = SymbolCreator;
@@ -32,3 +32,541 @@ export const requestsModule = createModule({
     models: ["Response", "Request"],
   },
 });
+
+// Descriptor source captured from pydantic 2.13.4 via script
+const pydanticDescriptor = {
+  ".": [
+    "AfterValidator",
+    "AliasChoices",
+    "AliasGenerator",
+    "AliasPath",
+    "AllowInfNan",
+    "AmqpDsn",
+    "AnyHttpUrl",
+    "AnyUrl",
+    "AnyWebsocketUrl",
+    "AwareDatetime",
+    "Base64Bytes",
+    "Base64Encoder",
+    "Base64Str",
+    "Base64UrlBytes",
+    "Base64UrlStr",
+    "BaseModel",
+    "BeforeValidator",
+    "ByteSize",
+    "ClickHouseDsn",
+    "CockroachDsn",
+    "ConfigDict",
+    "DirectoryPath",
+    "Discriminator",
+    "EmailStr",
+    "EncodedBytes",
+    "EncodedStr",
+    "EncoderProtocol",
+    "Extra",
+    "FailFast",
+    "Field",
+    "FieldSerializationInfo",
+    "FilePath",
+    "FileUrl",
+    "FiniteFloat",
+    "FtpUrl",
+    "FutureDate",
+    "FutureDatetime",
+    "GetCoreSchemaHandler",
+    "GetJsonSchemaHandler",
+    "GetPydanticSchema",
+    "HttpUrl",
+    "IPvAnyAddress",
+    "IPvAnyInterface",
+    "IPvAnyNetwork",
+    "ImportString",
+    "InstanceOf",
+    "Json",
+    "JsonValue",
+    "KafkaDsn",
+    "MariaDBDsn",
+    "ModelWrapValidatorHandler",
+    "MongoDsn",
+    "MySQLDsn",
+    "NaiveDatetime",
+    "NameEmail",
+    "NatsDsn",
+    "NegativeFloat",
+    "NegativeInt",
+    "NewPath",
+    "NonNegativeFloat",
+    "NonNegativeInt",
+    "NonPositiveFloat",
+    "NonPositiveInt",
+    "OnErrorOmit",
+    "PastDate",
+    "PastDatetime",
+    "PaymentCardNumber",
+    "PlainSerializer",
+    "PlainValidator",
+    "PositiveFloat",
+    "PositiveInt",
+    "PostgresDsn",
+    "PrivateAttr",
+    "PydanticDeprecatedSince20",
+    "PydanticDeprecatedSince210",
+    "PydanticDeprecatedSince211",
+    "PydanticDeprecatedSince212",
+    "PydanticDeprecatedSince26",
+    "PydanticDeprecatedSince29",
+    "PydanticDeprecationWarning",
+    "PydanticErrorCodes",
+    "PydanticExperimentalWarning",
+    "PydanticForbiddenQualifier",
+    "PydanticImportError",
+    "PydanticInvalidForJsonSchema",
+    "PydanticSchemaGenerationError",
+    "PydanticUndefinedAnnotation",
+    "PydanticUserError",
+    "RedisDsn",
+    "RootModel",
+    "Secret",
+    "SecretBytes",
+    "SecretStr",
+    "SerializationInfo",
+    "SerializeAsAny",
+    "SerializerFunctionWrapHandler",
+    "SkipValidation",
+    "SnowflakeDsn",
+    "SocketPath",
+    "Strict",
+    "StrictBool",
+    "StrictBytes",
+    "StrictFloat",
+    "StrictInt",
+    "StrictStr",
+    "StringConstraints",
+    "Tag",
+    "TypeAdapter",
+    "UUID1",
+    "UUID3",
+    "UUID4",
+    "UUID5",
+    "UUID6",
+    "UUID7",
+    "UUID8",
+    "UrlConstraints",
+    "VERSION",
+    "ValidateAs",
+    "ValidationError",
+    "ValidationInfo",
+    "ValidatorFunctionWrapHandler",
+    "WebsocketUrl",
+    "WithJsonSchema",
+    "WrapSerializer",
+    "WrapValidator",
+    "__version__",
+    "computed_field",
+    "conbytes",
+    "condate",
+    "condecimal",
+    "confloat",
+    "confrozenset",
+    "conint",
+    "conlist",
+    "conset",
+    "constr",
+    "create_model",
+    "dataclasses",
+    "field_serializer",
+    "field_validator",
+    "model_serializer",
+    "model_validator",
+    "validate_call",
+    "validate_email",
+    "with_config",
+  ],
+  alias_generators: ["to_camel", "to_pascal", "to_snake"],
+  aliases: ["AliasChoices", "AliasGenerator", "AliasPath"],
+  annotated_handlers: ["GetCoreSchemaHandler", "GetJsonSchemaHandler"],
+  color: [
+    "Any",
+    "COLORS_BY_NAME",
+    "COLORS_BY_VALUE",
+    "Callable",
+    "Color",
+    "ColorTuple",
+    "ColorType",
+    "CoreSchema",
+    "HslColorTuple",
+    "JsonSchemaValue",
+    "Optional",
+    "PydanticCustomError",
+    "PydanticDeprecatedSince20",
+    "RGBA",
+    "Union",
+    "cast",
+    "core_schema",
+    "deprecated",
+    "float_to_255",
+    "hls_to_rgb",
+    "ints_to_rgba",
+    "math",
+    "parse_color_value",
+    "parse_float_alpha",
+    "parse_hsl",
+    "parse_str",
+    "parse_tuple",
+    "r_hex_long",
+    "r_hex_short",
+    "r_hsl",
+    "r_hsl_v4_style",
+    "r_rgb",
+    "r_rgb_v4_style",
+    "rads",
+    "re",
+    "repeat_colors",
+    "rgb_to_hls",
+  ],
+  config: ["ConfigDict", "with_config"],
+  dataclasses: ["dataclass", "rebuild_dataclass"],
+  errors: [
+    "PydanticErrorCodes",
+    "PydanticForbiddenQualifier",
+    "PydanticImportError",
+    "PydanticInvalidForJsonSchema",
+    "PydanticSchemaGenerationError",
+    "PydanticUndefinedAnnotation",
+    "PydanticUserError",
+  ],
+  fields: ["Field", "FieldInfo", "PrivateAttr", "computed_field"],
+  functional_serializers: [
+    "Annotated",
+    "Any",
+    "AnyType",
+    "Callable",
+    "GetCoreSchemaHandler",
+    "Literal",
+    "PlainSerializer",
+    "PydanticUndefined",
+    "PydanticUndefinedAnnotation",
+    "PydanticUserError",
+    "SerializationInfo",
+    "SerializeAsAny",
+    "SerializerFunctionWrapHandler",
+    "TYPE_CHECKING",
+    "TypeAlias",
+    "TypeVar",
+    "WhenUsed",
+    "WrapSerializer",
+    "annotations",
+    "core_schema",
+    "dataclasses",
+    "field_serializer",
+    "model_serializer",
+    "overload",
+    "partial",
+    "partialmethod",
+  ],
+  functional_validators: [
+    "AfterValidator",
+    "Annotated",
+    "Any",
+    "AnyType",
+    "ArbitraryTypeWarning",
+    "BeforeValidator",
+    "Callable",
+    "FieldValidatorModes",
+    "FreeModelBeforeValidator",
+    "FreeModelBeforeValidatorWithoutInfo",
+    "GetCoreSchemaHandler",
+    "InstanceOf",
+    "Literal",
+    "ModelAfterValidator",
+    "ModelAfterValidatorWithoutInfo",
+    "ModelBeforeValidator",
+    "ModelBeforeValidatorWithoutInfo",
+    "ModelWrapValidator",
+    "ModelWrapValidatorHandler",
+    "ModelWrapValidatorWithoutInfo",
+    "PlainValidator",
+    "Protocol",
+    "PydanticDeprecatedSince212",
+    "PydanticUndefined",
+    "PydanticUserError",
+    "Self",
+    "SkipValidation",
+    "TYPE_CHECKING",
+    "TypeAlias",
+    "TypeVar",
+    "Union",
+    "ValidateAs",
+    "WrapValidator",
+    "cast",
+    "core_schema",
+    "dataclasses",
+    "field_validator",
+    "model_validator",
+    "overload",
+    "partialmethod",
+    "sys",
+    "version_short",
+    "warnings",
+  ],
+  json_schema: [
+    "Annotated",
+    "Any",
+    "AnyType",
+    "Callable",
+    "ComputedField",
+    "CoreModeRef",
+    "CoreRef",
+    "CoreSchema",
+    "CoreSchemaOrFieldType",
+    "Counter",
+    "DEFAULT_REF_TEMPLATE",
+    "DefsRef",
+    "Enum",
+    "Examples",
+    "GenerateJsonSchema",
+    "GetJsonSchemaHandler",
+    "Hashable",
+    "Iterable",
+    "JsonDict",
+    "JsonRef",
+    "JsonSchemaKeyT",
+    "JsonSchemaMode",
+    "JsonSchemaValue",
+    "JsonSchemaWarningKind",
+    "JsonValue",
+    "Literal",
+    "MISSING",
+    "NewType",
+    "NoDefault",
+    "Pattern",
+    "PydanticDeprecatedSince26",
+    "PydanticDeprecatedSince29",
+    "PydanticInvalidForJsonSchema",
+    "PydanticJsonSchemaWarning",
+    "PydanticOmit",
+    "PydanticSchemaGenerationError",
+    "PydanticUserError",
+    "Sequence",
+    "SkipJsonSchema",
+    "TYPE_CHECKING",
+    "TypeAlias",
+    "TypeVar",
+    "Union",
+    "WithJsonSchema",
+    "assert_never",
+    "cast",
+    "collections",
+    "core_schema",
+    "dataclasses",
+    "deepcopy",
+    "defaultdict",
+    "deprecated",
+    "final",
+    "get_literal_values",
+    "inspect",
+    "math",
+    "model_json_schema",
+    "models_json_schema",
+    "os",
+    "overload",
+    "pydantic_core",
+    "re",
+    "to_jsonable_python",
+    "warnings",
+  ],
+  main: ["BaseModel", "create_model"],
+  networks: [
+    "AmqpDsn",
+    "AnyHttpUrl",
+    "AnyUrl",
+    "AnyWebsocketUrl",
+    "ClickHouseDsn",
+    "CockroachDsn",
+    "EmailStr",
+    "FileUrl",
+    "FtpUrl",
+    "HttpUrl",
+    "IPvAnyAddress",
+    "IPvAnyInterface",
+    "IPvAnyNetwork",
+    "KafkaDsn",
+    "MariaDBDsn",
+    "MongoDsn",
+    "MySQLDsn",
+    "NameEmail",
+    "NatsDsn",
+    "PostgresDsn",
+    "RedisDsn",
+    "SnowflakeDsn",
+    "UrlConstraints",
+    "WebsocketUrl",
+    "validate_email",
+  ],
+  plugin: [
+    "BaseValidateHandlerProtocol",
+    "NewSchemaReturns",
+    "PydanticPluginProtocol",
+    "SchemaKind",
+    "SchemaTypePath",
+    "ValidateJsonHandlerProtocol",
+    "ValidatePythonHandlerProtocol",
+    "ValidateStringsHandlerProtocol",
+  ],
+  root_model: ["RootModel"],
+  type_adapter: [
+    "Any",
+    "BaseModel",
+    "Callable",
+    "ConfigDict",
+    "CoreSchema",
+    "DEFAULT_REF_TEMPLATE",
+    "ExtraValues",
+    "FrameType",
+    "GenerateJsonSchema",
+    "Generic",
+    "IncEx",
+    "Iterable",
+    "JsonSchemaKeyT",
+    "JsonSchemaMode",
+    "JsonSchemaValue",
+    "Literal",
+    "P",
+    "ParamSpec",
+    "PluggableSchemaValidator",
+    "PydanticUndefinedAnnotation",
+    "PydanticUserError",
+    "R",
+    "SchemaSerializer",
+    "SchemaValidator",
+    "Some",
+    "T",
+    "TypeAdapter",
+    "TypeAdapterT",
+    "TypeVar",
+    "cast",
+    "create_schema_validator",
+    "final",
+    "is_dataclass",
+    "is_typeddict",
+    "overload",
+    "sys",
+    "types",
+  ],
+  types: [
+    "AllowInfNan",
+    "AwareDatetime",
+    "Base64Bytes",
+    "Base64Encoder",
+    "Base64Str",
+    "Base64UrlBytes",
+    "Base64UrlStr",
+    "ByteSize",
+    "DirectoryPath",
+    "Discriminator",
+    "EncodedBytes",
+    "EncodedStr",
+    "EncoderProtocol",
+    "FailFast",
+    "FilePath",
+    "FiniteFloat",
+    "FutureDate",
+    "FutureDatetime",
+    "GetPydanticSchema",
+    "ImportString",
+    "Json",
+    "JsonValue",
+    "NaiveDatetime",
+    "NegativeFloat",
+    "NegativeInt",
+    "NewPath",
+    "NonNegativeFloat",
+    "NonNegativeInt",
+    "NonPositiveFloat",
+    "NonPositiveInt",
+    "OnErrorOmit",
+    "PastDate",
+    "PastDatetime",
+    "PaymentCardNumber",
+    "PositiveFloat",
+    "PositiveInt",
+    "Secret",
+    "SecretBytes",
+    "SecretStr",
+    "SocketPath",
+    "Strict",
+    "StrictBool",
+    "StrictBytes",
+    "StrictFloat",
+    "StrictInt",
+    "StrictStr",
+    "StringConstraints",
+    "Tag",
+    "UUID1",
+    "UUID3",
+    "UUID4",
+    "UUID5",
+    "UUID6",
+    "UUID7",
+    "UUID8",
+    "conbytes",
+    "condate",
+    "condecimal",
+    "confloat",
+    "confrozenset",
+    "conint",
+    "conlist",
+    "conset",
+    "constr",
+  ],
+  validate_call_decorator: ["validate_call"],
+  version: ["VERSION", "version_info"],
+  warnings: [
+    "ArbitraryTypeWarning",
+    "PydanticDeprecatedSince20",
+    "PydanticDeprecatedSince210",
+    "PydanticDeprecatedSince211",
+    "PydanticDeprecatedSince212",
+    "PydanticDeprecatedSince26",
+    "PydanticDeprecatedSince29",
+    "PydanticDeprecationWarning",
+    "PydanticExperimentalWarning",
+    "TypedDictExtraConfigWarning",
+    "UnsupportedFieldAttributeWarning",
+  ],
+} as const satisfies ModuleDescriptor;
+
+export const pydanticModule = createModule({
+  name: "pydantic",
+  descriptor: pydanticDescriptor,
+});
+
+/** `typing` stdlib symbols used heavily with Pydantic generics and annotations. */
+export const typingModule = createModule({
+  name: "typing",
+  descriptor: {
+    ".": [
+      "Annotated",
+      "Any",
+      "ClassVar",
+      "Generic",
+      "Literal",
+      "Optional",
+      "Protocol",
+      "TypeVar",
+      "Union",
+      // Class- and method-level decorators commonly stacked above the
+      // intrinsic `class` / `def`.
+      "final",
+      "override",
+      "runtime_checkable",
+    ],
+  },
+});
+
+export const pydanticSettingsModule = createModule({
+  name: "pydantic_settings",
+  descriptor: {
+    ".": ["BaseSettings", "SettingsConfigDict"],
+  },
+});

package/src/components/ClassDeclaration.tsx

@@ -1,6 +1,7 @@
 import { Children, List, Name, Show, createContentSlot } from "@alloy-js/core";
 import { createPythonSymbol } from "../symbol-creation.js";
 import { BaseDeclarationProps, Declaration } from "./Declaration.js";
+import { DecoratorList } from "./DecoratorList.jsx";
 import { MemberScope } from "./MemberScope.jsx";
 import { PythonBlock } from "./PythonBlock.jsx";
 
@@ -9,6 +10,27 @@ export interface ClassDeclarationProps extends BaseDeclarationProps {
    * The base classes that this class inherits from.
    */
   bases?: 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` 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`, do not include `@dataclass(...)` in
+   * `decorators` — the component renders it for you, and stacking it twice
+   * would produce invalid Python.
+   */
+  decorators?: Children[];
 }
 
 /**
@@ -57,6 +79,7 @@ export function ClassDeclaration(props: ClassDeclarationProps) {
 
   return (
     <Declaration symbol={sym}>
+      <DecoratorList decorators={props.decorators} />
       class <Name />
       <MemberScope ownerSymbol={sym}>
         {basesPart}

package/src/components/ClassMethodDeclaration.tsx

@@ -1,4 +1,6 @@
+import { splitProps } from "@alloy-js/core";
 import { createMethodSymbol } from "../symbols/factories.js";
+import { DecoratorList } from "./DecoratorList.jsx";
 import type { CommonFunctionProps } from "./FunctionBase.js";
 import { MethodDeclarationBase } from "./MethodBase.js";
 
@@ -17,6 +19,10 @@ import { MethodDeclarationBase } from "./MethodBase.js";
  * def create(cls, value: str) -> None:
  *     return cls(value)
  * ```
+ *
+ * @remarks
+ * Use **`decorators`** for decorators that must appear above `@classmethod`
+ * (for example Pydantic `@field_validator`).
  */
 export interface ClassMethodDeclarationProps extends CommonFunctionProps {
   abstract?: boolean;
@@ -24,11 +30,13 @@ export interface ClassMethodDeclarationProps extends CommonFunctionProps {
 
 export function ClassMethodDeclaration(props: ClassMethodDeclarationProps) {
   const sym = createMethodSymbol(props.name, { refkeys: props.refkey });
+  const [decoratorProps, rest] = splitProps(props, ["decorators"]);
   return (
     <>
+      <DecoratorList decorators={decoratorProps.decorators} />
       {"@classmethod"}
       <hbr />
-      <MethodDeclarationBase functionType="class" {...props} sym={sym} />
+      <MethodDeclarationBase functionType="class" {...rest} sym={sym} />
     </>
   );
 }

package/src/components/DataclassDeclaration.tsx

@@ -160,7 +160,7 @@ export function DataclassDeclaration(props: DataclassDeclarationProps) {
     validateDataclassDecoratorArgs(kwargs);
   }
 
-  return (
+  const dataclassDecorator = (
     <>
       {"@"}
       {dataclassesModule["."].dataclass}
@@ -175,16 +175,23 @@ export function DataclassDeclaration(props: DataclassDeclarationProps) {
         </For>
         )
       </Show>
-      <hbr />
-      <ClassDeclaration
-        name={props.name}
-        bases={props.bases}
-        doc={props.doc}
-        refkey={props.refkey}
-      >
-        <StatementList>{props.children}</StatementList>
-        {validateDataclassMemberConflicts(kwargs as DataclassDecoratorKwargs)}
-      </ClassDeclaration>
     </>
   );
+
+  // User decorators stack above the intrinsic `@dataclass(...)`, mirroring
+  // how Pydantic's `@field_validator` sits above `@classmethod` on methods.
+  const decorators = [...(props.decorators ?? []), dataclassDecorator];
+
+  return (
+    <ClassDeclaration
+      name={props.name}
+      bases={props.bases}
+      doc={props.doc}
+      refkey={props.refkey}
+      decorators={decorators}
+    >
+      <StatementList>{props.children}</StatementList>
+      {validateDataclassMemberConflicts(kwargs as DataclassDecoratorKwargs)}
+    </ClassDeclaration>
+  );
 }