@alloy-js/python 0.0.1

package/src/components/index.ts

@@ -0,0 +1,18 @@
+export * from "./Atom.js";
+export * from "./CallSignature.js";
+export * from "./ClassDeclaration.js";
+export * from "./ClassInstantiation.js";
+export * from "./Declaration.js";
+export * from "./EnumDeclaration.js";
+export * from "./EnumMember.js";
+export * from "./FunctionCallExpression.js";
+export * from "./FunctionDeclaration.js";
+export * from "./ImportStatement.js";
+export * from "./MemberExpression.js";
+export * from "./NoNamePolicy.js";
+export * from "./PyDoc.js";
+export * from "./PythonBlock.js";
+export * from "./Reference.js";
+export * from "./SourceFile.js";
+export * from "./StatementList.js";
+export * from "./VariableDeclaration.js";

package/src/create-module.ts

@@ -0,0 +1,102 @@
+import {
+  type Binder,
+  getSymbolCreatorSymbol,
+  type Refkey,
+  refkey,
+  SymbolCreator,
+} from "@alloy-js/core";
+import { createPythonSymbol } from "./symbol-creation.js";
+import { PythonModuleScope } from "./symbols/index.js";
+
+export interface ModuleDescriptor {
+  [path: string]: string[];
+}
+
+export interface CreateModuleProps<T extends ModuleDescriptor> {
+  name: string;
+  descriptor: T;
+}
+
+export type NamedMap<TDescriptor extends readonly string[]> = {
+  [S in TDescriptor[number]]: Refkey;
+};
+
+export type ModuleRefkeys<PD extends Record<string, string[]>> = {
+  [P in keyof PD]: NamedMap<PD[P]>;
+};
+
+function createSymbols(
+  binder: Binder,
+  props: CreateModuleProps<ModuleDescriptor>,
+  refkeys: Record<string, any>,
+) {
+  // Create a module scope for each path in the descriptor
+  for (const [path, symbols] of Object.entries(props.descriptor)) {
+    // If the path is ".", we use the module name directly
+    // Otherwise, we append the path to the module name
+    const fullModuleScopeName = props.name + (path === "." ? "" : `.${path}`);
+    const keys = refkeys[path];
+    const moduleScope = new PythonModuleScope(fullModuleScopeName, {
+      parent: undefined,
+      binder: binder,
+    });
+
+    // Create a symbol for each exported name
+    for (const exportedName of symbols ?? []) {
+      const key = keys[exportedName];
+
+      const _ = createPythonSymbol(
+        exportedName,
+        {
+          binder: binder,
+          scope: moduleScope,
+          refkeys: key,
+          module: moduleScope.name,
+        },
+        undefined,
+        false,
+      );
+    }
+  }
+}
+
+// A module is a map of refkeys for each path in the descriptor.
+// Each path maps to a set of named refkeys for the exported symbols.
+// When one of the symbols is used, the relevant import will be added
+// to the source file, and the symbol will be available in the output.
+//
+// Most of the use cases will be for templates and not for use in JSX,
+// so the symbols will not be normally used directly in the code, but
+// there may be cases where you want to use them directly.
+//
+// Example:
+// ```ts
+// const requestsLib = createModule({
+//   name: "requests",
+//   descriptor: {
+//     ".": ["get", "post"],
+//   },
+// });
+// ```
+//
+// For this scenario, if requestsLib["."].get is used, it will add
+// the import `from requests import get` and would render the symbol
+// as `get` in the output.
+export function createModule<const T extends ModuleDescriptor>(
+  props: CreateModuleProps<T>,
+): ModuleRefkeys<T> & SymbolCreator {
+  const refkeys: any = {
+    [getSymbolCreatorSymbol()](binder: Binder) {
+      createSymbols(binder, props, refkeys);
+    },
+  };
+
+  for (const [path, symbols] of Object.entries(props.descriptor)) {
+    const keys: Record<string, Refkey> = (refkeys[path] = {});
+    for (const named of symbols ?? []) {
+      keys[named] = refkey(props.descriptor, path, named);
+    }
+  }
+
+  return refkeys;
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./builtins/python.js";
+export * from "./components/index.js";
+export * from "./create-module.js";
+export * from "./name-policy.js";
+export * from "./parameter-descriptor.js";
+export * from "./symbols/index.js";
+export * from "./utils.js";

package/src/name-policy.ts

@@ -0,0 +1,101 @@
+import { createNamePolicy, NamePolicy, useNamePolicy } from "@alloy-js/core";
+import { constantCase, pascalCase, snakeCase } from "change-case";
+
+export type PythonElements =
+  | "class" // Classes
+  | "class-member" // Class members (attributes, methods)
+  | "function" // Functions
+  | "variable" // Variables
+  | "object-member" // Object members (attributes, methods)
+  | "constant"
+  | "parameter"
+  | "method"
+  | "module"
+  | "enum" // Enums
+  | "enum-member"; // Enum members
+
+// Reserved words
+const GLOBAL_RESERVED_WORDS = new Set([
+  "False",
+  "None",
+  "True",
+  "and",
+  "as",
+  "assert",
+  "async",
+  "await",
+  "break",
+  "class",
+  "continue",
+  "def",
+  "del",
+  "elif",
+  "else",
+  "except",
+  "finally",
+  "for",
+  "from",
+  "global",
+  "if",
+  "import",
+  "in",
+  "is",
+  "lambda",
+  "nonlocal",
+  "not",
+  "or",
+  "pass",
+  "raise",
+  "return",
+  "try",
+  "while",
+  "with",
+  "and",
+  "yield",
+]);
+
+/**
+ * Ensures a valid Python identifier for the given element kind.
+ * @param name - The name to validate.
+ * @param element - The Python element kind.
+ * @returns A Python-safe name.
+ */
+function ensureNonReservedName(name: string): string {
+  const suffix = "_";
+
+  // Global reserved words always need handling
+  if (GLOBAL_RESERVED_WORDS.has(name)) {
+    return `${name}${suffix}`;
+  }
+
+  return name;
+}
+
+export function createPythonNamePolicy(): NamePolicy<PythonElements> {
+  return createNamePolicy((name, element) => {
+    let transformedName: string;
+
+    switch (element) {
+      case "class":
+      case "enum":
+        transformedName = pascalCase(name);
+        break;
+      case "constant":
+      case "enum-member":
+        transformedName = constantCase(name);
+        break;
+      case "module":
+        transformedName = snakeCase(name).toLowerCase();
+        break;
+      default:
+        transformedName = snakeCase(name);
+        break;
+    }
+
+    return ensureNonReservedName(transformedName);
+  });
+}
+
+export function usePythonNamePolicy(): NamePolicy<PythonElements> {
+  return useNamePolicy();
+}

package/src/parameter-descriptor.ts

@@ -0,0 +1,36 @@
+import type { Children, Refkey } from "@alloy-js/core";
+
+/**
+ * Information for a Python function parameter.
+ */
+export interface ParameterDescriptor {
+  /**
+   * The name of the parameter.
+   */
+  readonly name: string;
+
+  /**
+   * The type of the parameter.
+   */
+  readonly type?: Children;
+
+  /**
+   * The refkey for this parameter.
+   */
+  readonly refkey?: Refkey | Refkey[];
+
+  /**
+   * Whether the parameter is optional.
+   */
+  readonly optional?: boolean;
+
+  /**
+   * Documentation for the parameter.
+   */
+  readonly doc?: Children;
+
+  /**
+   * The default value of the parameter.
+   */
+  readonly default?: Children;
+}

package/src/symbol-creation.ts

@@ -0,0 +1,36 @@
+import { refkey, useContext } from "@alloy-js/core";
+import { PythonSourceFileContext } from "./components/SourceFile.js";
+import { PythonElements, usePythonNamePolicy } from "./name-policy.js";
+import {
+  CreatePythonSymbolOptions,
+  PythonOutputSymbol,
+} from "./symbols/index.js";
+
+export function createPythonSymbol(
+  name: string,
+  options: CreatePythonSymbolOptions,
+  kind?: PythonElements,
+  createRefkeyIfNeeded = false,
+): PythonOutputSymbol {
+  let processedName = name;
+  const sfContext = useContext(PythonSourceFileContext);
+  // Only apply the name policy if a kind is provided and name policy context is available
+  if (kind) {
+    const namePolicy = usePythonNamePolicy();
+    if (namePolicy) {
+      processedName = namePolicy.getName(name, kind);
+    }
+  }
+
+  return new PythonOutputSymbol(processedName, {
+    binder: options.binder,
+    aliasTarget: options.aliasTarget,
+    scope: options.scope,
+    refkeys:
+      options.refkeys ??
+      (createRefkeyIfNeeded ? refkey(processedName) : undefined),
+    flags: options.flags,
+    metadata: options.metadata,
+    module: sfContext?.module,
+  });
+}

package/src/symbols/custom-output-scope.ts

@@ -0,0 +1,35 @@
+import { OutputScope, OutputScopeOptions, SymbolTable } from "@alloy-js/core";
+
+// This is named as CustomOutputScope and not PythonOutputScope to avoid confusion with the one defined in scopes.ts
+// We are creating a custom output scope so we can add out custom name conflict resolution logic.
+export class CustomOutputScope extends OutputScope {
+  #symbols: SymbolTable;
+  /**
+   * The symbols defined within this scope.
+   */
+  get symbols() {
+    return this.#symbols;
+  }
+
+  constructor(name: string, options: OutputScopeOptions = {}) {
+    super(name, options);
+    this.#symbols = new SymbolTable(this, {
+      nameConflictResolver: (_, symbols) => {
+        for (let i = 1; i < symbols.length; i++) {
+          // Rename all but the first symbol to have a suffix of _2, _3, plus the scope name if available.
+          const symbol = symbols[i] as unknown as {
+            originalName: string;
+            name: string;
+            module?: string;
+          };
+          symbol.name =
+            symbol.originalName +
+            "_" +
+            (i + 1) +
+            "_" +
+            (symbols[i].aliasTarget?.scope?.name ?? symbol.module ?? "");
+        }
+      },
+    });
+  }
+}

