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

package/docs/api/types/PythonElements.md

@@ -0,0 +1,5 @@
+# PythonElements
+
+```ts
+type PythonElements = "class" | "class-member" | "function" | "variable" | "object-member" | "constant" | "parameter" | "method" | "module" | "enum" | "enum-member";
+```

package/docs/api/types/PythonLexicalScope.md

@@ -0,0 +1,11 @@
+# PythonLexicalScope
+
+## Members
+
+Extends [OutputScope](../../../core/types/outputscope/)
+
+|                   |                                                                          |   |
+| ----------------- | ------------------------------------------------------------------------ | - |
+| declarationSpaces | readonly string\[]                                                       |   |
+| ownerSymbol       | undefined                                                                |   |
+| symbols           | import(“@alloy-js/core”).[OutputSpace](../../../core/types/outputspace/) |   |

package/docs/api/types/PythonMemberScope.md

@@ -0,0 +1,9 @@
+# PythonMemberScope
+
+## Members
+
+Extends [OutputScope](../../../core/types/outputscope/)
+
+|             |                                              |   |
+| ----------- | -------------------------------------------- | - |
+| ownerSymbol | [PythonOutputSymbol](../pythonoutputsymbol/) |   |

package/docs/api/types/PythonModuleScope.md

@@ -0,0 +1,13 @@
+# PythonModuleScope
+
+## Members
+
+Extends [PythonLexicalScope](../pythonlexicalscope/)
+
+|                 |                                                                                                                      |                                                                                                            |
+| --------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| addImport       | (targetSymbol: PythonOutputSymbol, targetModule: PythonModuleScope, options: AddImportOptions) => PythonOutputSymbol |                                                                                                            |
+| addTypeImport   | () => PythonOutputSymbol                                                                                             | Add TYPE\_CHECKING import from the typing module. Returns the local symbol for use in the if block opener. |
+| debugInfo       | Record\<string, unknown>                                                                                             |                                                                                                            |
+| importedModules | [ImportRecords](../importrecords/)                                                                                   |                                                                                                            |
+| importedSymbols | Map<[PythonOutputSymbol](../pythonoutputsymbol/), [PythonOutputSymbol](../pythonoutputsymbol/)>                      |                                                                                                            |

package/docs/api/types/PythonOutputScope.md

@@ -0,0 +1,5 @@
+# PythonOutputScope
+
+```ts
+type PythonOutputScope = PythonLexicalScope | PythonModuleScope | PythonMemberScope;
+```

package/docs/api/types/PythonOutputSymbol.md

@@ -0,0 +1,21 @@
+# PythonOutputSymbol
+
+Represents an ‘exported’ symbol from a .py file. Class, enum, interface etc.
+
+## Members
+
+Extends [OutputSymbol](../../../core/types/outputsymbol/)
+
+|                        |                                                                                                                   |                                                                                                                                   |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| constructor            | (name: string \| Namekey, spaces: OutputSpace\[] \| OutputSpace \| undefined, options: PythonOutputSymbolOptions) | Constructs a new instance of the [`PythonOutputSymbol`](PythonOutputSymbol.md) class                                                                       |
+| copy                   | () => PythonOutputSymbol                                                                                          |                                                                                                                                   |
+| debugInfo              | Record\<string, unknown>                                                                                          |                                                                                                                                   |
+| instanceMembers        | import(“@alloy-js/core”).[OutputMemberSpace](../../../core/types/outputmemberspace/)                              |                                                                                                                                   |
+| isInstanceMemberSymbol | boolean                                                                                                           |                                                                                                                                   |
+| isStaticMemberSymbol   | boolean                                                                                                           |                                                                                                                                   |
+| isTypeOnly             | boolean                                                                                                           | Returns true if this symbol is only used in type annotation contexts. Such symbols can be imported inside a TYPE\_CHECKING block. |
+| markAsValue            | () => void                                                                                                        | Mark this symbol as also being used as a value (not just a type).                                                                 |
+| memberSpaces           | readonly \[“static”, “instance”]                                                                                  |                                                                                                                                   |
+| module                 | string \| undefined                                                                                               |                                                                                                                                   |
+| staticMembers          | import(“@alloy-js/core”).[OutputMemberSpace](../../../core/types/outputmemberspace/)                              |                                                                                                                                   |

