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

package/docs/api/components/ExceptionDoc.md

@@ -0,0 +1,55 @@
+# ExceptionDoc
+
+A component that creates an ExceptionDoc block for custom exception classes.
+
+* jsx
+
+  ```tsx
+  import { ExceptionDoc } from "@alloy-js/python";
+
+
+  <ExceptionDoc
+    attributes={GoogleStyleDocAttributeProps[]}
+    deprecated="string"
+    description={Children[]}
+    examples={Children[]}
+    note="string"
+    parameters={ParameterDescriptor[]}
+    seeAlso={string[]}
+    style={"google"}
+    warning="string"
+   />
+  ```
+
+* stc
+
+  ```ts
+  import { ExceptionDoc } from "@alloy-js/python/stc";
+
+
+  ExceptionDoc({
+    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/FunctionCallExpression.md

@@ -0,0 +1,43 @@
+# FunctionCallExpression
+
+A Python function call expression.
+
+* jsx
+
+  ```tsx
+  import { FunctionCallExpression } from "@alloy-js/python";
+
+
+  <FunctionCallExpression args={Children[]} target={Children} />
+  ```
+
+* stc
+
+  ```ts
+  import { FunctionCallExpression } from "@alloy-js/python/stc";
+
+
+  FunctionCallExpression({
+    args: Children[],
+    target: Children,
+  }).children(children)
+  ```
+
+## Props
+
+|        |                                                       |   |
+| ------ | ----------------------------------------------------- | - |
+| args   | optional [Children](../../../core/types/children/)\[] |   |
+| target | [Children](../../../core/types/children/)             |   |
+
+## Example
+
+```tsx
+<FunctionCallExpression target="foo" args={["arg1", "arg2"]} />
+```
+
+This will generate:
+
+```python
+foo(arg1, arg2)
+```

package/docs/api/components/FunctionDeclaration.md

@@ -0,0 +1,50 @@
+# FunctionDeclaration
+
+A Python function declaration.
+
+* jsx
+
+  ```tsx
+  import { FunctionDeclaration } from "@alloy-js/python";
+
+
+  <FunctionDeclaration async />
+  ```
+
+* stc
+
+  ```ts
+  import { FunctionDeclaration } from "@alloy-js/python/stc";
+
+
+  FunctionDeclaration({ async: boolean }).children(children)
+  ```
+
+## Props
+
+|       |                  |                                       |
+| ----- | ---------------- | ------------------------------------- |
+| async | optional boolean | Indicates that the function is async. |
+
+## Remarks
+
+This component creates a Python function declaration with optional type annotations, parameters, and return types. It supports async functions and automatically handles symbol creation and emission.
+
+## Example
+
+```tsx
+<FunctionDeclaration
+  name="my_function"
+  returnType="int"
+  parameters={[{ name: "a", type: { children: "int" } }, { name: "b", type: { children: "str" } }]}
+>
+  return a + b
+</FunctionDeclaration>
+```
+
+This will generate:
+
+```python
+def my_function(a: int, b: str) -> int:
+    return a + b
+```

package/docs/api/components/FunctionDoc.md

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

package/docs/api/components/FunctionalEnumDeclaration.md

@@ -0,0 +1,79 @@
+# FunctionalEnumDeclaration
+
+Create a Python enum using the functional syntax.
+
+This generates enums using the `Enum('Name', [...])` or `Enum('Name', {...})` syntax. The format depends on whether enum members have explicit values:
+
+* Members without values: `Enum('Direction', ['NORTH', 'SOUTH', 'EAST', 'WEST'])`
+* Members with values: `Enum('Direction', {'NORTH': 1, 'SOUTH': 2, 'EAST': 3, 'WEST': 4})`
+
+- jsx
+
+  ```tsx
+  import { FunctionalEnumDeclaration } from "@alloy-js/python";
+
+
+  <FunctionalEnumDeclaration
+    baseType={"Enum" | "IntEnum" | "StrEnum" | "Flag" | "IntFlag"}
+    doc={Children}
+    members={Array<EnumMemberProps>}
+   />
+  ```
+
+- stc
+
+  ```ts
+  import { FunctionalEnumDeclaration } from "@alloy-js/python/stc";
+
+
+  FunctionalEnumDeclaration({
+    baseType: "Enum" | "IntEnum" | "StrEnum" | "Flag" | "IntFlag",
+    doc: Children,
+    members: Array<EnumMemberProps>,
+  }).children(children)
+  ```
+
+## Props
+
+|          |                                                                  |                                                                                                         |
+| -------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| 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
+<FunctionalEnumDeclaration
+  name="Direction"
+  members={[
+    { name: "NORTH" },
+    { name: "SOUTH" },
+    { name: "EAST" },
+    { name: "WEST" }
+  ]}
+/>
+```
+
+renders to:
+
+```python
+Direction = Enum('Direction', ['NORTH', 'SOUTH', 'EAST', 'WEST'])
+```
+
+```tsx
+<FunctionalEnumDeclaration
+  name="Status"
+  members={[
+    { name: "PENDING", value: 1 },
+    { name: "ACTIVE", value: 2 },
+    { name: "INACTIVE", value: 3 }
+  ]}
+/>
+```
+
+renders to:
+
+```python
+Status = Enum('Status', {'PENDING': 1, 'ACTIVE': 2, 'INACTIVE': 3})
+```

