@alloy-js/python 0.0.1

package/dist/src/components/PyDoc.js

@@ -0,0 +1,280 @@
+import { memo as _$memo, createComponent as _$createComponent, createIntrinsic as _$createIntrinsic } from "@alloy-js/core/jsx-runtime";
+import { For, Indent, List, Prose, Show, childrenArray } from "@alloy-js/core";
+import { Atom } from "./index.js";
+function GoogleStyleDocParamType(props) {
+  return [_$createComponent(Show, {
+    get when() {
+      return Boolean(props.type);
+    },
+    get children() {
+      return [" (", _$memo(() => props.type), _$createComponent(Show, {
+        get when() {
+          return props.optional;
+        },
+        children: ", optional"
+      }), ")"];
+    }
+  })];
+}
+function GoogleStyleDocParamName(props) {
+  return [_$memo(() => props.name)];
+}
+function GoogleStyleDocParamDescription(props) {
+  return _$createComponent(Show, {
+    get when() {
+      return Boolean(props.children);
+    },
+    get children() {
+      return [": ", _$createIntrinsic("align", {
+        width: 4,
+        get children() {
+          return [_$createComponent(Prose, {
+            get children() {
+              return props.children;
+            }
+          }), _$createComponent(Show, {
+            get when() {
+              return Boolean(props.defaultValue);
+            },
+            get children() {
+              return [" ", "Defaults to ", _$createComponent(Atom, {
+                get jsValue() {
+                  return props.defaultValue;
+                }
+              }), "."];
+            }
+          })];
+        }
+      })];
+    }
+  });
+}
+/**
+ * Create a GoogleStyleDoc parameter.
+ */
+export function GoogleStyleDocParam(props) {
+  return [_$createComponent(GoogleStyleDocParamName, {
+    get name() {
+      return props.name;
+    }
+  }), _$createComponent(GoogleStyleDocParamType, {
+    get type() {
+      return props.type;
+    },
+    get optional() {
+      return props.optional;
+    }
+  }), _$createComponent(GoogleStyleDocParamDescription, {
+    get children() {
+      return props.children;
+    },
+    get defaultValue() {
+      return props.defaultValue;
+    }
+  })];
+}
+/**
+ * A component that creates a GoogleStyleDoc block for parameters.
+ */
+export function GoogleStyleDocParams(props) {
+  const parameters = normalizeParametersForDoc(props.parameters);
+  return ["Args:", _$createComponent(Indent, {
+    get children() {
+      return _$createComponent(List, {
+        doubleHardline: true,
+        get children() {
+          return parameters.map(param => _$createComponent(GoogleStyleDocParam, {
+            get name() {
+              return param.name;
+            },
+            get type() {
+              return param.type;
+            },
+            get optional() {
+              return param.optional;
+            },
+            get children() {
+              return param.doc;
+            }
+          }));
+        }
+      });
+    }
+  })];
+}
+/**
+ * A component that creates a GoogleStyleDoc block for parameters.
+ */
+export function GoogleStyleDocReturn(props) {
+  return ["Returns:", _$createComponent(Indent, {
+    get children() {
+      return props.message;
+    }
+  })];
+}
+/**
+ * A component that creates a GoogleStyleDoc block for parameters.
+ */
+export function GoogleStyleDocRaises(props) {
+  return ["Raises:", _$createComponent(Indent, {
+    get children() {
+      return props.message;
+    }
+  })];
+}
+/**
+ * A component that creates a GoogleStyleFunctionDoc block for parameters.
+ */
+export function GoogleStyleFunctionDoc(props) {
+  // We are creating a list instead of relying on <Show> because otherwise
+  // <List> would render spaces between the elements even if <Show> evaluates to false.
+  const children = [];
+  if (props.description !== undefined) {
+    children.push(_$createComponent(List, {
+      doubleHardline: true,
+      get children() {
+        return props.description.map(param => param);
+      }
+    }));
+  }
+  if (props.parameters !== undefined && props.parameters.length > 0) {
+    children.push(_$createComponent(GoogleStyleDocParams, {
+      get parameters() {
+        return props.parameters;
+      }
+    }));
+  }
+  if (props.returns !== undefined) {
+    children.push(_$createComponent(GoogleStyleDocReturn, {
+      get message() {
+        return props.returns;
+      }
+    }));
+  }
+  if (props.raises !== undefined && props.raises.length > 0) {
+    children.push(props.raises.map(param => _$createComponent(GoogleStyleDocRaises, {
+      message: param
+    })));
+  }
+  return _$createComponent(PyDoc, {
+    children: children
+  });
+}
+/**
+ * A component that creates a FunctionDoc block for parameters.
+ */
+export function FunctionDoc(props) {
+  const style = props.style ?? "google";
+  if (style === "google") {
+    return _$createComponent(GoogleStyleFunctionDoc, {
+      get description() {
+        return props.description;
+      },
+      get parameters() {
+        return props.parameters;
+      },
+      get returns() {
+        return props.returns;
+      },
+      get raises() {
+        return props.raises;
+      }
+    });
+  }
+}
+/**
+ * A component that creates a ClassDoc block for parameters.
+ */
+export function ClassDoc(props) {
+  const style = props.style ?? "google";
+  if (style === "google") {
+    return _$createComponent(GoogleStyleClassDoc, {
+      get description() {
+        return props.description;
+      },
+      get parameters() {
+        return props.parameters;
+      }
+    });
+  }
+}
+/**
+ * A component that creates a GoogleStyleClassDoc block for parameters.
+ */
+export function GoogleStyleClassDoc(props) {
+  // We are creating a list instead of relying on <Show> because otherwise
+  // <List> would render spaces between the elements even if <Show> evaluates to false.
+  const children = [];
+  if (props.description !== undefined) {
+    children.push(_$createComponent(List, {
+      doubleHardline: true,
+      get children() {
+        return props.description.map(param => param);
+      }
+    }));
+  }
+  if (props.parameters !== undefined && props.parameters.length > 0) {
+    children.push(_$createComponent(GoogleStyleDocParams, {
+      get parameters() {
+        return props.parameters;
+      }
+    }));
+  }
+  return _$createComponent(PyDoc, {
+    children: children
+  });
+}
+/**
+ * Create a PyDoc example, which is prepended by \>\>.
+ */
+export function PyDocExample(props) {
+  const children = childrenArray(() => props.children);
+  let lines = [];
+  if (children.length === 1 && typeof children[0] === "string") {
+    // Split, trim each line, and filter out empty lines
+    lines = children[0].split(/\r?\n/).map(line => line.trim()).filter(line => line.length > 0);
+  } else {
+    // For non-string children, filter out empty/whitespace-only strings
+    lines = children.map(child => typeof child === "string" ? child : "").map(line => line.trim()).filter(line => line.length > 0);
+  }
+  return [_$createComponent(For, {
+    each: lines,
+    children: line => [">> ", line]
+  })];
+}
+function normalizeParametersForDoc(parameters) {
+  if (parameters.some(p => typeof p === "string")) {
+    return [];
+  }
+  return parameters;
+}
+/**
+ * A PyDoc comment. The children of this component are joined with two hard
+ * linebreaks. This is useful for creating PyDoc comments with multiple paragraphs.
+ */
+export function PyDoc(props) {
+  const children = childrenArray(() => props.children);
+  return ['"""', _$createIntrinsic("hbr", {}), _$createComponent(List, {
+    doubleHardline: true,
+    children: children
+  }), _$createIntrinsic("hbr", {}), '"""', _$createIntrinsic("hbr", {})];
+}
+export function SimpleCommentBlock(props) {
+  return ["#", " ", _$createIntrinsic("align", {
+    string: "# ",
+    get children() {
+      return _$createComponent(Prose, {
+        get children() {
+          return props.children;
+        }
+      });
+    }
+  })];
+}
+export function SimpleInlineComment(props) {
+  return ["  ", "# ", _$createComponent(Prose, {
+    get children() {
+      return props.children;
+    }
+  })];
+}