package/docs/api/types/PythonOutputSymbolOptions.md

@@ -0,0 +1,10 @@
+# PythonOutputSymbolOptions
+
+## Members
+
+Extends [OutputSymbolOptions](../../../core/types/outputsymboloptions/)
+
+|          |                  |                                                              |
+| -------- | ---------------- | ------------------------------------------------------------ |
+| module   | optional string  |                                                              |
+| typeOnly | optional boolean | Whether this symbol is only used in type annotation contexts |

package/docs/api/types/RefOptions.md

@@ -0,0 +1,7 @@
+# RefOptions
+
+## Members
+
+|      |                  |                                                                                                                         |
+| ---- | ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| type | optional boolean | If true, this reference is only used in a type annotation context. The import will be guarded with `if TYPE_CHECKING:`. |

package/docs/api/types/SubscriptionProps.md

@@ -0,0 +1,9 @@
+# SubscriptionProps
+
+## Members
+
+|       |                                                                                                                                                                     |                                                                                                                    |
+| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| key   | optional [Children](../../../core/types/children/)                                                                                                                  | Single key for subscription access (obj\[key] or obj\[0]). Use this for single subscription access.                |
+| keys  | optional [Children](../../../core/types/children/)\[]                                                                                                               | Multiple keys for tuple subscription access (obj\[a, b] -> obj\[(a, b)]). Use this when you need tuple key access. |
+| slice | optional { start?: [Children](../../../core/types/children/); stop?: [Children](../../../core/types/children/); step?: [Children](../../../core/types/children/); } | Slice notation for subscription access (obj\[start:stop:step]). Use this for Python slice syntax.                  |

package/docs/api/types/index.md

