@alloy-js/python 0.4.0-dev.5 → 0.4.0-dev.7

package/docs/api/components/AttributeDoc.md

@@ -0,0 +1,36 @@
+# AttributeDoc
+
+A component that creates documentation for a single attribute. This can be used for both inline and block attribute documentation.
+
+* jsx
+
+  ```tsx
+  import { AttributeDoc } from "@alloy-js/python";
+
+
+  <AttributeDoc name={Children} style={"google"} type={Children}>
+    {children}
+  </AttributeDoc>
+  ```
+
+* stc
+
+  ```ts
+  import { AttributeDoc } from "@alloy-js/python/stc";
+
+
+  AttributeDoc({
+    name: Children,
+    style: "google",
+    type: Children,
+  }).children(children)
+  ```
+
+## Props
+
+|          |                                                    |   |
+| -------- | -------------------------------------------------- | - |
+| children | optional [Children](../../../core/types/children/) |   |
+| name     | [Children](../../../core/types/children/)          |   |
+| style    | optional “google”                                  |   |
+| type     | optional [Children](../../../core/types/children/) |   |

package/docs/api/components/CallSignature.md

@@ -0,0 +1,62 @@
+# CallSignature
+
+A Python call signature, e.g. the part after the `def` keyword and the name in a function expression.
+
+* jsx
+
+  ```tsx
+  import { CallSignature } from "@alloy-js/python";
+
+
+  <CallSignature
+    args
+    kwargs
+    parameters={(ParameterDescriptor | ParameterMarker | string)[]}
+    returnType={Children}
+    typeParameters={string[]}
+   />
+  ```
+
+* stc
+
+  ```ts
+  import { CallSignature } from "@alloy-js/python/stc";
+
+
+  CallSignature({
+    args: boolean,
+    kwargs: boolean,
+    parameters: (ParameterDescriptor | ParameterMarker | string)[],
+    returnType: Children,
+    typeParameters: string[],
+  }).children(children)
+  ```
+
+## Props
+
+|                |                                                                                                                                    |                                                                                                                                                                                                                               |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| args           | optional boolean                                                                                                                   | Indicates if there are positional arguments (`*args`) in the function                                                                                                                                                         |
+| kwargs         | optional boolean                                                                                                                   | Indicates if there are keyword arguments (`**kwargs`) in the function                                                                                                                                                         |
+| parameters     | optional ([ParameterDescriptor](../../types/parameterdescriptor/) \| [ParameterMarker](../../types/parametermarker/) \| string)\[] | The parameters to the call signature. Can be an array of strings (for simple parameter names), [ParameterDescriptor](../../types/parameterdescriptor/)s, or special markers (”\*” for keyword-only, ”/” for positional-only). |
+| returnType     | optional [Children](../../../core/types/children/)                                                                                 | The return type of the function.                                                                                                                                                                                              |
+| typeParameters | optional string\[]                                                                                                                 | The type parameters of the call signature, e.g. for a generic function. This is only supported in Python 3.12+.                                                                                                               |
+
+## Remarks
+
+Any parameters or type parameters declared in this signature will be placed in the current scope. This component does not make a scope to hold its parameters.
+
+## Example
+
+```tsx
+<CallSignature
+  parameters={[{ name: "a", type: "int" }, { name: "b", type: "str" }]}
+  returnType="int"
+/>
+```
+
+renders to
+
+```py
+(a: int, b: str) -> int
+```

package/docs/api/components/CallSignatureParameters.md

@@ -0,0 +1,49 @@
+# CallSignatureParameters
+
+A call signature parameters declaration, which can be used to define the parameters of a function or other callables.
+
+* jsx
+
+  ```tsx
+  import { CallSignatureParameters } from "@alloy-js/python";
+
+
+  <CallSignatureParameters
+    args
+    kwargs
+    parameters={(ParameterDescriptor | ParameterMarker | string)[]}
+   />
+  ```
+
+* stc
+
+  ```ts
+  import { CallSignatureParameters } from "@alloy-js/python/stc";
+
+
+  CallSignatureParameters({
+    args: boolean,
+    kwargs: boolean,
+    parameters: (ParameterDescriptor | ParameterMarker | string)[],
+  }).children(children)
+  ```
+
+## Props
+
+|            |                                                                                                                                    |   |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- | - |
+| args       | optional boolean                                                                                                                   |   |
+| kwargs     | optional boolean                                                                                                                   |   |
+| parameters | optional ([ParameterDescriptor](../../types/parameterdescriptor/) \| [ParameterMarker](../../types/parametermarker/) \| string)\[] |   |
+
+## Example
+
+```tsx
+<py.CallSignatureParameters parameters={[ "a", "b" ]} />
+```
+
+This will generate:
+
+```python
+a, b
+```

