@alloy-js/python 0.0.1

package/dist/src/components/MemberExpression.js

@@ -0,0 +1,308 @@
+import { createIntrinsic as _$createIntrinsic, memo as _$memo, createComponent as _$createComponent } from "@alloy-js/core/jsx-runtime";
+import { childrenArray, code, computed, For, isComponentCreator, reactive, ref, Show, takeSymbols, useBinder } from "@alloy-js/core";
+const MEMBER_ACCESS_TYPES = {
+  ATTRIBUTE: "attribute",
+  SUBSCRIPTION: "subscription",
+  CALL: "call"
+};
+/**
+ * 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.
+ *
+ * @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
+ * ```
+ */
+export function MemberExpression(props) {
+  const children = childrenArray(() => props.children);
+  const parts = childrenToPartDescriptors(children);
+  // any symbols emitted from the children won't be relevant to
+  // parent scopes. TODO: emit the proper symbol if we know it?
+  takeSymbols();
+  if (parts.length === 0) {
+    return [];
+  }
+  return computed(() => {
+    return formatChain(parts);
+  });
+}
+
+/**
+ * Build part descriptors from the children of a MemberExpression.
+ */
+function childrenToPartDescriptors(children) {
+  const parts = [];
+  for (const child of children) {
+    if (!isComponentCreator(child, MemberExpression.Part)) {
+      // we ignore non-parts
+      continue;
+    }
+    parts.push(createPartDescriptorFromProps(child.props, child === children[0]));
+  }
+  return parts;
+}
+const exclusiveParts = ["args", "refkey", "symbol", "id", "key", "keys", "slice"];
+/**
+ * Creates a reactive part descriptor from the given part props.
+ *
+ * @param partProps The props for the part.
+ * @param first Whether this is the first part in the expression. Refkeys are
+ * handled specially for the first part.
+ */
+function createPartDescriptorFromProps(partProps, first) {
+  const foundProps = exclusiveParts.filter(key => {
+    return key in partProps;
+  });
+  if (foundProps.length > 1) {
+    throw new Error(`Only one of ${foundProps.join(", ")} can be used for a MemberExpression part at a time`);
+  }
+
+  // Validate slice syntax
+  if (partProps.slice) {
+    const {
+      start,
+      stop,
+      step
+    } = partProps.slice;
+    if (!start && !stop && !step) {
+      throw new Error("MemberExpression.Part: slice object cannot be empty");
+    }
+  }
+
+  // Validate keys array
+  if (partProps.keys?.length === 0) {
+    throw new Error("MemberExpression.Part: keys array cannot be empty");
+  }
+  const symbolSource = computed(() => {
+    if (partProps.refkey) {
+      return getSymbolForRefkey(partProps.refkey).value;
+    } else if (partProps.symbol) {
+      return partProps.symbol;
+    } else {
+      return undefined;
+    }
+  });
+
+  // Return different descriptor types based on what props are provided
+  let part;
+  if (partProps.args !== undefined) {
+    // CallDescriptor
+    part = {
+      type: computed(() => {
+        return "call";
+      }),
+      args: ref(partProps.args === true ? [] : partProps.args)
+    };
+  } else if (partProps.key !== undefined || partProps.keys !== undefined || partProps.slice !== undefined) {
+    // SubscriptionDescriptor
+    part = {
+      type: computed(() => {
+        return "subscription";
+      }),
+      expression: computed(() => {
+        return getSubscriptionValue(partProps);
+      }),
+      quoted: computed(() => {
+        return partProps.key !== undefined && typeof partProps.key === "string";
+      })
+    };
+  } else {
+    // IdentifierDescriptor
+    part = {
+      type: computed(() => {
+        return "attribute";
+      }),
+      name: computed(() => {
+        if (first && partProps.refkey) {
+          return partProps.refkey;
+        } else if (partProps.id !== undefined) {
+          if (!isValidIdentifier(partProps.id)) {
+            throw new Error(`Invalid identifier: ${partProps.id}`);
+          }
+          return partProps.id;
+        } else if (symbolSource.value) {
+          return symbolSource.value.name;
+        } else {
+          return "<unresolved symbol>";
+        }
+      })
+    };
+  }
+  return reactive(part);
+}
+
+/**
+ * Convert a refkey to a symbol ref using the current binder.
+ */
+function getSymbolForRefkey(refkey) {
+  const binder = useBinder();
+  return binder.getSymbolForRefkey(refkey);
+}
+
+/**
+ * Format a chain of parts into a MemberExpression.
+ */
+function formatChain(parts) {
+  return computed(() => {
+    const expression = [];
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      if (i === 0) {
+        if (!isAttributeDescriptor(part)) {
+          throw new Error("The first part of a MemberExpression must be an id or refkey");
+        }
+        expression.push(part.name);
+      } else {
+        if (isCallDescriptor(part)) {
+          expression.push(formatCallOutput(part));
+        } else if (isAttributeDescriptor(part)) {
+          expression.push(formatAttributeOutput(part));
+        } else if (isSubscriptionDescriptor(part)) {
+          expression.push(formatSubscriptionOutput(part));
+        }
+      }
+    }
+    return expression;
+  });
+}
+
+/**
+ * Format a part of a member expression that is an array access.
+ * This is used for parts like `foo[0]` or `foo["bar"]`.
+ */
+function formatSubscriptionOutput(part) {
+  return _$createIntrinsic("group", {
+    get children() {
+      return ["", "[", _$createIntrinsic("indent", {
+        get children() {
+          return [_$createIntrinsic("sbr", {}), _$memo(() => part.quoted && '"'), _$memo(() => part.expression), _$memo(() => part.quoted && '"')];
+        }
+      }), _$createIntrinsic("sbr", {}), "]"];
+    }
+  });
+}
+function formatAttributeOutput(part) {
+  return _$createIntrinsic("group", {
+    get children() {
+      return _$createIntrinsic("indent", {
+        get children() {
+          return [_$createIntrinsic("ifBreak", {
+            children: " \\"
+          }), _$createIntrinsic("sbr", {}), ".", _$memo(() => part.name)];
+        }
+      });
+    }
+  });
+}
+function formatCallOutput(part) {
+  const args = computed(() => {
+    return typeof part.args === "boolean" ? [] : part.args ?? [];
+  });
+  return _$createIntrinsic("group", {
+    get children() {
+      return ["", "(", _$createComponent(Show, {
+        get when() {
+          return args.value.length <= 1;
+        },
+        get children() {
+          return args.value[0];
+        }
+      }), _$createComponent(Show, {
+        get when() {
+          return args.value.length > 1;
+        },
+        get children() {
+          return [_$createIntrinsic("indent", {
+            get children() {
+              return [_$createIntrinsic("sbr", {}), _$createComponent(For, {
+                each: args,
+                comma: true,
+                line: true,
+                children: arg => arg
+              })];
+            }
+          }), _$createIntrinsic("sbr", {})];
+        }
+      }), ")"];
+    }
+  });
+}
+/**
+ * A part of a member expression. Each part can provide one of the following
+ * props:
+ *
+ * * **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
+ */
+MemberExpression.Part = function (props) {
+  /**
+   * This component does nothing except hold props which are retrieved by
+   * the `MemberExpression` component.
+   */
+};
+function isValidIdentifier(id) {
+  if (typeof id === "string" && id.includes('"')) {
+    return false;
+  }
+  return true;
+}
+function isCallDescriptor(part) {
+  return "type" in part && part.type === MEMBER_ACCESS_TYPES.CALL;
+}
+function isAttributeDescriptor(part) {
+  return "type" in part && part.type === MEMBER_ACCESS_TYPES.ATTRIBUTE;
+}
+function isSubscriptionDescriptor(part) {
+  return "type" in part && part.type === MEMBER_ACCESS_TYPES.SUBSCRIPTION;
+}
+function getNameForRefkey(refkey) {
+  const parsedValue = getSymbolForRefkey(refkey).value;
+  return parsedValue !== undefined ? parsedValue.name : refkey;
+}
+function getSubscriptionValue(partProps) {
+  // Handle tuple keys: obj[a, b] → (a, b)
+  if (partProps.keys?.length) {
+    const parsedKeys = partProps.keys.map(key => getNameForRefkey(key));
+    return code`${parsedKeys.join(", ")}`;
+  }
+
+  // Handle slice: obj[start:stop:step]
+  if (partProps.slice && Object.keys(partProps.slice).length > 0) {
+    const {
+      start,
+      stop,
+      step
+    } = partProps.slice;
+    const parts = [start ? getNameForRefkey(start) : "", ":", stop ? getNameForRefkey(stop) : ""];
+    if (step) {
+      parts.push(":", getNameForRefkey(step));
+    }
+    return code`${parts.join("")}`;
+  }
+
+  // Handle single key: obj[key]
+  return getNameForRefkey(partProps.key);
+}

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

