@alloy-js/python 0.4.0-dev.3 → 0.4.0-dev.6

package/docs/api/components/ModuleDoc.md

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

package/docs/api/components/PropertyDeclaration.md

@@ -0,0 +1,46 @@
+# PropertyDeclaration
+
+Declares a Python property with optional getter, setter, and deleter methods.
+
+* jsx
+
+  ```tsx
+  import { PropertyDeclaration } from "@alloy-js/python";
+
+
+  <PropertyDeclaration
+    abstract
+    doc={Children}
+    name="string"
+    refkey={Refkey}
+    type={Children}
+  >
+    {children}
+  </PropertyDeclaration>
+  ```
+
+* stc
+
+  ```ts
+  import { PropertyDeclaration } from "@alloy-js/python/stc";
+
+
+  PropertyDeclaration({
+    abstract: boolean,
+    doc: Children,
+    name: string,
+    refkey: Refkey,
+    type: Children,
+  }).children(children)
+  ```
+
+## 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/) |   |

package/docs/api/components/PropertyDoc.md

@@ -0,0 +1,52 @@
+# PropertyDoc
+
+A component that creates a PropertyDoc block for `@property` decorated methods.
+
+* jsx
+
+  ```tsx
+  import { PropertyDoc } from "@alloy-js/python";
+
+
+  <PropertyDoc
+    deprecated="string"
+    description={Children[]}
+    examples={Children[]}
+    note="string"
+    returns="string"
+    seeAlso={string[]}
+    style={"google"}
+    warning="string"
+   />
+  ```
+
+* stc
+
+  ```ts
+  import { PropertyDoc } from "@alloy-js/python/stc";
+
+
+  PropertyDoc({
+    deprecated: string,
+    description: Children[],
+    examples: Children[],
+    note: 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                                       |   |
+| returns     | optional string                                       |   |
+| seeAlso     | optional string\[]                                    |   |
+| style       | optional “google”                                     |   |
+| warning     | optional string                                       |   |

package/docs/api/components/PyDoc.md

@@ -0,0 +1,29 @@
+# PyDoc
+
+A PyDoc comment. The children of this component are joined with two hard linebreaks. This is useful for creating PyDoc comments with multiple paragraphs.
+
+* jsx
+
+  ```tsx
+  import { PyDoc } from "@alloy-js/python";
+
+
+  <PyDoc >
+    {children}
+  </PyDoc>
+  ```
+
+* stc
+
+  ```ts
+  import { PyDoc } from "@alloy-js/python/stc";
+
+
+  PyDoc({  }).children(children)
+  ```
+
+## Props
+
+|          |                                           |   |
+| -------- | ----------------------------------------- | - |
+| children | [Children](../../../core/types/children/) |   |

package/docs/api/components/PyDocExample.md

@@ -0,0 +1,29 @@
+# PyDocExample
+
+Create a PyDoc example, which is prepended by >>.
+
+* jsx
+
+  ```tsx
+  import { PyDocExample } from "@alloy-js/python";
+
+
+  <PyDocExample >
+    {children}
+  </PyDocExample>
+  ```
+
+* stc
+
+  ```ts
+  import { PyDocExample } from "@alloy-js/python/stc";
+
+
+  PyDocExample({  }).children(children)
+  ```
+
+## Props
+
+|          |                                           |   |
+| -------- | ----------------------------------------- | - |
+| children | [Children](../../../core/types/children/) |   |

package/docs/api/components/PythonBlock.md

@@ -0,0 +1,47 @@
+# PythonBlock
+
+A Python block component that can be used to render a block of Python code.
+
+* jsx
+
+  ```tsx
+  import { PythonBlock } from "@alloy-js/python";
+
+
+  <PythonBlock opener="string">
+    {children}
+  </PythonBlock>
+  ```
+
+* stc
+
+  ```ts
+  import { PythonBlock } from "@alloy-js/python/stc";
+
+
+  PythonBlock({ opener: string }).children(children)
+  ```
+
+## Props
+
+|          |                                           |   |
+| -------- | ----------------------------------------- | - |
+| children | [Children](../../../core/types/children/) |   |
+| opener   | optional string                           |   |
+
+## Example
+
+```tsx
+<PythonBlock opener="def my_function()">
+  <VariableDeclaration name="x" type="int" />
+  <VariableDeclaration name="y" type="str" />
+</PythonBlock>
+```
+
+renders to
+
+```py
+def my_function():
+  x: int = None
+  y: str = None
+```

package/docs/api/components/Reference.md

@@ -0,0 +1,31 @@
+# Reference
+
+A Python reference to a symbol, such as a variable, function, or class.
+
+* jsx
+
+  ```tsx
+  import { Reference } from "@alloy-js/python";
+
+
+  <Reference refkey={Refkey} />
+  ```
+
+* stc
+
+  ```ts
+  import { Reference } from "@alloy-js/python/stc";
+
+
+  Reference({ refkey: Refkey }).children(children)
+  ```
+
+## Props
+
+|        |                                       |   |
+| ------ | ------------------------------------- | - |
+| refkey | [Refkey](../../../core/types/refkey/) |   |
+
+## Remarks
+
+This component is used to render references to symbols in Python code. It takes a `refkey` prop which is the key of the symbol to reference.

package/docs/api/components/SimpleCommentBlock.md

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

package/docs/api/components/SimpleInlineComment.md

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

package/docs/api/components/SourceFile.md

@@ -0,0 +1,83 @@
+# SourceFile
+
+A Python source file component that represents a Python file in the source directory. It provides a scope for the file, which is a [`PythonModuleScope`](../types/PythonModuleScope.md) that contains all the symbols defined in the file, such as functions, classes, and variables.
+
+* jsx
+
+  ```tsx
+  import { SourceFile } from "@alloy-js/python";
+
+
+  <SourceFile
+    doc={Children}
+    futureImports={Children[]}
+    header={Children}
+    headerComment="string"
+    path="string"
+  >
+    {children}
+  </SourceFile>
+  ```
+
+* stc
+
+  ```ts
+  import { SourceFile } from "@alloy-js/python/stc";
+
+
+  SourceFile({
+    doc: Children,
+    futureImports: Children[],
+    header: Children,
+    headerComment: string,
+    path: string,
+  }).children(children)
+  ```
+
+## Props
+
+|               |                                                       |                                                                                                                                                       |
+| ------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| children      | optional [Children](../../../core/types/children/)    | Content to add to the file, such as function definitions, class definitions, and variable declarations.                                               |
+| doc           | optional [Children](../../../core/types/children/)    | Documentation for this module, which will be rendered as a module-level docstring.                                                                    |
+| futureImports | optional [Children](../../../core/types/children/)\[] | **future** imports to render after the docstring but before regular imports.                                                                          |
+| header        | optional [Children](../../../core/types/children/)    | Content to render at the very top of the file, before everything else. Use this for shebang lines, encoding declarations, or license headers.         |
+| headerComment | optional string                                       | Comment to add at the top of the file, rendered as a Python comment block. This is a convenience prop for adding copyright notices or other comments. |
+| path          | string                                                | The path to the file relative to the source directory.                                                                                                |
+
+## Examples
+
+```tsx
+<SourceFile path="test.py">
+  <FunctionDeclaration name="test" />
+</SourceFile>
+```
+
+renders to
+
+```py
+def test():
+  pass
+```
+
+With module documentation:
+
+```tsx
+<SourceFile
+  path="utils.py"
+  doc={<ModuleDoc description={[<Prose>Utility functions for data processing.</Prose>]} />}
+>
+  <FunctionDeclaration name="process_data" />
+</SourceFile>
+```
+
+renders to
+
+```py
+"""
+Utility functions for data processing.
+"""
+
+def process_data():
+  pass
+```

package/docs/api/components/StatementList.md

@@ -0,0 +1,47 @@
+# StatementList
+
+A Python statement list, which is a list of statements that can be rendered in a Python source file.
+
+* jsx
+
+  ```tsx
+  import { StatementList } from "@alloy-js/python";
+
+
+  <StatementList >
+    {children}
+  </StatementList>
+  ```
+
+* stc
+
+  ```ts
+  import { StatementList } from "@alloy-js/python/stc";
+
+
+  StatementList({  }).children(children)
+  ```
+
+## Props
+
+|          |                                           |   |
+| -------- | ----------------------------------------- | - |
+| children | [Children](../../../core/types/children/) |   |
+
+## Example
+
+```tsx
+<StatementList>
+  <FunctionDeclaration name="test" />
+  <VariableDeclaration name="x" value={42} />
+</StatementList>
+```
+
+renders to
+
+```py
+def test():
+  pass
+
+x = 42
+```

package/docs/api/components/StaticMethodDeclaration.md

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

package/docs/api/components/TypeArguments.md

@@ -0,0 +1,27 @@
+# TypeArguments
+
+Render Python-style type arguments, e.g. \[T, P].
+
+* jsx
+
+  ```tsx
+  import { TypeArguments } from "@alloy-js/python";
+
+
+  <TypeArguments args={Children[]} />
+  ```
+
+* stc
+
+  ```ts
+  import { TypeArguments } from "@alloy-js/python/stc";
+
+
+  TypeArguments({ args: Children[] }).children(children)
+  ```
+
+## Props
+
+|      |                                              |   |
+| ---- | -------------------------------------------- | - |
+| args | [Children](../../../core/types/children/)\[] |   |

package/docs/api/components/TypeRefContext.md

@@ -0,0 +1,41 @@
+# TypeRefContext
+
+Set the current context of reference to be type reference.
+
+* jsx
+
+  ```tsx
+  import { TypeRefContext } from "@alloy-js/python";
+
+
+  <TypeRefContext >
+    {children}
+  </TypeRefContext>
+  ```
+
+* stc
+
+  ```ts
+  import { TypeRefContext } from "@alloy-js/python/stc";
+
+
+  TypeRefContext({  }).children(children)
+  ```
+
+## Props
+
+|          |                                           |          |
+| -------- | ----------------------------------------- | -------- |
+| children | [Children](../../../core/types/children/) | Children |
+
+## Remarks
+
+References used inside the children of this component will be treated as type-only references. When a symbol is only referenced in type contexts, it will be imported inside a `if TYPE_CHECKING:` block.
+
+## Example
+
+```tsx
+<TypeRefContext>
+  {someTypeRefkey}
+</TypeRefContext>
+```

package/docs/api/components/TypeReference.md

@@ -0,0 +1,37 @@
+# TypeReference
+
+A type reference like Foo\[T, P] or int.
+
+* jsx
+
+  ```tsx
+  import { TypeReference } from "@alloy-js/python";
+
+
+  <TypeReference name={Children} refkey={Refkey} typeArgs={Children[]} />
+  ```
+
+* stc
+
+  ```ts
+  import { TypeReference } from "@alloy-js/python/stc";
+
+
+  TypeReference({
+    name: Children,
+    refkey: Refkey,
+    typeArgs: Children[],
+  }).children(children)
+  ```
+
+## Props
+
+|          |                                                       |                                                     |
+| -------- | ----------------------------------------------------- | --------------------------------------------------- |
+| name     | optional [Children](../../../core/types/children/)    | A raw name to reference when no refkey is provided. |
+| refkey   | optional [Refkey](../../../core/types/refkey/)        | A refkey to a declared symbol.                      |
+| typeArgs | optional [Children](../../../core/types/children/)\[] | Type arguments to render inside brackets.           |
+
+## Remarks
+
+This component automatically wraps its content in a type reference context, so any symbols referenced via refkey will be imported as type-only (inside a `if TYPE_CHECKING:` block) unless also used as values elsewhere.

package/docs/api/components/UnionTypeExpression.md

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