package/docs/api/components/ClassDeclaration.md

@@ -0,0 +1,67 @@
+# ClassDeclaration
+
+Create a Python class declaration.
+
+* jsx
+
+  ```tsx
+  import { ClassDeclaration } from "@alloy-js/python";
+
+
+  <ClassDeclaration
+    bases={Children[]}
+    doc={Children}
+    name={string | Namekey}
+    refkey={Refkey | Refkey[]}
+   />
+  ```
+
+* stc
+
+  ```ts
+  import { ClassDeclaration } from "@alloy-js/python/stc";
+
+
+  ClassDeclaration({
+    bases: Children[],
+    doc: Children,
+    name: string | Namekey,
+    refkey: Refkey | Refkey[],
+  }).children(children)
+  ```
+
+## 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.                                        |
+
+## Remarks
+
+Any child declarations (methods, fields, nested classes) will be placed in the class scope. This component creates a class scope to hold its members.
+
+## Example
+
+```tsx
+<ClassDeclaration name="MyClass" bases={["BaseClass"]}>
+  <VariableDeclaration name="a" type="int" />
+  <VariableDeclaration name="b" type="str" />
+  <py.FunctionDeclaration name="my_method" parameters={[{ name: "a", type: "int" }, { name: "b", type: "str" }]} returnType="int">
+    return a + b
+  </py.FunctionDeclaration>
+</ClassDeclaration>
+```
+
+renders to
+
+```py
+class MyClass(BaseClass):
+  a: int = None
+  b: str = None
+  def my_method(self, a: int, b: str) -> int:
+    return a + b
+```

package/docs/api/components/ClassDoc.md

@@ -0,0 +1,55 @@
+# ClassDoc
+
+A component that creates a ClassDoc block for classes.
+
+* jsx
+
+  ```tsx
+  import { ClassDoc } from "@alloy-js/python";
+
+
+  <ClassDoc
+    attributes={GoogleStyleDocAttributeProps[]}
+    deprecated="string"
+    description={Children[]}
+    examples={Children[]}
+    note="string"
+    parameters={ParameterDescriptor[]}
+    seeAlso={string[]}
+    style={"google"}
+    warning="string"
+   />
+  ```
+
+* stc
+
+  ```ts
+  import { ClassDoc } from "@alloy-js/python/stc";
+
+
+  ClassDoc({
+    attributes: GoogleStyleDocAttributeProps[],
+    deprecated: string,
+    description: Children[],
+    examples: Children[],
+    note: string,
+    parameters: ParameterDescriptor[],
+    seeAlso: string[],
+    style: "google",
+    warning: string,
+  }).children(children)
+  ```
+
+## Props
+
+|             |                                                                                       |   |
+| ----------- | ------------------------------------------------------------------------------------- | - |
+| attributes  | optional [GoogleStyleDocAttributeProps](../../types/googlestyledocattributeprops/)\[] |   |
+| deprecated  | optional string                                                                       |   |
+| description | [Children](../../../core/types/children/)\[]                                          |   |
+| examples    | optional [Children](../../../core/types/children/)\[]                                 |   |
+| note        | optional string                                                                       |   |
+| parameters  | optional [ParameterDescriptor](../../types/parameterdescriptor/)\[]                   |   |
+| seeAlso     | optional string\[]                                                                    |   |
+| style       | optional “google”                                                                     |   |
+| warning     | optional string                                                                       |   |

package/docs/api/components/ClassEnumDeclaration.md

@@ -0,0 +1,111 @@
+# ClassEnumDeclaration
+
+Create a Python enum using the class-based syntax.
+
+This generates enums using the `class Name(Enum):` syntax with member definitions inside the class body. Supports various member value styles including auto-generated values, explicit values, and custom base types.
+
+* jsx
+
+  ```tsx
+  import { ClassEnumDeclaration } from "@alloy-js/python";
+
+
+  <ClassEnumDeclaration
+    auto
+    baseType={"Enum" | "IntEnum" | "StrEnum" | "Flag" | "IntFlag"}
+    doc={Children}
+    members={Array<EnumMemberProps>}
+   />
+  ```
+
+* stc
+
+  ```ts
+  import { ClassEnumDeclaration } from "@alloy-js/python/stc";
+
+
+  ClassEnumDeclaration({
+    auto: boolean,
+    baseType: "Enum" | "IntEnum" | "StrEnum" | "Flag" | "IntFlag",
+    doc: Children,
+    members: Array<EnumMemberProps>,
+  }).children(children)
+  ```
+
+## 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.                                                             |
+
+## Examples
+
+```tsx
+<ClassEnumDeclaration
+  name="Direction"
+  members={[
+    { name: "NORTH" },
+    { name: "SOUTH" },
+    { name: "EAST" },
+    { name: "WEST" }
+  ]}
+/>
+```
+
+renders to:
+
+```python
+class Direction(Enum):
+    NORTH = "NORTH"
+    SOUTH = "SOUTH"
+    EAST = "EAST"
+    WEST = "WEST"
+```
+
+With explicit values:
+
+```tsx
+<ClassEnumDeclaration
+  name="Status"
+  members={[
+    { name: "PENDING", value: 1 },
+    { name: "ACTIVE", value: 2 },
+    { name: "INACTIVE", value: 3 }
+  ]}
+/>
+```
+
+renders to:
+
+```python
+class Status(Enum):
+    PENDING = 1
+    ACTIVE = 2
+    INACTIVE = 3
+```
+
+With auto() values:
+
+```tsx
+<ClassEnumDeclaration
+  name="Color"
+  style="auto"
+  members={[
+    { name: "RED" },
+    { name: "GREEN" },
+    { name: "BLUE" }
+  ]}
+/>
+```
+
+renders to:
+
+```python
+class Color(Enum):
+    RED = auto()
+    GREEN = auto()
+    BLUE = auto()
+```