package/dist/src/components/PythonBlock.d.ts

@@ -0,0 +1,23 @@
+import { Children } from "@alloy-js/core";
+/**
+ * A Python block component that can be used to render a block of Python code.
+ *
+ * @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
+ * ```
+ */
+export declare function PythonBlock(props: {
+    children: Children;
+    opener?: string;
+}): Children;
+//# sourceMappingURL=PythonBlock.d.ts.map

package/dist/src/components/PythonBlock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PythonBlock.d.ts","sourceRoot":"","sources":["../../../src/components/PythonBlock.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAS,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,YAMzE"}

package/dist/src/components/PythonBlock.js

@@ -0,0 +1,31 @@
+import { memo as _$memo, createComponent as _$createComponent } from "@alloy-js/core/jsx-runtime";
+import { Block } from "@alloy-js/core";
+
+/**
+ * A Python block component that can be used to render a block of Python code.
+ *
+ * @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
+ * ```
+ */
+export function PythonBlock(props) {
+  return _$createComponent(Block, {
+    get opener() {
+      return props.opener ?? "";
+    },
+    closer: "",
+    get children() {
+      return props.children;
+    }
+  });
+}

package/dist/src/components/Reference.d.ts

@@ -0,0 +1,13 @@
+import { Refkey } from "@alloy-js/core";
+export interface ReferenceProps {
+    refkey: Refkey;
+}
+/**
+ * A Python reference to a symbol, such as a variable, function, or class.
+ *
+ * @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.
+ */
+export declare function Reference({ refkey }: ReferenceProps): import("@alloy-js/core").Children;
+//# sourceMappingURL=Reference.d.ts.map

