@alloy-js/python 0.3.0-dev.4 → 0.3.0-dev.6

package/src/components/CallSignature.tsx

@@ -14,8 +14,16 @@ import { createPythonSymbol } from "../symbol-creation.js";
 import { PythonOutputSymbol } from "../symbols/index.js";
 import { Atom } from "./Atom.jsx";
 
+export type ParameterMarker = "*" | "/";
+
+function isParameterMarker(
+  param: string | ParameterDescriptor | undefined,
+): param is ParameterMarker {
+  return typeof param === "string" && (param === "*" || param === "/");
+}
+
 export interface CallSignatureParametersProps {
-  readonly parameters?: (ParameterDescriptor | string)[];
+  readonly parameters?: (ParameterDescriptor | ParameterMarker | string)[];
   readonly args?: boolean;
   readonly kwargs?: boolean;
 }
@@ -34,13 +42,11 @@ export interface CallSignatureParametersProps {
  * ```
  */
 export function CallSignatureParameters(props: CallSignatureParametersProps) {
-  const parameters = normalizeAndDeclareParameters(props.parameters ?? []);
-
   const parameterList = computed(() => {
-    const params = [];
-    // Add regular parameters
-    parameters.forEach((param) => {
-      params.push(parameter(param));
+    const params = (props.parameters ?? []).map((p) => {
+      return isParameterMarker(p) ? p : (
+          parameter(normalizeAndDeclareParameter(p))
+        );
     });
 
     // Add *args if specified
@@ -88,40 +94,39 @@ interface DeclaredParameterDescriptor
   TypeSlot?: SymbolSlot;
 }
 
-function normalizeAndDeclareParameters(
-  parameters: (ParameterDescriptor | string)[],
-): DeclaredParameterDescriptor[] {
-  return parameters.map((param) => {
-    if (isParameterDescriptor(param)) {
-      const TypeSlot = createSymbolSlot();
-
-      const symbol = createPythonSymbol(
-        param.name,
-        {
-          refkeys: param.refkey,
-          type: TypeSlot.firstSymbol,
-        },
-        "parameter",
-      );
-
-      return {
-        ...param,
-        symbol,
-        TypeSlot,
-      };
-    } else {
-      const symbol = createPythonSymbol(param, {}, "parameter");
-      return { refkeys: symbol.refkeys, symbol };
-    }
-  });
+function normalizeAndDeclareParameter(
+  param: ParameterDescriptor | string,
+): DeclaredParameterDescriptor {
+  if (isParameterDescriptor(param)) {
+    const TypeSlot = createSymbolSlot();
+
+    const symbol = createPythonSymbol(
+      param.name,
+      {
+        refkeys: param.refkey,
+        type: TypeSlot.firstSymbol,
+      },
+      "parameter",
+    );
+
+    return {
+      ...param,
+      symbol,
+      TypeSlot,
+    };
+  } else {
+    const symbol = createPythonSymbol(param, {}, "parameter");
+    return { symbol };
+  }
 }
 
 export interface CallSignatureProps {
   /**
-   * The parameters to the call signature. Can be an array of strings (for parameters
-   * which don't have a type or a default value) or {@link ParameterDescriptor}s.
+   * The parameters to the call signature. Can be an array of strings (for simple
+   * parameter names), {@link ParameterDescriptor}s, or special markers ("*" for
+   * keyword-only, "/" for positional-only).
    */
-  parameters?: (ParameterDescriptor | string)[];
+  parameters?: (ParameterDescriptor | ParameterMarker | string)[];
 
   /**
    * The type parameters of the call signature, e.g. for a generic function.

package/src/components/FutureStatement.tsx

@@ -0,0 +1,38 @@
+import { type Children } from "@alloy-js/core";
+
+export interface FutureStatementProps {
+  /**
+   * The name of the feature to import from __future__.
+   */
+  feature: string;
+}
+
+/**
+ * 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.
+ *
+ * @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
+ * ```
+ */
+export function FutureStatement(props: FutureStatementProps): Children {
+  return <>from __future__ import {props.feature}</>;
+}

package/src/components/SourceFile.tsx

@@ -1,7 +1,9 @@
 import {
+  childrenArray,
   ComponentContext,
   SourceFile as CoreSourceFile,
   createNamedContext,
+  isComponentCreator,
   List,
   Scope,
   Show,
@@ -12,8 +14,51 @@ import {
 import { join } from "pathe";
 import { PythonModuleScope } from "../symbols/index.js";
 import { ImportStatements } from "./ImportStatement.js";
+import { SimpleCommentBlock } from "./PyDoc.js";
 import { Reference } from "./Reference.js";
 
+// Non top-level definitions
+const NON_DEFINITION_NAMES = new Set([
+  "VariableDeclaration",
+  "MemberExpression",
+  "FunctionCallExpression",
+  "ClassInstantiation",
+  "Reference",
+]);
+
+// Wrapper components that we should look inside to find the actual first child
+const WRAPPER_COMPONENT_NAMES = new Set(["StatementList"]);
+
+/**
+ * Checks if the first child is a top-level definition (function or class).
+ * PEP 8 requires 2 blank lines before top-level function and class definitions,
+ * but not before other statements like variable assignments.
+ *
+ * Returns true only if there are children and the first child is a definition.
+ */
+function firstChildIsDefinition(children: Children | undefined): boolean {
+  if (!children) return false;
+  const arr = childrenArray(() => children);
+  if (arr.length === 0) return false;
+  const first = arr[0];
+
+  // Non-component children (strings, numbers, refkeys, etc.) are not definitions
+  if (!isComponentCreator(first)) {
+    return false;
+  }
+
+  const name = first.component.name;
+  if (NON_DEFINITION_NAMES.has(name)) {
+    return false;
+  }
+  // Look inside wrapper components
+  if (WRAPPER_COMPONENT_NAMES.has(name) && first.props?.children) {
+    return firstChildIsDefinition(first.props.children as Children);
+  }
+  // If we get here, it's likely a definition (FunctionDeclaration, ClassDeclaration, etc.)
+  return true;
+}
+
 export interface PythonSourceFileContext {
   scope: PythonModuleScope;
   /** The module name for this file, e.g. 'test' for test.py */
@@ -37,17 +82,23 @@ export interface SourceFileProps {
    */
   children?: Children;
   /**
-   * Header comment to add to the file, which will be rendered at the top of the file.
+   * Content to render at the very top of the file, before everything else.
+   * Use this for shebang lines, encoding declarations, or license headers.
    */
   header?: Children;
   /**
-   * Comment to add to the header, which will be rendered as a comment in the file.
+   * 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.
    */
   headerComment?: string;
   /**
    * Documentation for this module, which will be rendered as a module-level docstring.
    */
   doc?: Children;
+  /**
+   * __future__ imports to render after the docstring but before regular imports.
+   */
+  futureImports?: Children;
 }
 
 /**
@@ -100,21 +151,90 @@ export function SourceFile(props: SourceFileProps) {
     module: path,
   };
 
+  // Check if there are any children
+  const hasChildren =
+    props.children !== undefined &&
+    childrenArray(() => props.children).length > 0;
+
+  // PEP 8 requires 2 blank lines before top-level function/class definitions
+  const needsExtraSpacing = firstChildIsDefinition(props.children);
+
+  // Check if there's any preamble content (header, doc, imports, etc.)
+  const hasPreamble =
+    props.header !== undefined ||
+    props.headerComment !== undefined ||
+    props.doc !== undefined ||
+    props.futureImports !== undefined;
+
   return (
-    <CoreSourceFile path={props.path} filetype="py" reference={Reference}>
-      <Show when={scope.importedModules.size > 0}>
-        <ImportStatements records={scope.importedModules} />
-        <hbr />
+    <CoreSourceFile
+      path={props.path}
+      filetype="py"
+      reference={Reference}
+      header={props.header}
+    >
+      {/* Extra blank line after header when followed by doc/futureImports/children (not headerComment) */}
+      <Show
+        when={
+          props.header !== undefined &&
+          props.headerComment === undefined &&
+          (props.doc !== undefined ||
+            props.futureImports !== undefined ||
+            hasChildren)
+        }
+      >
         <hbr />
       </Show>
+      <Show when={props.headerComment !== undefined}>
+        <SimpleCommentBlock>{props.headerComment}</SimpleCommentBlock>
+        {/* When followed by doc: just newline (no blank line) */}
+        <Show when={props.doc !== undefined}>
+          <hbr />
+        </Show>
+        {/* When followed by futureImports or children directly (no doc): blank line */}
+        <Show
+          when={
+            props.doc === undefined &&
+            (props.futureImports !== undefined || hasChildren)
+          }
+        >
+          <hbr />
+          <hbr />
+        </Show>
+      </Show>
       <Show when={props.doc !== undefined}>
         {props.doc}
-        <hbr />
+        <Show when={props.futureImports !== undefined || hasChildren}>
+          <hbr />
+        </Show>
+      </Show>
+      <Show when={props.futureImports !== undefined}>
+        {props.futureImports}
+        <Show when={hasChildren}>
+          <hbr />
+          <hbr />
+        </Show>
+      </Show>
+      <Show when={scope.importedModules.size > 0}>
+        <ImportStatements records={scope.importedModules} />
+        <Show when={hasChildren}>
+          <hbr />
+          <hbr />
+        </Show>
+      </Show>
+      {/* Extra blank line before top-level definitions */}
+      <Show
+        when={
+          needsExtraSpacing && (hasPreamble || scope.importedModules.size > 0)
+        }
+      >
         <hbr />
       </Show>
       <PythonSourceFileContext.Provider value={sfContext}>
         <Scope value={scope}>
-          <List doubleHardline>{props.children}</List>
+          <Show when={hasChildren}>
+            <List doubleHardline>{props.children}</List>
+          </Show>
         </Scope>
       </PythonSourceFileContext.Provider>
     </CoreSourceFile>

package/src/components/index.ts

@@ -12,6 +12,7 @@ export * from "./EnumMember.js";
 export type { CommonFunctionProps } from "./FunctionBase.js";
 export * from "./FunctionCallExpression.js";
 export * from "./FunctionDeclaration.js";
+export * from "./FutureStatement.js";
 export * from "./ImportStatement.js";
 export * from "./LexicalScope.js";
 export * from "./MemberExpression.js";

package/temp/api.json

@@ -831,6 +831,15 @@
                   "text": "ParameterDescriptor",
                   "canonicalReference": "@alloy-js/python!ParameterDescriptor:interface"
                 },
+                {
+                  "kind": "Content",
+                  "text": " | "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ParameterMarker",
+                  "canonicalReference": "@alloy-js/python!ParameterMarker:type"
+                },
                 {
                   "kind": "Content",
                   "text": " | string)[]"
@@ -846,7 +855,7 @@
               "name": "parameters",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 4
+                "endIndex": 6
               }
             }
           ],