package/docs/api/components/ClassInstantiation.md

@@ -0,0 +1,44 @@
+# ClassInstantiation
+
+Used to create new instances of classes in Python.
+
+* jsx
+
+  ```tsx
+  import { ClassInstantiation } from "@alloy-js/python";
+
+
+  <ClassInstantiation args={Children[]} target={Children} />
+  ```
+
+* stc
+
+  ```ts
+  import { ClassInstantiation } from "@alloy-js/python/stc";
+
+
+  ClassInstantiation({ args: Children[], target: Children }).children(children)
+  ```
+
+## Props
+
+|        |                                                       |   |
+| ------ | ----------------------------------------------------- | - |
+| args   | optional [Children](../../../core/types/children/)\[] |   |
+| target | [Children](../../../core/types/children/)             |   |
+
+## Remarks
+
+It is similar to FunctionCallExpression but specifically for class instantiation. Args should be a list arguments that can be either simple js values or py.Atoms, which will render as positional arguments, or py.VariableDeclarations, which will render as named arguments in the call statement. This component will not check for the correctness of the python grammar and will just work with any children you provide. It is up to you to ensure that the arguments you provide are valid in the context of a class instantiation.
+
+## Example
+
+```tsx
+<ClassInstantiation target="MyClass" args={["arg1", "arg2"]} />
+```
+
+This will generate:
+
+```python
+MyClass(arg1, arg2)
+```

package/docs/api/components/ClassMethodDeclaration.md

@@ -0,0 +1,31 @@
+# ClassMethodDeclaration
+
+A Python class method declaration component.
+
+* jsx
+
+  ```tsx
+  import { ClassMethodDeclaration } from "@alloy-js/python";
+
+
+  <ClassMethodDeclaration abstract async />
+  ```
+
+* stc
+
+  ```ts
+  import { ClassMethodDeclaration } from "@alloy-js/python/stc";
+
+
+  ClassMethodDeclaration({
+    abstract: boolean,
+    async: boolean,
+  }).children(children)
+  ```
+
+## Props
+
+|          |                  |                                       |
+| -------- | ---------------- | ------------------------------------- |
+| abstract | optional boolean |                                       |
+| async    | optional boolean | Indicates that the function is async. |

package/docs/api/components/ConstructorDeclaration.md

@@ -0,0 +1,27 @@
+# ConstructorDeclaration
+
+A Python constructor declaration for `__new__`.
+
+* jsx
+
+  ```tsx
+  import { ConstructorDeclaration } from "@alloy-js/python";
+
+
+  <ConstructorDeclaration abstract />
+  ```
+
+* stc
+
+  ```ts
+  import { ConstructorDeclaration } from "@alloy-js/python/stc";
+
+
+  ConstructorDeclaration({ abstract: boolean }).children(children)
+  ```
+
+## Props
+
+|          |                  |   |
+| -------- | ---------------- | - |
+| abstract | optional boolean |   |

package/docs/api/components/DataclassDeclaration.md