@@ -0,0 +1,31 @@
+# python — types
+
+- [AddImportOptions](AddImportOptions.md)
+- [BaseDeclarationProps](BaseDeclarationProps.md)
+- [CommonFunctionProps](CommonFunctionProps.md) — Shared base interface for function-like components.
+- [CreateModuleProps](CreateModuleProps.md)
+- [CreatePythonSymbolFunctionOptions](CreatePythonSymbolFunctionOptions.md) — Extends [PythonOutputSymbolOptions](../pythonoutputsymboloptions/)
+- [DataclassDecoratorKey](DataclassDecoratorKey.md) — type DataclassDecoratorKey = (typeof dataclassDecoratorKeys)[number];
+- [DataclassDecoratorKwargs](DataclassDecoratorKwargs.md) — type DataclassDecoratorKwargs = Partial<Record<DataclassDecoratorKey, boolean>>;
+- [EnumPropsBase](EnumPropsBase.md) — Extends [BaseDeclarationProps](../basedeclarationprops/)
+- [GoogleStyleDocAttributeProps](GoogleStyleDocAttributeProps.md)
+- [ImportedSymbol](ImportedSymbol.md)
+- [ImportRecordProps](ImportRecordProps.md)
+- [ImportRecords](ImportRecords.md) — Extends Map<[PythonModuleScope](../pythonmodulescope/), [ImportRecordProps](../importrecordprops/)>
+- [LexicalScopeProps](LexicalScopeProps.md) — type LexicalScopeProps = LexicalScopePropsWithScopeValue | LeixcalScopePropsWithScopeInfo;
+- [MemberExpressionPartProps](MemberExpressionPartProps.md)
+- [ModuleDescriptor](ModuleDescriptor.md)
+- [ModuleRefkeys](ModuleRefkeys.md) — type ModuleRefkeys<PD extends Record<string, string[]>> = {
+- [NamedMap](NamedMap.md) — type NamedMap<TDescriptor extends readonly string[]> = {
+- [ParameterDescriptor](ParameterDescriptor.md) — Information for a Python function parameter.
+- [ParameterMarker](ParameterMarker.md) — type ParameterMarker = "*" | "/";
+- [PropertyMethodDeclarationProps](PropertyMethodDeclarationProps.md) — Extends Omit<[CommonFunctionProps](../commonfunctionprops/), “name”>
+- [PythonElements](PythonElements.md) — type PythonElements = "class" | "class-member" | "function" | "variable" | "object-member" | "constant" | "parameter" |
+- [PythonLexicalScope](PythonLexicalScope.md) — Extends [OutputScope](../../../core/types/outputscope/)
+- [PythonMemberScope](PythonMemberScope.md) — Extends [OutputScope](../../../core/types/outputscope/)
+- [PythonModuleScope](PythonModuleScope.md) — Extends [PythonLexicalScope](../pythonlexicalscope/)
+- [PythonOutputScope](PythonOutputScope.md) — type PythonOutputScope = PythonLexicalScope | PythonModuleScope | PythonMemberScope;
+- [PythonOutputSymbol](PythonOutputSymbol.md) — Represents an ‘exported’ symbol from a .py file.
+- [PythonOutputSymbolOptions](PythonOutputSymbolOptions.md) — Extends [OutputSymbolOptions](../../../core/types/outputsymboloptions/)
+- [RefOptions](RefOptions.md)
+- [SubscriptionProps](SubscriptionProps.md)

package/docs/api/variables/abcModule.md

@@ -0,0 +1,7 @@
+# abcModule
+
+```ts
+abcModule: import("../create-module.js").ModuleRefkeys<{
+    readonly ".": ["abstractmethod"];
+}> & SymbolCreator
+```

package/docs/api/variables/dataclassDecoratorKeySet.md

@@ -0,0 +1,5 @@
+# dataclassDecoratorKeySet
+
+```ts
+dataclassDecoratorKeySet: Set<string>
+```

package/docs/api/variables/dataclassDecoratorKeys.md

@@ -0,0 +1,7 @@
+# dataclassDecoratorKeys
+
+Allowed keyword arguments for the Python `@dataclass(...)` decorator. Single source of truth: runtime keys and compile-time type are derived here.
+
+```ts
+dataclassDecoratorKeys: readonly ["init", "repr", "eq", "order", "unsafeHash", "frozen", "matchArgs", "kwOnly", "slots", "weakrefSlot"]
+```

package/docs/api/variables/dataclassesModule.md

@@ -0,0 +1,7 @@
+# dataclassesModule
+
+```ts
+dataclassesModule: import("../create-module.js").ModuleRefkeys<{
+    readonly ".": ["dataclass", "KW_ONLY"];
+}> & SymbolCreator
+```

package/docs/api/variables/enumModule.md

@@ -0,0 +1,7 @@
+# enumModule
+
+```ts
+enumModule: import("../create-module.js").ModuleRefkeys<{
+    readonly ".": ["auto", "Enum", "Flag", "IntEnum", "IntFlag", "StrEnum"];
+}> & SymbolCreator
+```

package/docs/api/variables/index.md

@@ -0,0 +1,8 @@
+# python — variables
+
+- [abcModule](abcModule.md) — abcModule: import("../create-module.js").ModuleRefkeys<{
+- [dataclassDecoratorKeys](dataclassDecoratorKeys.md) — Allowed keyword arguments for the Python `@dataclass(...)` decorator.
+- [dataclassDecoratorKeySet](dataclassDecoratorKeySet.md) — dataclassDecoratorKeySet: Set<string>
+- [dataclassesModule](dataclassesModule.md) — dataclassesModule: import("../create-module.js").ModuleRefkeys<{
+- [enumModule](enumModule.md) — enumModule: import("../create-module.js").ModuleRefkeys<{
+- [requestsModule](requestsModule.md) — requestsModule: import("../create-module.js").ModuleRefkeys<{

package/docs/api/variables/requestsModule.md

@@ -0,0 +1,8 @@
+# requestsModule
+
+```ts
+requestsModule: import("../create-module.js").ModuleRefkeys<{
+    readonly ".": ["get", "post", "put", "delete", "patch", "head", "options"];
+    readonly models: ["Response", "Request"];
+}> & SymbolCreator
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alloy-js/python",
-  "version": "0.4.0-dev.3",
+  "version": "0.4.0-dev.6",
   "description": "Python bindings for Alloy",
   "repository": {
     "type": "git",
@@ -8,9 +8,11 @@
   },
   "exports": {
     ".": {
+      "development": "./dist/dev/src/index.js",
       "import": "./dist/src/index.js"
     },
     "./stc": {
+      "development": "./dist/dev/src/components/stc/index.js",
       "import": "./dist/src/components/stc/index.js"
     }
   },
@@ -18,13 +20,13 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@alloy-js/core": "~0.22.0 || >= 0.23.0-dev.10",
+    "@alloy-js/core": "~0.22.0 || >= 0.23.0-dev.15",
     "change-case": "^5.4.4",
     "pathe": "^2.0.3"
   },
   "devDependencies": {
-    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.3",
-    "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.1",
+    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.5",
+    "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.2",
     "@microsoft/api-extractor": "~7.52.8",
     "@rollup/plugin-typescript": "^12.1.2",
     "concurrently": "^9.2.0",
@@ -34,7 +36,7 @@
   "type": "module",
   "scripts": {
     "generate-docs": "api-extractor run",
-    "build": "alloy build && pnpm run generate-docs",
+    "build": "alloy build --with-dev && pnpm run generate-docs",
     "clean": "rimraf dist/ .temp/",
     "test:watch": "vitest -w",
     "watch": "alloy build --watch",

package/src/components/CallSignature.tsx

@@ -13,6 +13,7 @@ import {
 import { createPythonSymbol } from "../symbol-creation.js";
 import { PythonOutputSymbol } from "../symbols/index.js";
 import { Atom } from "./Atom.jsx";
+import { TypeRefContext } from "./TypeRefContext.jsx";
 
 export type ParameterMarker = "*" | "/";
 
@@ -75,7 +76,10 @@ function parameter(param: DeclaredParameterDescriptor) {
     <group>
       {param.symbol.name}
       <Show when={!!param.type}>
-        : <TypeSlot>{param.type}</TypeSlot>
+        :{" "}
+        <TypeRefContext>
+          <TypeSlot>{param.type}</TypeSlot>
+        </TypeRefContext>
       </Show>
       <Show when={param.default !== undefined}>
         <Show when={!param.type}>=</Show>
@@ -184,7 +188,7 @@ export function CallSignature(props: CallSignatureProps) {
     props.returnType ?
       <>
         {" -> "}
-        {props.returnType}
+        <TypeRefContext>{props.returnType}</TypeRefContext>
       </>
     : undefined;
 

package/src/components/ImportStatement.tsx

@@ -6,6 +6,53 @@ export interface ImportStatementsProps {
   joinImportsFromSameModule?: boolean;
 }
 
+export interface CategorizedImports {
+  /** Imports used only in type annotation contexts (for TYPE_CHECKING block) */
+  typeImports: ImportRecords;
+  /** Regular imports used at runtime */
+  valueImports: ImportRecords;
+}
+
+/**
+ * Categorize import records into type-only and value imports.
+ * Type-only imports are those used only in type annotation contexts.
+ * Value imports are regular imports used at runtime.
+ */
+export function categorizeImportRecords(
+  records: ImportRecords,
+): CategorizedImports {
+  const typeImports = new Map() as ImportRecords;
+  const valueImports = new Map() as ImportRecords;
+
+  for (const [module, properties] of records) {
+    if (!properties.symbols || properties.symbols.size === 0) {
+      // Module-level imports without symbols go to value imports
+      valueImports.set(module, properties);
+      continue;
+    }
+
+    const typeSymbols = new Set<ImportedSymbol>();
+    const valueSymbols = new Set<ImportedSymbol>();
+
+    for (const sym of properties.symbols) {
+      if (sym.local.isTypeOnly) {
+        typeSymbols.add(sym);
+      } else {
+        valueSymbols.add(sym);
+      }
+    }
+
+    if (typeSymbols.size > 0) {
+      typeImports.set(module, { symbols: typeSymbols });
+    }
+    if (valueSymbols.size > 0) {
+      valueImports.set(module, { symbols: valueSymbols });
+    }
+  }
+
+  return { typeImports, valueImports };
+}
+
 /**
  * A component that renders import statements based on the provided import records.
  *
@@ -16,11 +63,11 @@ export interface ImportStatementsProps {
  */
 export function ImportStatements(props: ImportStatementsProps) {
   // Sort the import records by module name
-  const imports = computed(() =>
-    [...props.records].sort(([a], [b]) => {
+  const imports = computed(() => {
+    return [...props.records].sort(([a], [b]) => {
       return a.name.localeCompare(b.name);
-    }),
-  );
+    });
+  });
 
   return mapJoin(
     () => imports.value,

package/src/components/Reference.tsx

@@ -1,4 +1,5 @@
 import { computed, emitSymbol, Refkey } from "@alloy-js/core";
+import { isTypeRefContext } from "../context/type-ref-context.js";
 import { ref } from "../symbols/index.js";
 
 export interface ReferenceProps {
@@ -13,7 +14,8 @@ export interface ReferenceProps {
  * It takes a `refkey` prop which is the key of the symbol to reference.
  */
 export function Reference({ refkey }: ReferenceProps) {
-  const reference = ref(refkey);
+  const inTypeRef = isTypeRefContext();
+  const reference = ref(refkey, { type: inTypeRef });
   const symbolRef = computed(() => reference()[1]);
 
   emitSymbol(symbolRef);

package/src/components/SourceFile.tsx

@@ -1,6 +1,7 @@
 import {
   childrenArray,
   ComponentContext,
+  computed,
   SourceFile as CoreSourceFile,
   createNamedContext,
   createScope,
@@ -14,8 +15,12 @@ import {
 } from "@alloy-js/core";
 import { join } from "pathe";
 import { PythonModuleScope } from "../symbols/index.js";
-import { ImportStatements } from "./ImportStatement.js";
+import {
+  categorizeImportRecords,
+  ImportStatements,
+} from "./ImportStatement.js";
 import { SimpleCommentBlock } from "./PyDoc.js";
+import { PythonBlock } from "./PythonBlock.js";
 import { Reference } from "./Reference.js";
 
 // Non top-level definitions
@@ -99,7 +104,7 @@ export interface SourceFileProps {
   /**
    * __future__ imports to render after the docstring but before regular imports.
    */
-  futureImports?: Children;
+  futureImports?: Children[];
 }
 
 /**
@@ -167,6 +172,28 @@ export function SourceFile(props: SourceFileProps) {
     props.doc !== undefined ||
     props.futureImports !== undefined;
 
+  const imports = computed(() => {
+    // Quick scan for any type-only imports
+    const hasTypeImports = [...scope.importedModules.values()].some(
+      (props) =>
+        props.symbols && [...props.symbols].some((s) => s.local.isTypeOnly),
+    );
+
+    // Add TYPE_CHECKING before categorizing so it's naturally included
+    const typeImportSymbol = hasTypeImports ? scope.addTypeImport() : undefined;
+
+    // Single categorize - TYPE_CHECKING is already in scope.importedModules
+    const { valueImports, typeImports } = categorizeImportRecords(
+      scope.importedModules,
+    );
+
+    return {
+      valueImports,
+      typeImports,
+      typeImportSymbol,
+    };
+  });
+
   return (
     <CoreSourceFile
       path={props.path}
@@ -216,12 +243,21 @@ export function SourceFile(props: SourceFileProps) {
           <hbr />
         </Show>
       </Show>
-      <Show when={scope.importedModules.size > 0}>
-        <ImportStatements records={scope.importedModules} />
-        <Show when={hasChildren}>
-          <hbr />
-          <hbr />
-        </Show>
+      {/* Regular (non-type-only) imports */}
+      <Show when={imports.value.valueImports.size > 0}>
+        <ImportStatements records={imports.value.valueImports} />
+        <hbr />
+      </Show>
+      {/* TYPE_CHECKING block with type-only imports */}
+      <Show when={imports.value.typeImports.size > 0}>
+        <hbr />
+        <PythonBlock opener={`if ${imports.value.typeImportSymbol!.name}:`}>
+          <ImportStatements records={imports.value.typeImports} />
+        </PythonBlock>
+      </Show>
+      {/* Spacing after imports */}
+      <Show when={hasChildren && scope.importedModules.size > 0}>
+        <hbr />
       </Show>
       {/* Extra blank line before top-level definitions */}
       <Show

package/src/components/TypeRefContext.tsx

@@ -0,0 +1,36 @@
+import type { Children } from "@alloy-js/core";
+import {
+  isTypeRefContext,
+  TypeRefContextDef,
+} from "../context/type-ref-context.js";
+
+// Re-export for external use
+export { isTypeRefContext };
+
+export interface TypeRefContextProps {
+  /**
+   * Children
+   */
+  children: Children;
+}
+
+/**
+ * Set the current context of reference to be type reference.
+ *
+ * @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>
+ * ```
+ */
+export const TypeRefContext = ({ children }: TypeRefContextProps) => {
+  return (
+    <TypeRefContextDef.Provider value>{children}</TypeRefContextDef.Provider>
+  );
+};

package/src/components/TypeReference.tsx

@@ -1,5 +1,6 @@
 import { Children, Refkey, Show } from "@alloy-js/core";
 import { TypeArguments } from "./TypeArguments.js";
+import { TypeRefContext } from "./TypeRefContext.js";
 
 export interface TypeReferenceProps {
   /** A refkey to a declared symbol. */
@@ -12,6 +13,11 @@ export interface TypeReferenceProps {
 
 /**
  * A type reference like Foo[T, P] or int.
+ *
+ * @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.
  */
 export function TypeReference(props: TypeReferenceProps) {
   const type = props.refkey ? props.refkey : props.name;
@@ -21,13 +27,15 @@ export function TypeReference(props: TypeReferenceProps) {
     : undefined;
 
   return (
-    <group>
-      <indent>
+    <TypeRefContext>
+      <group>
+        <indent>
+          <sbr />
+          {type}
+          <Show when={Boolean(typeArgs)}>{typeArgs}</Show>
+        </indent>
         <sbr />
-        {type}
-        <Show when={Boolean(typeArgs)}>{typeArgs}</Show>
-      </indent>
-      <sbr />
-    </group>
+      </group>
+    </TypeRefContext>
   );
 }

package/src/components/VariableDeclaration.tsx

@@ -10,6 +10,7 @@ import { createPythonSymbol } from "../symbol-creation.js";
 import { Atom } from "./Atom.jsx";
 import { BaseDeclarationProps } from "./Declaration.jsx";
 import { SimpleCommentBlock } from "./PyDoc.jsx";
+import { TypeRefContext } from "./TypeRefContext.jsx";
 
 export interface VariableDeclarationProps extends BaseDeclarationProps {
   /**
@@ -93,7 +94,10 @@ export function VariableDeclaration(props: VariableDeclarationProps) {
     if (!props.type || props.callStatementVar) return undefined;
     return (
       <>
-        : <TypeSymbolSlot>{props.type}</TypeSymbolSlot>
+        :{" "}
+        <TypeRefContext>
+          <TypeSymbolSlot>{props.type}</TypeSymbolSlot>
+        </TypeRefContext>
       </>
     );
   });

package/src/components/index.ts

@@ -13,7 +13,6 @@ 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";
 export * from "./MemberScope.jsx";
@@ -27,6 +26,7 @@ export * from "./SourceFile.js";
 export * from "./StatementList.js";
 export * from "./StaticMethodDeclaration.js";
 export * from "./TypeArguments.js";
+export * from "./TypeRefContext.js";
 export * from "./TypeReference.js";
 export * from "./UnionTypeExpression.js";
 export * from "./VariableDeclaration.js";

package/src/context/index.ts

@@ -0,0 +1 @@
+export * from "./type-ref-context.js";

package/src/context/type-ref-context.tsx

@@ -0,0 +1,16 @@
+import { ComponentContext, createContext, useContext } from "@alloy-js/core";
+
+/**
+ * Context for tracking whether we are in a type annotation position.
+ * Used to determine if imports should be guarded with TYPE_CHECKING.
+ *
+ * @internal Use the TypeRefContext component instead.
+ */
+export const TypeRefContextDef: ComponentContext<true> = createContext<true>();
+
+/**
+ * @returns 'true' if in a type context, 'false' if in a value context.
+ */
+export function isTypeRefContext(): boolean {
+  return useContext(TypeRefContextDef) === true;
+}

package/src/name-conflict-resolver.ts

@@ -1,21 +1,15 @@
+import { OutputSymbol } from "@alloy-js/core";
 import { PythonOutputSymbol } from "./symbols/python-output-symbol.js";
 
-export function pythonNameConflictResolver(
-  _: string,
-  symbols: PythonOutputSymbol[],
-) {
+export function pythonNameConflictResolver(_: string, symbols: OutputSymbol[]) {
   for (let i = 1; i < symbols.length; i++) {
+    const symbol = symbols[i] as PythonOutputSymbol;
     // 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 ?? "");
+      (symbol.aliasTarget?.scope?.name ?? symbol.module ?? "");
   }
 }