@alloy-js/python 0.4.0-dev.5 → 0.4.0-dev.7

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.5",
+  "version": "0.4.0-dev.7",
   "description": "Python bindings for Alloy",
   "repository": {
     "type": "git",
@@ -20,13 +20,13 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@alloy-js/core": "~0.22.0 || >= 0.23.0-dev.12",
+    "@alloy-js/core": "~0.22.0 || >= 0.23.0-dev.18",
     "change-case": "^5.4.4",
     "pathe": "^2.0.3"
   },
   "devDependencies": {
-    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.4",
-    "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.1",
+    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.6",
+    "@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",

package/src/name-conflict-resolver.ts

@@ -1,21 +1,19 @@
+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[]) {
+  if (symbols.length === 0) return;
+  // Clear any prior deconflict rename on the first symbol so it reverts to
+  // the plain name once a collision is resolved.
+  symbols[0].deconflictedName = undefined;
   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.deconflictedName =
       symbol.originalName +
       "_" +
       (i + 1) +
       "_" +
-      (symbols[i].aliasTarget?.scope?.name ?? symbol.module ?? "");
+      (symbol.aliasTarget?.scope?.name ?? symbol.module ?? "");
   }
 }

package/test/name-conflict.test.ts

@@ -0,0 +1,37 @@
+import { createOutputBinder } from "@alloy-js/core";
+import { expect, it } from "vitest";
+import { pythonNameConflictResolver } from "../src/name-conflict-resolver.js";
+import { createPythonSymbol } from "../src/symbol-creation.js";
+import { PythonModuleScope } from "../src/symbols/index.js";
+
+it("reverts Python's non-`_N` rename scheme when the conflict is removed", () => {
+  // Python renames via `foo_2_modulename` — the old regex-based revert would
+  // never match this pattern. The deconflictedName slot is pattern-agnostic,
+  // so invoking the resolver with the survivor alone clears the rename
+  // regardless of scheme.
+  const binder = createOutputBinder();
+  const scope = new PythonModuleScope("root", undefined, { binder });
+
+  const a = createPythonSymbol("foo", scope.symbols);
+  const b = createPythonSymbol("foo", scope.symbols);
+
+  // Simulate a conflict pass.
+  pythonNameConflictResolver("foo", [a, b]);
+  expect(a.name).toBe("foo");
+  expect(b.name).not.toBe("foo");
+  expect(b.deconflictedName).toBeDefined();
+
+  // Simulate the post-delete deconflict pass — the sole survivor must have
+  // its prior rename cleared, even though its "rename scheme" differs from
+  // the default `_N` shape.
+  b.deconflictedName = "foo_2_module"; // pretend b had been renamed using python scheme
+  pythonNameConflictResolver("foo", [a]);
+  expect(a.name).toBe("foo");
+  expect(a.deconflictedName).toBeUndefined();
+
+  // And if a was the one carrying the prior rename:
+  a.deconflictedName = "foo_3_other";
+  pythonNameConflictResolver("foo", [a]);
+  expect(a.name).toBe("foo");
+  expect(a.deconflictedName).toBeUndefined();
+});