package/docs/api/components/FutureStatement.md

@@ -0,0 +1,51 @@
+# FutureStatement
+
+A future statement that imports features from **future**.
+
+Future statements are directives to the compiler that a particular module should be compiled using syntax or semantics from a future Python release. They must appear near the top of the module, after the module docstring (if any).
+
+Use this in the `futureImports` prop of SourceFile to ensure proper placement.
+
+* jsx
+
+  ```tsx
+  import { FutureStatement } from "@alloy-js/python";
+
+
+  <FutureStatement feature="string" />
+  ```
+
+* stc
+
+  ```ts
+  import { FutureStatement } from "@alloy-js/python/stc";
+
+
+  FutureStatement({ feature: string }).children(children)
+  ```
+
+## Props
+
+|         |        |                                                    |
+| ------- | ------ | -------------------------------------------------- |
+| feature | string | The name of the feature to import from **future**. |
+
+## Example
+
+```tsx
+<SourceFile path="models.py" futureImports={<FutureStatement feature="annotations" />}>
+  <ClassDeclaration name="User">
+    <PropertyDeclaration name="manager" type="User" />
+  </ClassDeclaration>
+</SourceFile>
+```
+
+renders to
+
+```py
+from __future__ import annotations
+
+
+class User:
+    manager: User
+```

package/docs/api/components/GeneratorDoc.md

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

package/docs/api/components/InlineDoc.md

@@ -0,0 +1,29 @@
+# InlineDoc
+
+An inline documentation component for attribute docstrings. Unlike PyDoc, this doesn’t add a trailing line break after the closing quotes, which is appropriate for documenting consecutive attributes like enum members.
+
+* jsx
+
+  ```tsx
+  import { InlineDoc } from "@alloy-js/python";
+
+
+  <InlineDoc >
+    {children}
+  </InlineDoc>
+  ```
+
+* stc
+
+  ```ts
+  import { InlineDoc } from "@alloy-js/python/stc";
+
+
+  InlineDoc({  }).children(children)
+  ```
+
+## Props
+
+|          |                                           |   |
+| -------- | ----------------------------------------- | - |
+| children | [Children](../../../core/types/children/) |   |

package/docs/api/components/LexicalScope.md

@@ -0,0 +1,65 @@
+# LexicalScope
+
+## Overload 1
+
+* jsx
+
+  ```tsx
+  import { LexicalScope } from "@alloy-js/python";
+
+
+  <LexicalScope value={OutputScope} />
+  ```
+
+* stc
+
+  ```ts
+  import { LexicalScope } from "@alloy-js/python/stc";
+
+
+  LexicalScope({ value: OutputScope }).children(children)
+  ```
+
+### Props
+
+|          |                                                    |                                                                 |
+| -------- | -------------------------------------------------- | --------------------------------------------------------------- |
+| children | optional [Children](../../../core/types/children/) |                                                                 |
+| value    | [OutputScope](../../../core/types/outputscope/)    | The scope to use. If not provided, a new scope will be created. |
+
+## Overload 2
+
+* jsx
+
+  ```tsx
+  import { LexicalScope } from "@alloy-js/python";
+
+
+  <LexicalScope
+    metadata={Record<string, unknown>}
+    name="string"
+    ownerSymbol={OutputSymbol}
+   />
+  ```
+
+* stc
+
+  ```ts
+  import { LexicalScope } from "@alloy-js/python/stc";
+
+
+  LexicalScope({
+    metadata: Record<string, unknown>,
+    name: string,
+    ownerSymbol: OutputSymbol,
+  }).children(children)
+  ```
+
+### Props
+
+|             |                                                            |                                                                             |
+| ----------- | ---------------------------------------------------------- | --------------------------------------------------------------------------- |
+| children    | optional [Children](../../../core/types/children/)         |                                                                             |
+| metadata    | optional Record\<string, unknown>                          | Additional metadata for the scope.                                          |
+| name        | optional string                                            | The name of this scope.                                                     |
+| ownerSymbol | optional [OutputSymbol](../../../core/types/outputsymbol/) | Create a member scope with the owner symbol providing the in-scope symbols. |

package/docs/api/components/MemberExpression.md