@@ -924,7 +933,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/python!CallSignatureProps#parameters:member",
-              "docComment": "/**\n * The parameters to the call signature. Can be an array of strings (for parameters\n * which don't have a type or a default value) or {@link ParameterDescriptor}s.\n */\n",
+              "docComment": "/**\n * The parameters to the call signature. Can be an array of strings (for simple\n * parameter names), {@link ParameterDescriptor}s, or special markers (\"*\" for\n * keyword-only, \"/\" for positional-only).\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -939,6 +948,15 @@
                   "text": "ParameterDescriptor",
                   "canonicalReference": "@alloy-js/python!ParameterDescriptor:interface"
                 },
+                {
+                  "kind": "Content",
+                  "text": " | "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ParameterMarker",
+                  "canonicalReference": "@alloy-js/python!ParameterMarker:type"
+                },
                 {
                   "kind": "Content",
                   "text": " | string)[]"
@@ -954,7 +972,7 @@
               "name": "parameters",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 4
+                "endIndex": 6
               }
             },
             {
@@ -4332,6 +4350,98 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "Function",
+          "canonicalReference": "@alloy-js/python!FutureStatement:function(1)",
+          "docComment": "/**\n * A future statement that imports features from __future__.\n *\n * Future statements are directives to the compiler that a particular module\n * should be compiled using syntax or semantics from a future Python release.\n * They must appear near the top of the module, after the module docstring (if any).\n *\n * Use this in the `futureImports` prop of SourceFile to ensure proper placement.\n *\n * @example\n * ```tsx\n * <SourceFile path=\"models.py\" futureImports={<FutureStatement feature=\"annotations\" />}>\n *   <ClassDeclaration name=\"User\">\n *     <PropertyDeclaration name=\"manager\" type=\"User\" />\n *   </ClassDeclaration>\n * </SourceFile>\n * ```\n *\n * renders to\n * ```py\n * from __future__ import annotations\n *\n *\n * class User:\n *     manager: User\n * ```\n *\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function FutureStatement(props: "
+            },
+            {
+              "kind": "Reference",
+              "text": "FutureStatementProps",
+              "canonicalReference": "@alloy-js/python!FutureStatementProps:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Reference",
+              "text": "Children",
+              "canonicalReference": "@alloy-js/core!Children:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/components/FutureStatement.tsx",
+          "returnTypeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 4
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "props",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            }
+          ],
+          "name": "FutureStatement"
+        },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@alloy-js/python!FutureStatementProps:interface",
+          "docComment": "",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface FutureStatementProps "
+            }
+          ],
+          "fileUrlPath": "src/components/FutureStatement.tsx",
+          "releaseTag": "Public",
+          "name": "FutureStatementProps",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@alloy-js/python!FutureStatementProps#feature:member",
+              "docComment": "/**\n * The name of the feature to import from __future__.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "feature: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "feature",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/python!GeneratorDoc:function(1)",
@@ -7384,6 +7494,32 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@alloy-js/python!ParameterMarker:type",
+          "docComment": "",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type ParameterMarker = "
+            },
+            {
+              "kind": "Content",
+              "text": "\"*\" | \"/\""
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/components/CallSignature.tsx",
+          "releaseTag": "Public",
+          "name": "ParameterMarker",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/python!PropertyDeclaration:function(1)",
@@ -9942,10 +10078,38 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@alloy-js/python!SourceFileProps#futureImports:member",
+              "docComment": "/**\n * __future__ imports to render after the docstring but before regular imports.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "futureImports?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Children",
+                  "canonicalReference": "@alloy-js/core!Children:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "futureImports",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/python!SourceFileProps#header:member",
-              "docComment": "/**\n * Header comment to add to the file, which will be rendered at the top of the file.\n */\n",
+              "docComment": "/**\n * Content to render at the very top of the file, before everything else.\n * Use this for shebang lines, encoding declarations, or license headers.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -9973,7 +10137,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/python!SourceFileProps#headerComment:member",
-              "docComment": "/**\n * Comment to add to the header, which will be rendered as a comment in the file.\n */\n",
+              "docComment": "/**\n * Comment to add at the top of the file, rendered as a Python comment block.\n * This is a convenience prop for adding copyright notices or other comments.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",