package/dist/src/components/Reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Reference.d.ts","sourceRoot":"","sources":["../../../src/components/Reference.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAwB,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAG9D,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,EAAE,MAAM,EAAE,EAAE,cAAc,qCAMnD"}

package/dist/src/components/Reference.js

@@ -0,0 +1,18 @@
+import { memo as _$memo } from "@alloy-js/core/jsx-runtime";
+import { computed, emitSymbol } from "@alloy-js/core";
+import { ref } from "../symbols/index.js";
+/**
+ * A Python reference to a symbol, such as a variable, function, or class.
+ *
+ * @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.
+ */
+export function Reference({
+  refkey
+}) {
+  const reference = ref(refkey);
+  const symbolRef = computed(() => reference()[1]);
+  emitSymbol(symbolRef);
+  return [_$memo(() => reference()[0])];
+}

package/dist/src/components/SourceFile.d.ts

@@ -0,0 +1,46 @@
+import { ComponentContext, type Children } from "@alloy-js/core";
+import { PythonModuleScope } from "../symbols/index.js";
+export interface PythonSourceFileContext {
+    scope: PythonModuleScope;
+    /** The module name for this file, e.g. 'test' for test.py */
+    module: string;
+}
+export declare const PythonSourceFileContext: ComponentContext<PythonSourceFileContext>;
+export declare function useSourceFile(): PythonSourceFileContext;
+export interface SourceFileProps {
+    /**
+     * The path to the file relative to the source directory.
+     */
+    path: string;
+    /**
+     * Content to add to the file, such as function definitions, class definitions, and variable declarations.
+     */
+    children?: Children;
+    /**
+     * Header comment to add to the file, which will be rendered at the top of the file.
+     */
+    header?: Children;
+    /**
+     * Comment to add to the header, which will be rendered as a comment in the file.
+     */
+    headerComment?: string;
+}
+/**
+ * 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` that contains
+ * all the symbols defined in the file, such as functions, classes, and variables.
+ *
+ * @example
+ * ```tsx
+ * <SourceFile path="test.py">
+ *   <FunctionDeclaration name="test" />
+ * </SourceFile>
+ * ```
+ * renders to
+ * ```py
+ * def test():
+ *   pass
+ * ```
+ */
+export declare function SourceFile(props: SourceFileProps): Children;
+//# sourceMappingURL=SourceFile.d.ts.map

package/dist/src/components/SourceFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SourceFile.d.ts","sourceRoot":"","sources":["../../../src/components/SourceFile.tsx"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAQhB,KAAK,QAAQ,EACd,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAIxD,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,iBAAiB,CAAC;IACzB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,uBAAuB,EAAE,gBAAgB,CAAC,uBAAuB,CAC3B,CAAC;AAEpD,wBAAgB,aAAa,4BAE5B;AAED,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;OAEG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,YA2BhD"}

package/dist/src/components/SourceFile.js