@@ -0,0 +1,55 @@
+# DataclassDeclaration
+
+Renders a Python dataclass.
+
+Example:
+
+```tsx
+<py.DataclassDeclaration name="User" kwOnly>
+  <py.VariableDeclaration instanceVariable omitNone name="id" type="int" />
+  <py.VariableDeclaration instanceVariable name={namekey("_", { ignoreNamePolicy: true })} type={dataclassesModule["."].KW_ONLY} omitNone />
+  <py.VariableDeclaration
+    instanceVariable
+    name="name"
+    type="str"
+    initializer={"Anonymous"}
+  />
+</py.DataclassDeclaration>
+```
+
+Will render as:
+
+```py
+from dataclasses import dataclass
+from dataclasses import KW_ONLY
+
+@dataclass(kw_only=True)
+class User:
+    id: int
+    _: KW_ONLY
+    name: str = "Anonymous"
+```
+
+* jsx
+
+  ```tsx
+  import { DataclassDeclaration } from "@alloy-js/python";
+
+
+  <DataclassDeclaration bases={Children[]} />
+  ```
+
+* stc
+
+  ```ts
+  import { DataclassDeclaration } from "@alloy-js/python/stc";
+
+
+  DataclassDeclaration({ bases: Children[] }).children(children)
+  ```
+
+## Props
+
+|       |                                                       |                                                 |
+| ----- | ----------------------------------------------------- | ----------------------------------------------- |
+| bases | optional [Children](../../../core/types/children/)\[] | The base classes that this class inherits from. |

package/docs/api/components/Declaration.md

@@ -0,0 +1,41 @@
+# Declaration
+
+A Python declaration, which can be a class, function, variable, etc.
+
+* jsx
+
+  ```tsx
+  import { Declaration } from "@alloy-js/python";
+
+
+  <Declaration
+    name={string | Namekey}
+    nameKind={PythonElements}
+    symbol={PythonOutputSymbol}
+   />
+  ```
+
+* stc
+
+  ```ts
+  import { Declaration } from "@alloy-js/python/stc";
+
+
+  Declaration({
+    name: string | Namekey,
+    nameKind: PythonElements,
+    symbol: PythonOutputSymbol,
+  }).children(children)
+  ```
+
+## Props
+
+|          |                                                                |                                                   |
+| -------- | -------------------------------------------------------------- | ------------------------------------------------- |
+| name     | optional string \| [Namekey](../../../core/types/namekey/)     | The name of this declaration.                     |
+| nameKind | optional [PythonElements](../../types/pythonelements/)         | The name policy kind to apply to the declaration. |
+| symbol   | optional [PythonOutputSymbol](../../types/pythonoutputsymbol/) | The symbol to use for this declaration.           |
+
+## Remarks
+
+This component is used to create a declaration with a symbol that can be referenced in the code.

package/docs/api/components/DunderMethodDeclaration.md

@@ -0,0 +1,31 @@
+# DunderMethodDeclaration
+
+A Python dunder method declaration.
+
+* jsx
+
+  ```tsx
+  import { DunderMethodDeclaration } from "@alloy-js/python";
+
+
+  <DunderMethodDeclaration abstract async />
+  ```
+
+* stc
+
+  ```ts
+  import { DunderMethodDeclaration } from "@alloy-js/python/stc";
+
+
+  DunderMethodDeclaration({
+    abstract: boolean,
+    async: boolean,
+  }).children(children)
+  ```
+
+## Props
+
+|          |                  |                                       |
+| -------- | ---------------- | ------------------------------------- |
+| abstract | optional boolean |                                       |
+| async    | optional boolean | Indicates that the function is async. |

package/docs/api/components/EnumMember.md

@@ -0,0 +1,61 @@
+# EnumMember
+
+A Python enum member.
+
+* jsx
+
+  ```tsx
+  import { EnumMember } from "@alloy-js/python";
+
+
+  <EnumMember
+    auto
+    doc={Children}
+    functional
+    jsValue={string | number}
+    name={string | Namekey}
+    refkey={Refkey}
+    value={Children}
+   />
+  ```
+
+* stc
+
+  ```ts
+  import { EnumMember } from "@alloy-js/python/stc";
+
+
+  EnumMember({
+    auto: boolean,
+    doc: Children,
+    functional: boolean,
+    jsValue: string | number,
+    name: string | Namekey,
+    refkey: Refkey,
+    value: Children,
+  }).children(children)
+  ```
+
+## Props
+
+|            |                                                    |                                                                                                                                           |
+| ---------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| auto       | optional boolean                                   | Will use auto() to generate the value if set to true.                                                                                     |
+| doc        | optional [Children](../../../core/types/children/) | Documentation for the enum member.                                                                                                        |
+| functional | optional boolean                                   | Functional mappings/list                                                                                                                  |
+| jsValue    | optional string \| number                          | The JS value of the enum member.                                                                                                          |
+| name       | string \| [Namekey](../../../core/types/namekey/)  | The name of the enum member.                                                                                                              |
+| refkey     | optional [Refkey](../../../core/types/refkey/)     | Refkey for the enum member symbol. If the refkey is not provided, a symbol will be created and the member cannot be referenced by refkey. |
+| value      | optional [Children](../../../core/types/children/) | The value of the enum member.                                                                                                             |
+
+## Example
+
+```tsx
+<EnumMember name="NORTH" />
+```
+
+This will generate:
+
+```python
+NORTH
+```