@@ -0,0 +1,23 @@
+import { Children } from "@alloy-js/core/jsx-runtime";
+export interface NoNamePolicyProps {
+    children: Children;
+}
+/**
+ * A wrapper component that disables name policy transformation for its children.
+ *
+ * This is useful for components that need to preserve exact names without applying
+ * naming conventions, such as Python dunder methods like `__init__`, `__str__`, etc.
+ *
+ * @example
+ * ```tsx
+ * <NoNamePolicy>
+ *   <FunctionDeclaration name="__init__" instanceFunction>
+ *     // Function content
+ *   </FunctionDeclaration>
+ * </NoNamePolicy>
+ * ```
+ *
+ * This ensures `__init__` stays as `__init__` without name policy transformation.
+ */
+export declare function NoNamePolicy(props: NoNamePolicyProps): Children;
+//# sourceMappingURL=NoNamePolicy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NoNamePolicy.d.ts","sourceRoot":"","sources":["../../../src/components/NoNamePolicy.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,YAMpD"}

package/dist/src/components/NoNamePolicy.js

@@ -0,0 +1,27 @@
+import { memo as _$memo, createComponent as _$createComponent } from "@alloy-js/core/jsx-runtime";
+import { NamePolicyContext } from "@alloy-js/core";
+/**
+ * A wrapper component that disables name policy transformation for its children.
+ *
+ * This is useful for components that need to preserve exact names without applying
+ * naming conventions, such as Python dunder methods like `__init__`, `__str__`, etc.
+ *
+ * @example
+ * ```tsx
+ * <NoNamePolicy>
+ *   <FunctionDeclaration name="__init__" instanceFunction>
+ *     // Function content
+ *   </FunctionDeclaration>
+ * </NoNamePolicy>
+ * ```
+ *
+ * This ensures `__init__` stays as `__init__` without name policy transformation.
+ */
+export function NoNamePolicy(props) {
+  return _$createComponent(NamePolicyContext.Provider, {
+    value: undefined,
+    get children() {
+      return props.children;
+    }
+  });
+}

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