package/src/symbols/index.ts

@@ -0,0 +1,6 @@
+export * from "./custom-output-scope.js";
+export * from "./python-member-scope.js";
+export * from "./python-module-scope.js";
+export * from "./python-output-symbol.js";
+export * from "./reference.js";
+export * from "./scopes.js";

package/src/symbols/python-member-scope.ts

@@ -0,0 +1,12 @@
+import { CustomOutputScope } from "./custom-output-scope.js";
+import { PythonOutputSymbol } from "./python-output-symbol.js";
+
+export class PythonMemberScope extends CustomOutputScope {
+  get kind() {
+    return "member" as const;
+  }
+
+  get owner() {
+    return super.owner as PythonOutputSymbol;
+  }
+}

package/src/symbols/python-module-scope.ts

@@ -0,0 +1,89 @@
+import { reactive, shallowReactive } from "@alloy-js/core";
+import { createPythonSymbol } from "../symbol-creation.js";
+import { CustomOutputScope } from "./custom-output-scope.js";
+import { PythonOutputSymbol } from "./python-output-symbol.js";
+
+export class ImportedSymbol {
+  local: PythonOutputSymbol;
+  target: PythonOutputSymbol;
+
+  constructor(target: PythonOutputSymbol, local: PythonOutputSymbol) {
+    this.target = target;
+    this.local = local;
+  }
+
+  static from(target: PythonOutputSymbol, local: PythonOutputSymbol) {
+    return new ImportedSymbol(target, local);
+  }
+}
+
+export interface ImportRecordProps {
+  symbols: Set<ImportedSymbol>;
+}
+
+export type ImportRecords = Map<PythonModuleScope, ImportRecordProps>;
+
+export const ImportRecords = Map as {
+  new (): ImportRecords;
+  new (
+    entries?:
+      | readonly (readonly [PythonModuleScope, ImportRecordProps])[]
+      | null,
+  ): ImportRecords;
+  prototype: Map<PythonModuleScope, ImportRecordProps>;
+};
+
+export class PythonModuleScope extends CustomOutputScope {
+  get kind() {
+    return "module" as const;
+  }
+
+  #importedSymbols: Map<PythonOutputSymbol, PythonOutputSymbol> =
+    shallowReactive(new Map());
+  get importedSymbols() {
+    return this.#importedSymbols;
+  }
+
+  #importedModules: ImportRecords = reactive(new Map());
+  get importedModules() {
+    return this.#importedModules;
+  }
+
+  addImport(targetSymbol: PythonOutputSymbol, targetModule: PythonModuleScope) {
+    const existing = this.importedSymbols.get(targetSymbol);
+    if (existing) {
+      return existing;
+    }
+
+    if (targetModule.kind !== "module") {
+      throw new Error("Cannot import symbol that isn't in module scope");
+    }
+
+    if (!this.importedModules.has(targetModule)) {
+      this.importedModules.set(targetModule, {
+        symbols: new Set<ImportedSymbol>(),
+      });
+    }
+
+    const localSymbol = createPythonSymbol(
+      targetSymbol.name,
+      {
+        binder: this.binder,
+        scope: this,
+        aliasTarget: targetSymbol,
+      },
+      undefined,
+      false,
+    );
+
+    targetSymbol.copyTo(localSymbol);
+
+    this.importedSymbols.set(targetSymbol, localSymbol);
+    this.importedModules.get(targetModule)!.symbols?.add({
+      local: localSymbol,
+      target: targetSymbol,
+    });
+
+    return localSymbol;
+  }
+}