@@ -0,0 +1,75 @@
+import { createComponent as _$createComponent, createIntrinsic as _$createIntrinsic } from "@alloy-js/core/jsx-runtime";
+import { SourceFile as CoreSourceFile, createNamedContext, List, Scope, Show, SourceDirectoryContext, useContext } from "@alloy-js/core";
+import { join } from "pathe";
+import { PythonModuleScope } from "../symbols/index.js";
+import { ImportStatements } from "./ImportStatement.js";
+import { Reference } from "./Reference.js";
+export const PythonSourceFileContext = createNamedContext("@alloy-js/python SourceFile");
+export function useSourceFile() {
+  return useContext(PythonSourceFileContext);
+}
+/**
+ * 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` that contains
+ * all the symbols defined in the file, such as functions, classes, and variables.
+ *
+ * @example
+ * ```tsx
+ * <SourceFile path="test.py">
+ *   <FunctionDeclaration name="test" />
+ * </SourceFile>
+ * ```
+ * renders to
+ * ```py
+ * def test():
+ *   pass
+ * ```
+ */
+export function SourceFile(props) {
+  const directoryContext = useContext(SourceDirectoryContext);
+  const currentDir = directoryContext.path;
+  // Name of the scope is derived from the file path, minus the .py extension, and with slashes replaced by dots
+  const path = join(currentDir, props.path).replace(/\.py$/, "").replace(/\//g, ".");
+  const scope = new PythonModuleScope(path);
+  const sfContext = {
+    scope: scope,
+    module: path
+  };
+  return _$createComponent(CoreSourceFile, {
+    get path() {
+      return props.path;
+    },
+    filetype: "py",
+    reference: Reference,
+    get children() {
+      return [_$createComponent(Show, {
+        get when() {
+          return scope.importedModules.size > 0;
+        },
+        get children() {
+          return [_$createComponent(ImportStatements, {
+            get records() {
+              return scope.importedModules;
+            }
+          }), _$createIntrinsic("hbr", {}), _$createIntrinsic("hbr", {})];
+        }
+      }), _$createComponent(PythonSourceFileContext.Provider, {
+        value: sfContext,
+        get children() {
+          return _$createComponent(Scope, {
+            value: scope,
+            kind: "source-file",
+            get children() {
+              return _$createComponent(List, {
+                doubleHardline: true,
+                get children() {
+                  return props.children;
+                }
+              });
+            }
+          });
+        }
+      })];
+    }
+  });
+}

package/dist/src/components/StatementList.d.ts

@@ -0,0 +1,25 @@
+import { Children } from "@alloy-js/core";
+export interface StatementListProps {
+    children: Children;
+}
+/**
+ * A Python statement list, which is a list of statements that can be rendered
+ * in a Python source file.
+ *
+ * @example
+ * ```tsx
+ * <StatementList>
+ *   <FunctionDeclaration name="test" />
+ *   <VariableDeclaration name="x" value={42} />
+ * </StatementList>
+ * ```
+ * renders to
+ * ```py
+ * def test():
+ *   pass
+ *
+ * x = 42
+ * ```
+ */
+export declare function StatementList(props: StatementListProps): Children;
+//# sourceMappingURL=StatementList.d.ts.map

package/dist/src/components/StatementList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StatementList.d.ts","sourceRoot":"","sources":["../../../src/components/StatementList.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAQ,MAAM,gBAAgB,CAAC;AAEhD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,YAEtD"}

package/dist/src/components/StatementList.js

@@ -0,0 +1,29 @@
+import { createComponent as _$createComponent } from "@alloy-js/core/jsx-runtime";
+import { List } from "@alloy-js/core";
+/**
+ * A Python statement list, which is a list of statements that can be rendered
+ * in a Python source file.
+ *
+ * @example
+ * ```tsx
+ * <StatementList>
+ *   <FunctionDeclaration name="test" />
+ *   <VariableDeclaration name="x" value={42} />
+ * </StatementList>
+ * ```
+ * renders to
+ * ```py
+ * def test():
+ *   pass
+ *
+ * x = 42
+ * ```
+ */
+export function StatementList(props) {
+  return _$createComponent(List, {
+    hardline: true,
+    get children() {
+      return props.children;
+    }
+  });
+}

package/dist/src/components/VariableDeclaration.d.ts

@@ -0,0 +1,62 @@
+import { Children } from "@alloy-js/core";
+import { BaseDeclarationProps } from "./Declaration.jsx";
+export interface VariableDeclarationProps extends BaseDeclarationProps {
+    /**
+     * The initial value of the variable.
+     */
+    initializer?: Children;
+    /**
+     * The type of the variable. Used only for type annotation. Optional.
+     */
+    type?: Children;
+    /**
+     * Indicates if we should omit the None assignment. Optional.
+     */
+    omitNone?: boolean;
+    /**
+     * Indicates if this is a call statement variable. Optional.
+     * This is used to handle cases where the variable is part of a call statement.
+     */
+    callStatementVar?: boolean;
+    /**
+     * Indicates if this variable is an instance variable. Optional.
+     * This is used to handle cases where the variable is part of a class instance.
+     */
+    instanceVariable?: boolean;
+}
+/**
+ * A variable declaration component for Python.
+ *
+ * @example
+ * ```tsx
+ * <VariableDeclaration
+ *   name="myVar"
+ *   type="int"
+ *   initializer={42}  // Initial value
+ * />
+ * <VariableDeclaration
+ *   name="myOtherVar"
+ *   type="str"
+ *   omitNone={true}
+ * />
+ * <VariableDeclaration
+ *   name="myCallStmtVar"
+ *   callStatementVar={true}
+ *   initializer={12}
+ * />
+ * VariableDeclaration
+ *   name=""
+ *   callStatementVar={true}
+ *   initializer={12}
+ * />
+ * ```
+ * renders to
+ * ```py
+ * myVar: int = 42
+ * myOtherVar: str
+ * myCallStmtVar=12
+ * 12
+ * ```
+ */
+export declare function VariableDeclaration(props: VariableDeclarationProps): Children;
+//# sourceMappingURL=VariableDeclaration.d.ts.map

package/dist/src/components/VariableDeclaration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VariableDeclaration.d.ts","sourceRoot":"","sources":["../../../src/components/VariableDeclaration.tsx"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EAYT,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAGzD,MAAM,WAAW,wBAAyB,SAAQ,oBAAoB;IACpE;;OAEG;IACH,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB;;OAEG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,YAqGlE"}