@@ -0,0 +1,90 @@
+import { Children } from "@alloy-js/core/jsx-runtime";
+import { ParameterDescriptor } from "../parameter-descriptor.js";
+export interface GoogleStyleDocParamProps {
+    name: Children;
+    type?: Children;
+    children?: Children;
+    optional?: boolean;
+    defaultValue?: Children;
+}
+/**
+ * Create a GoogleStyleDoc parameter.
+ */
+export declare function GoogleStyleDocParam(props: GoogleStyleDocParamProps): Children;
+export interface GoogleStyleDocParamsProps {
+    parameters: ParameterDescriptor[] | string[];
+}
+/**
+ * A component that creates a GoogleStyleDoc block for parameters.
+ */
+export declare function GoogleStyleDocParams(props: GoogleStyleDocParamsProps): Children;
+export interface GoogleStyleDocReturnProps {
+    message: string;
+}
+/**
+ * A component that creates a GoogleStyleDoc block for parameters.
+ */
+export declare function GoogleStyleDocReturn(props: GoogleStyleDocReturnProps): Children;
+export interface GoogleStyleDocRaisesProps {
+    message: string;
+}
+/**
+ * A component that creates a GoogleStyleDoc block for parameters.
+ */
+export declare function GoogleStyleDocRaises(props: GoogleStyleDocRaisesProps): Children;
+export interface GoogleStyleFunctionDocProps extends Omit<FunctionDocProps, "style"> {
+}
+/**
+ * A component that creates a GoogleStyleFunctionDoc block for parameters.
+ */
+export declare function GoogleStyleFunctionDoc(props: GoogleStyleFunctionDocProps): Children;
+export interface FunctionDocProps {
+    description: Children[];
+    parameters?: ParameterDescriptor[] | string[];
+    returns?: string;
+    raises?: string[];
+    style?: "google";
+}
+/**
+ * A component that creates a FunctionDoc block for parameters.
+ */
+export declare function FunctionDoc(props: FunctionDocProps): Children;
+export interface ClassDocProps {
+    description: Children[];
+    parameters?: ParameterDescriptor[] | string[];
+    style?: "google";
+}
+/**
+ * A component that creates a ClassDoc block for parameters.
+ */
+export declare function ClassDoc(props: ClassDocProps): Children;
+export interface GoogleStyleClassDocProps extends Omit<ClassDocProps, "style"> {
+}
+/**
+ * A component that creates a GoogleStyleClassDoc block for parameters.
+ */
+export declare function GoogleStyleClassDoc(props: GoogleStyleClassDocProps): Children;
+export interface PyDocExampleProps {
+    children: Children;
+}
+/**
+ * Create a PyDoc example, which is prepended by \>\>.
+ */
+export declare function PyDocExample(props: PyDocExampleProps): Children;
+export interface PyDocProps {
+    children: Children;
+}
+/**
+ * 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 declare function PyDoc(props: PyDocProps): Children;
+export interface SimpleCommentBlockProps {
+    children: Children;
+}
+export declare function SimpleCommentBlock(props: SimpleCommentBlockProps): Children;
+export interface SimpleInlineCommentProps {
+    children: Children;
+}
+export declare function SimpleInlineComment(props: SimpleInlineCommentProps): Children;
+//# sourceMappingURL=PyDoc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PyDoc.d.ts","sourceRoot":"","sources":["../../../src/components/PyDoc.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAmDjE,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,QAAQ,CAAC;CACzB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,YAWlE;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,mBAAmB,EAAE,GAAG,MAAM,EAAE,CAAC;CAC9C;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,YAoBpE;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,YAOpE;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,YAOpE;AAED,MAAM,WAAW,2BACf,SAAQ,IAAI,CAAC,gBAAgB,EAAE,OAAO,CAAC;CAAG;AAE5C;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,2BAA2B,YAqBxE;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,QAAQ,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,mBAAmB,EAAE,GAAG,MAAM,EAAE,CAAC;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,YAYlD;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,QAAQ,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,mBAAmB,EAAE,GAAG,MAAM,EAAE,CAAC;IAC9C,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,YAU5C;AAED,MAAM,WAAW,wBACf,SAAQ,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC;CAAG;AAEzC;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,YAalE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,YA8BpD;AAYD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,YAYtC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,YAShE;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,YAMlE"}