@@ -0,0 +1,53 @@
+# MemberExpression
+
+Create a member expression from parts. Each part can provide one of the following:
+
+* **id**: The identifier for the member expression part
+* **refkey**: a refkey for a symbol whose name becomes the identifier
+* **symbol**: a symbol whose name becomes the identifier part
+* **args**: create a method call with the given args
+* **children**: arbitrary contents for the identifier part.
+
+- jsx
+
+  ```tsx
+  import { MemberExpression } from "@alloy-js/python";
+
+
+  <MemberExpression >
+    {children}
+  </MemberExpression>
+  ```
+
+- stc
+
+  ```ts
+  import { MemberExpression } from "@alloy-js/python/stc";
+
+
+  MemberExpression({  }).children(children)
+  ```
+
+## Props
+
+|          |                                           |   |
+| -------- | ----------------------------------------- | - |
+| children | [Children](../../../core/types/children/) |   |
+
+## Example
+
+```tsx
+<MemberExpression>
+  <MemberExpression.Part id="base" />
+  <MemberExpression.Part refkey={rk} />
+  <MemberExpression.Part symbol={sym} />
+  <MemberExpression.Part args={["hello", "world"]} />
+  <MemberExpression.Part>SomeValue</MemberExpression.Part>
+</MemberExpression>
+```
+
+Assuming `rk` is a refkey to a symbol name “prop1”, and `sym` is a symbol with a name of “prop2”, this will render:
+
+```ts
+base.prop1.prop2("hello", "world").SomeValue
+```

package/docs/api/components/MemberScope.md

@@ -0,0 +1,28 @@
+# MemberScope
+
+* jsx
+
+  ```tsx
+  import { MemberScope } from "@alloy-js/python";
+
+
+  <MemberScope ownerSymbol={PythonOutputSymbol}>
+    {children}
+  </MemberScope>
+  ```
+
+* stc
+
+  ```ts
+  import { MemberScope } from "@alloy-js/python/stc";
+
+
+  MemberScope({ ownerSymbol: PythonOutputSymbol }).children(children)
+  ```
+
+## Props
+
+|             |                                                       |   |
+| ----------- | ----------------------------------------------------- | - |
+| children    | [Children](../../../core/types/children/)             |   |
+| ownerSymbol | [PythonOutputSymbol](../../types/pythonoutputsymbol/) |   |

package/docs/api/components/MethodDeclaration.md

@@ -0,0 +1,49 @@
+# MethodDeclaration
+
+A Python instance method declaration component.
+
+Shared base props for all method-like declarations.
+
+* jsx
+
+  ```tsx
+  import { MethodDeclaration } from "@alloy-js/python";
+
+
+  <MethodDeclaration abstract async />
+  ```
+
+* stc
+
+  ```ts
+  import { MethodDeclaration } from "@alloy-js/python/stc";
+
+
+  MethodDeclaration({ abstract: boolean, async: boolean }).children(children)
+  ```
+
+## Props
+
+|          |                  |                                        |
+| -------- | ---------------- | -------------------------------------- |
+| abstract | optional boolean | Indicates that the method is abstract. |
+| async    | optional boolean | Indicates that the function is async.  |
+
+## Remarks
+
+Automatically injects the `self` parameter for instance methods and enforces that the declaration appears within a class body.
+
+## Example
+
+```tsx
+<py.MethodDeclaration name="do_work" parameters={[{ name: "value", type: "int" }]}>
+  return value * 2
+</py.MethodDeclaration>
+```
+
+Generates:
+
+```python
+def do_work(self, value: int) -> None:
+    return value * 2
+```

package/docs/api/components/MethodDoc.md

@@ -0,0 +1,61 @@
+# MethodDoc
+
+A component that creates a MethodDoc block for class methods. Automatically adds a note about not including ‘self’ parameter if no custom note is provided.
+
+* jsx
+
+  ```tsx
+  import { MethodDoc } from "@alloy-js/python";
+
+
+  <MethodDoc
+    deprecated="string"
+    description={Children[]}
+    examples={Children[]}
+    note="string"
+    overrides="string"
+    parameters={ParameterDescriptor[]}
+    raises={string[]}
+    returns="string"
+    seeAlso={string[]}
+    style={"google"}
+    warning="string"
+   />
+  ```
+
+* stc
+
+  ```ts
+  import { MethodDoc } from "@alloy-js/python/stc";
+
+
+  MethodDoc({
+    deprecated: string,
+    description: Children[],
+    examples: Children[],
+    note: string,
+    overrides: string,
+    parameters: ParameterDescriptor[],
+    raises: string[],
+    returns: string,
+    seeAlso: string[],
+    style: "google",
+    warning: string,
+  }).children(children)
+  ```
+
+## Props
+
+|             |                                                                     |   |
+| ----------- | ------------------------------------------------------------------- | - |
+| deprecated  | optional string                                                     |   |
+| description | [Children](../../../core/types/children/)\[]                        |   |
+| examples    | optional [Children](../../../core/types/children/)\[]               |   |
+| note        | optional string                                                     |   |
+| overrides   | optional string                                                     |   |
+| parameters  | optional [ParameterDescriptor](../../types/parameterdescriptor/)\[] |   |
+| raises      | optional string\[]                                                  |   |
+| returns     | optional string                                                     |   |
+| seeAlso     | optional string\[]                                                  |   |
+| style       | optional “google”                                                   |   |
+| warning     | optional string                                                     |   |