package/src/symbols/python-output-symbol.ts

@@ -0,0 +1,36 @@
+import { OutputSymbol, OutputSymbolOptions } from "@alloy-js/core";
+import { PythonMemberScope } from "./python-member-scope.js";
+
+export interface CreatePythonSymbolOptions extends OutputSymbolOptions {
+  module?: string;
+}
+
+export interface CreatePythonSymbolFunctionOptions
+  extends CreatePythonSymbolOptions {
+  name: string;
+}
+
+/**
+ * Represents an 'exported' symbol from a .py file. Class, enum, interface etc.
+ */
+export class PythonOutputSymbol extends OutputSymbol {
+  constructor(name: string, options: CreatePythonSymbolOptions) {
+    super(name, options);
+    this.#module = options.module ?? undefined;
+  }
+
+  // The module in which the symbol is defined
+  #module?: string;
+
+  get module() {
+    return this.#module;
+  }
+
+  set module(value: string | undefined) {
+    this.#module = value;
+  }
+
+  get instanceMemberScope() {
+    return super.instanceMemberScope as PythonMemberScope | undefined;
+  }
+}

package/src/symbols/reference.ts

@@ -0,0 +1,99 @@
+import {
+  memo,
+  OutputSymbolFlags,
+  Refkey,
+  resolve,
+  untrack,
+  useContext,
+  useMemberScope,
+} from "@alloy-js/core";
+import { PythonSourceFileContext } from "../components/SourceFile.jsx";
+import {
+  PythonMemberScope,
+  PythonModuleScope,
+  PythonOutputScope,
+  PythonOutputSymbol,
+} from "./index.js";
+
+export function ref(
+  refkey: Refkey,
+): () => [string, PythonOutputSymbol | undefined] {
+  const sourceFile = useContext(PythonSourceFileContext);
+  const resolveResult = resolve<PythonOutputScope, PythonOutputSymbol>(
+    refkey as Refkey,
+  );
+  const currentScope = useMemberScope();
+
+  return memo(() => {
+    if (resolveResult.value === undefined) {
+      return ["<Unresolved Symbol>", undefined];
+    }
+
+    const { targetDeclaration, pathDown, memberPath } = resolveResult.value;
+
+    // if we resolved a instance member, check if we should be able to access
+    // it.
+    if (targetDeclaration.flags & OutputSymbolFlags.InstanceMember) {
+      if (currentScope?.instanceMembers !== targetDeclaration.scope) {
+        throw new Error(
+          "Cannot resolve member symbols from a different member scope",
+        );
+      }
+    }
+
+    // Where the target declaration is relative to the referencing scope.
+    // * module: target symbol is in a different module
+    // * local: target symbol is within the current module
+    const targetLocation = pathDown[0]?.kind ?? "local";
+    let localSymbol: PythonOutputSymbol | undefined;
+
+    if (targetLocation === "module") {
+      // Handling of targets in other modules, either created with createModule()
+      // or from other files.
+      const symbolPath = [
+        ...(pathDown.slice(1) as PythonMemberScope[]).map((s) => s.owner),
+        targetDeclaration,
+      ];
+
+      const importSymbol = symbolPath[0];
+
+      localSymbol = untrack(() =>
+        sourceFile!.scope.addImport(
+          importSymbol,
+          pathDown[0] as PythonModuleScope,
+        ),
+      );
+    }
+
+    if (memberPath && memberPath.length > 0) {
+      if (localSymbol) {
+        memberPath[0] = localSymbol;
+      }
+
+      return [buildMemberExpression(memberPath), memberPath.at(-1)];
+    } else {
+      return [
+        buildMemberExpression([localSymbol ?? targetDeclaration]),
+        localSymbol ?? targetDeclaration,
+      ];
+    }
+  });
+}
+
+function buildMemberExpression(path: PythonOutputSymbol[]) {
+  let memberExpr = "";
+
+  const base: PythonOutputSymbol = path[0];
+  if (base.flags & OutputSymbolFlags.InstanceMember) {
+    memberExpr += "self";
+  } else {
+    memberExpr += base.name;
+    path = path.slice(1);
+  }
+
+  for (const sym of path) {
+    memberExpr += `.${sym.name}`;
+  }
+
+  return memberExpr;
+}

package/src/symbols/scopes.ts

@@ -0,0 +1,9 @@
+import { useScope } from "@alloy-js/core";
+import { PythonMemberScope } from "./python-member-scope.js";
+import { PythonModuleScope } from "./python-module-scope.js";
+
+export type PythonOutputScope = PythonModuleScope | PythonMemberScope;
+
+export function usePythonScope() {
+  return useScope() as PythonOutputScope;
+}

package/src/utils.ts

@@ -0,0 +1,27 @@
+import { defaultProps, splitProps } from "@alloy-js/core";
+import { CallSignatureProps } from "./components/index.js";
+
+/**
+ * Extract only the call signature props from a props object which extends
+ * `CallSignatureProps`. You can provide default values for the props.
+ */
+export function getCallSignatureProps(
+  props: CallSignatureProps,
+  defaults?: Partial<CallSignatureProps>,
+) {
+  const [callSignatureProps] = splitProps(props, [
+    "parameters",
+    "typeParameters",
+    "args",
+    "kwargs",
+    "instanceFunction",
+    "classFunction",
+    "returnType",
+  ]);
+
+  if (!defaults) {
+    return callSignatureProps;
+  }
+
+  return defaultProps(callSignatureProps, defaults);
+}