@graphql-codegen/python-common 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# `@graphql-codegen/python-common`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared Python-specific helpers for the `@graphql-codegen/python` plugin family (`python`,
+`python-operations`): the naming knowledge those plugins must agree on so their generated classes
+line up exactly, kept in one place.
+
+Modeled on `@graphql-codegen/c-sharp-common` / `@graphql-codegen/java-common`, which play the same
+role for their respective language families.
+
+## What's here
+
+- **`PYTHON_KEYWORDS`** / **`PY_IDENT_RE`** / **`isValidClassAttr`** — the CPython reserved-word set
+  (incl. the soft keywords `match`/`case`) and identifier validation used to decide when a GraphQL
+  name needs escaping.
+- **`PYTHON_SCALARS`** — the default GraphQL scalar → Python type mapping (custom scalars fall back
+  to `Any`).
+- **`pythonFieldName`** / **`isReservedField`** — convert a GraphQL name to `snake_case` for use as
+  a Python identifier, escaping reserved keywords with a trailing `_`.
+- **`pascalCase`** / **`constantCase`** — the class-name and document-constant casing helpers,
+  re-exported from `change-case-all`.
+
+This package is the **single place in the family that depends on `change-case-all`**:
+`pythonFieldName`, `pascalCase`, and `constantCase` all route through it, so every plugin gets the
+same acronym-splitting behavior (`GetHTTPStatus` → `GetHttpStatus` / `get_http_status`) and no
+consumer imports `change-case-all` or hand-rolls the rules itself. `python` and `python-operations`
+get PascalCase names from `BaseVisitor.convertName` (which uses `change-case-all`); a plugin that
+doesn't extend the base visitor can use the `pascalCase` / `constantCase` exported here to produce
+byte-identical names.

package/dist/README.md

@@ -0,0 +1,28 @@
+# `@graphql-codegen/python-common`
+
+Shared Python-specific helpers for the `@graphql-codegen/python` plugin family (`python`,
+`python-operations`): the naming knowledge those plugins must agree on so their generated classes
+line up exactly, kept in one place.
+
+Modeled on `@graphql-codegen/c-sharp-common` / `@graphql-codegen/java-common`, which play the same
+role for their respective language families.
+
+## What's here
+
+- **`PYTHON_KEYWORDS`** / **`PY_IDENT_RE`** / **`isValidClassAttr`** — the CPython reserved-word set
+  (incl. the soft keywords `match`/`case`) and identifier validation used to decide when a GraphQL
+  name needs escaping.
+- **`PYTHON_SCALARS`** — the default GraphQL scalar → Python type mapping (custom scalars fall back
+  to `Any`).
+- **`pythonFieldName`** / **`isReservedField`** — convert a GraphQL name to `snake_case` for use as
+  a Python identifier, escaping reserved keywords with a trailing `_`.
+- **`pascalCase`** / **`constantCase`** — the class-name and document-constant casing helpers,
+  re-exported from `change-case-all`.
+
+This package is the **single place in the family that depends on `change-case-all`**:
+`pythonFieldName`, `pascalCase`, and `constantCase` all route through it, so every plugin gets the
+same acronym-splitting behavior (`GetHTTPStatus` → `GetHttpStatus` / `get_http_status`) and no
+consumer imports `change-case-all` or hand-rolls the rules itself. `python` and `python-operations`
+get PascalCase names from `BaseVisitor.convertName` (which uses `change-case-all`); a plugin that
+doesn't extend the base visitor can use the `pascalCase` / `constantCase` exported here to produce
+byte-identical names.

package/dist/cjs/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./keywords.js"), exports);
+tslib_1.__exportStar(require("./member-naming.js"), exports);
+tslib_1.__exportStar(require("./scalars.js"), exports);

package/dist/cjs/keywords.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PY_IDENT_RE = exports.PYTHON_KEYWORDS = void 0;
+exports.isValidClassAttr = isValidClassAttr;
+/**
+ * Python reserved keywords (from the CPython `keyword` module, incl. the soft
+ * keywords `match`/`case`). Names matching one of these get a trailing `_`
+ * wherever they'd otherwise be used as a Python identifier.
+ */
+exports.PYTHON_KEYWORDS = 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',
+    'yield',
+    'match',
+    'case',
+]);
+/** A valid Python identifier (matches the GraphQL Name grammar plus keywords). */
+exports.PY_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Whether `name` can be used as a plain Python class/dict attribute: it must
+ * be a valid identifier AND not a reserved keyword. When it cannot, the
+ * containing `TypedDict` must be emitted with functional syntax.
+ */
+function isValidClassAttr(name) {
+    return exports.PY_IDENT_RE.test(name) && !exports.PYTHON_KEYWORDS.has(name);
+}

package/dist/cjs/member-naming.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pascalCase = exports.constantCase = void 0;
+exports.pythonFieldName = pythonFieldName;
+exports.isReservedField = isReservedField;
+const change_case_all_1 = require("change-case-all");
+Object.defineProperty(exports, "constantCase", { enumerable: true, get: function () { return change_case_all_1.constantCase; } });
+Object.defineProperty(exports, "pascalCase", { enumerable: true, get: function () { return change_case_all_1.pascalCase; } });
+const keywords_js_1 = require("./keywords.js");
+/**
+ * This module is the single place in the Python plugin family that imports
+ * `change-case-all`. The plugins route their snake / pascal / constant casing
+ * through these exports so the generated names line up exactly and no consumer
+ * hand-rolls (or diverges on) the acronym-splitting rules.
+ */
+/**
+ * snake_case a GraphQL name for use as a Python identifier (field, method, or
+ * document-constant base name), appending a trailing `_` when the result
+ * collides with a reserved keyword.
+ *
+ * Uses change-case-all's `snakeCase` — the same implementation
+ * `@graphql-codegen/python`'s `pascalCase` (via `BaseVisitor.convertName`)
+ * already relies on — so acronym runs split identically on both sides, e.g.
+ * `httpURL` -> `http_url` lines up with `HttpUrl`. A hand-rolled
+ * implementation previously diverged for `pascalCase` on `GetHTTPStatus`.
+ *
+ * Each consumer previously duplicated this exact function under a locally
+ * meaningful name (`methodName`, `pyFieldName`, `snakeFieldName`); import and
+ * alias it the same way here instead of re-implementing it.
+ */
+function pythonFieldName(name) {
+    const snake = (0, change_case_all_1.snakeCase)(name);
+    return keywords_js_1.PYTHON_KEYWORDS.has(snake) ? `${snake}_` : snake;
+}
+/**
+ * Whether a GraphQL response key maps to a Python reserved keyword once
+ * snake-cased (before any trailing-`_` escaping is applied).
+ */
+function isReservedField(name) {
+    return keywords_js_1.PYTHON_KEYWORDS.has((0, change_case_all_1.snakeCase)(name));
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/scalars.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PYTHON_SCALARS = void 0;
+/**
+ * Default GraphQL scalar -> Python type mapping. Custom scalars fall back to
+ * `Any`.
+ */
+exports.PYTHON_SCALARS = {
+    ID: { input: 'str', output: 'str' },
+    String: { input: 'str', output: 'str' },
+    Int: { input: 'int', output: 'int' },
+    Float: { input: 'float', output: 'float' },
+    Boolean: { input: 'bool', output: 'bool' },
+};

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+export * from './keywords.js';
+export * from './member-naming.js';
+export * from './scalars.js';

package/dist/esm/keywords.js

@@ -0,0 +1,54 @@
+/**
+ * Python reserved keywords (from the CPython `keyword` module, incl. the soft
+ * keywords `match`/`case`). Names matching one of these get a trailing `_`
+ * wherever they'd otherwise be used as a Python identifier.
+ */
+export const PYTHON_KEYWORDS = 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',
+    'yield',
+    'match',
+    'case',
+]);
+/** A valid Python identifier (matches the GraphQL Name grammar plus keywords). */
+export const PY_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Whether `name` can be used as a plain Python class/dict attribute: it must
+ * be a valid identifier AND not a reserved keyword. When it cannot, the
+ * containing `TypedDict` must be emitted with functional syntax.
+ */
+export function isValidClassAttr(name) {
+    return PY_IDENT_RE.test(name) && !PYTHON_KEYWORDS.has(name);
+}

package/dist/esm/member-naming.js

@@ -0,0 +1,44 @@
+import { constantCase, pascalCase, snakeCase } from 'change-case-all';
+import { PYTHON_KEYWORDS } from './keywords.js';
+/**
+ * This module is the single place in the Python plugin family that imports
+ * `change-case-all`. The plugins route their snake / pascal / constant casing
+ * through these exports so the generated names line up exactly and no consumer
+ * hand-rolls (or diverges on) the acronym-splitting rules.
+ */
+/**
+ * snake_case a GraphQL name for use as a Python identifier (field, method, or
+ * document-constant base name), appending a trailing `_` when the result
+ * collides with a reserved keyword.
+ *
+ * Uses change-case-all's `snakeCase` — the same implementation
+ * `@graphql-codegen/python`'s `pascalCase` (via `BaseVisitor.convertName`)
+ * already relies on — so acronym runs split identically on both sides, e.g.
+ * `httpURL` -> `http_url` lines up with `HttpUrl`. A hand-rolled
+ * implementation previously diverged for `pascalCase` on `GetHTTPStatus`.
+ *
+ * Each consumer previously duplicated this exact function under a locally
+ * meaningful name (`methodName`, `pyFieldName`, `snakeFieldName`); import and
+ * alias it the same way here instead of re-implementing it.
+ */
+export function pythonFieldName(name) {
+    const snake = snakeCase(name);
+    return PYTHON_KEYWORDS.has(snake) ? `${snake}_` : snake;
+}
+/**
+ * Whether a GraphQL response key maps to a Python reserved keyword once
+ * snake-cased (before any trailing-`_` escaping is applied).
+ */
+export function isReservedField(name) {
+    return PYTHON_KEYWORDS.has(snakeCase(name));
+}
+/**
+ * PascalCase a name for a generated Python class / result-type name.
+ *
+ * This is the exact `change-case-all` `pascalCase` that
+ * `@graphql-codegen/python` and `@graphql-codegen/python-operations` use via
+ * `BaseVisitor.convertName`, re-exported so a plugin that does NOT extend the
+ * base visitor produces byte-identical class names, including acronym runs,
+ * e.g. `GetHTTPStatus` -> `GetHttpStatus`.
+ */
+export { constantCase, pascalCase };

package/dist/esm/scalars.js

@@ -0,0 +1,11 @@
+/**
+ * Default GraphQL scalar -> Python type mapping. Custom scalars fall back to
+ * `Any`.
+ */
+export const PYTHON_SCALARS = {
+    ID: { input: 'str', output: 'str' },
+    String: { input: 'str', output: 'str' },
+    Int: { input: 'int', output: 'int' },
+    Float: { input: 'float', output: 'float' },
+    Boolean: { input: 'bool', output: 'bool' },
+};

package/dist/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@graphql-codegen/python-common",
+  "version": "0.0.1",
+  "description": "Shared Python-specific helpers (reserved keywords, scalar mapping, identifier naming) for @graphql-codegen/python and @graphql-codegen/python-operations.",
+  "sideEffects": false,
+  "dependencies": {
+    "@graphql-codegen/visitor-plugin-common": "^6.3.0",
+    "change-case-all": "1.0.15",
+    "tslib": "^2.8.1"
+  },
+  "repository": "git@github.com:dotansimha/graphql-code-generator-community.git",
+  "license": "MIT",
+  "engines": {
+    "node": ">= 16.0.0"
+  },
+  "main": "cjs/index.js",
+  "module": "esm/index.js",
+  "typings": "typings/index.d.ts",
+  "typescript": {
+    "definition": "typings/index.d.ts"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./typings/index.d.cts",
+        "default": "./cjs/index.js"
+      },
+      "import": {
+        "types": "./typings/index.d.ts",
+        "default": "./esm/index.js"
+      },
+      "default": {
+        "types": "./typings/index.d.ts",
+        "default": "./esm/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  }
+}

package/dist/typings/index.d.cts

@@ -0,0 +1,3 @@
+export * from './keywords.cjs';
+export * from './member-naming.cjs';
+export * from './scalars.cjs';

package/dist/typings/index.d.ts

@@ -0,0 +1,3 @@
+export * from './keywords.js';
+export * from './member-naming.js';
+export * from './scalars.js';

package/dist/typings/keywords.d.cts

@@ -0,0 +1,14 @@
+/**
+ * Python reserved keywords (from the CPython `keyword` module, incl. the soft
+ * keywords `match`/`case`). Names matching one of these get a trailing `_`
+ * wherever they'd otherwise be used as a Python identifier.
+ */
+export declare const PYTHON_KEYWORDS: Set<string>;
+/** A valid Python identifier (matches the GraphQL Name grammar plus keywords). */
+export declare const PY_IDENT_RE: RegExp;
+/**
+ * Whether `name` can be used as a plain Python class/dict attribute: it must
+ * be a valid identifier AND not a reserved keyword. When it cannot, the
+ * containing `TypedDict` must be emitted with functional syntax.
+ */
+export declare function isValidClassAttr(name: string): boolean;

package/dist/typings/keywords.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Python reserved keywords (from the CPython `keyword` module, incl. the soft
+ * keywords `match`/`case`). Names matching one of these get a trailing `_`
+ * wherever they'd otherwise be used as a Python identifier.
+ */
+export declare const PYTHON_KEYWORDS: Set<string>;
+/** A valid Python identifier (matches the GraphQL Name grammar plus keywords). */
+export declare const PY_IDENT_RE: RegExp;
+/**
+ * Whether `name` can be used as a plain Python class/dict attribute: it must
+ * be a valid identifier AND not a reserved keyword. When it cannot, the
+ * containing `TypedDict` must be emitted with functional syntax.
+ */
+export declare function isValidClassAttr(name: string): boolean;

package/dist/typings/member-naming.d.cts

@@ -0,0 +1,38 @@
+import { constantCase, pascalCase } from 'change-case-all';
+/**
+ * This module is the single place in the Python plugin family that imports
+ * `change-case-all`. The plugins route their snake / pascal / constant casing
+ * through these exports so the generated names line up exactly and no consumer
+ * hand-rolls (or diverges on) the acronym-splitting rules.
+ */
+/**
+ * snake_case a GraphQL name for use as a Python identifier (field, method, or
+ * document-constant base name), appending a trailing `_` when the result
+ * collides with a reserved keyword.
+ *
+ * Uses change-case-all's `snakeCase` — the same implementation
+ * `@graphql-codegen/python`'s `pascalCase` (via `BaseVisitor.convertName`)
+ * already relies on — so acronym runs split identically on both sides, e.g.
+ * `httpURL` -> `http_url` lines up with `HttpUrl`. A hand-rolled
+ * implementation previously diverged for `pascalCase` on `GetHTTPStatus`.
+ *
+ * Each consumer previously duplicated this exact function under a locally
+ * meaningful name (`methodName`, `pyFieldName`, `snakeFieldName`); import and
+ * alias it the same way here instead of re-implementing it.
+ */
+export declare function pythonFieldName(name: string): string;
+/**
+ * Whether a GraphQL response key maps to a Python reserved keyword once
+ * snake-cased (before any trailing-`_` escaping is applied).
+ */
+export declare function isReservedField(name: string): boolean;
+/**
+ * PascalCase a name for a generated Python class / result-type name.
+ *
+ * This is the exact `change-case-all` `pascalCase` that
+ * `@graphql-codegen/python` and `@graphql-codegen/python-operations` use via
+ * `BaseVisitor.convertName`, re-exported so a plugin that does NOT extend the
+ * base visitor produces byte-identical class names, including acronym runs,
+ * e.g. `GetHTTPStatus` -> `GetHttpStatus`.
+ */
+export { constantCase, pascalCase };

package/dist/typings/member-naming.d.ts

@@ -0,0 +1,38 @@
+import { constantCase, pascalCase } from 'change-case-all';
+/**
+ * This module is the single place in the Python plugin family that imports
+ * `change-case-all`. The plugins route their snake / pascal / constant casing
+ * through these exports so the generated names line up exactly and no consumer
+ * hand-rolls (or diverges on) the acronym-splitting rules.
+ */
+/**
+ * snake_case a GraphQL name for use as a Python identifier (field, method, or
+ * document-constant base name), appending a trailing `_` when the result
+ * collides with a reserved keyword.
+ *
+ * Uses change-case-all's `snakeCase` — the same implementation
+ * `@graphql-codegen/python`'s `pascalCase` (via `BaseVisitor.convertName`)
+ * already relies on — so acronym runs split identically on both sides, e.g.
+ * `httpURL` -> `http_url` lines up with `HttpUrl`. A hand-rolled
+ * implementation previously diverged for `pascalCase` on `GetHTTPStatus`.
+ *
+ * Each consumer previously duplicated this exact function under a locally
+ * meaningful name (`methodName`, `pyFieldName`, `snakeFieldName`); import and
+ * alias it the same way here instead of re-implementing it.
+ */
+export declare function pythonFieldName(name: string): string;
+/**
+ * Whether a GraphQL response key maps to a Python reserved keyword once
+ * snake-cased (before any trailing-`_` escaping is applied).
+ */
+export declare function isReservedField(name: string): boolean;
+/**
+ * PascalCase a name for a generated Python class / result-type name.
+ *
+ * This is the exact `change-case-all` `pascalCase` that
+ * `@graphql-codegen/python` and `@graphql-codegen/python-operations` use via
+ * `BaseVisitor.convertName`, re-exported so a plugin that does NOT extend the
+ * base visitor produces byte-identical class names, including acronym runs,
+ * e.g. `GetHTTPStatus` -> `GetHttpStatus`.
+ */
+export { constantCase, pascalCase };

package/dist/typings/scalars.d.cts

@@ -0,0 +1,6 @@
+import type { NormalizedScalarsMap } from '@graphql-codegen/visitor-plugin-common';
+/**
+ * Default GraphQL scalar -> Python type mapping. Custom scalars fall back to
+ * `Any`.
+ */
+export declare const PYTHON_SCALARS: NormalizedScalarsMap;

package/dist/typings/scalars.d.ts

@@ -0,0 +1,6 @@
+import type { NormalizedScalarsMap } from '@graphql-codegen/visitor-plugin-common';
+/**
+ * Default GraphQL scalar -> Python type mapping. Custom scalars fall back to
+ * `Any`.
+ */
+export declare const PYTHON_SCALARS: NormalizedScalarsMap;

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@graphql-codegen/python-common",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Shared Python-specific helpers (reserved keywords, scalar mapping, identifier naming) for @graphql-codegen/python and @graphql-codegen/python-operations.",
+  "repository": "git@github.com:dotansimha/graphql-code-generator-community.git",
+  "license": "MIT",
+  "engines": {
+    "node": ">= 16.0.0"
+  },
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/typings/index.d.cts",
+        "default": "./dist/cjs/index.js"
+      },
+      "import": {
+        "types": "./dist/typings/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "default": {
+        "types": "./dist/typings/index.d.ts",
+        "default": "./dist/esm/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "typings": "dist/typings/index.d.ts",
+  "scripts": {
+    "lint": "eslint **/*.ts"
+  },
+  "dependencies": {
+    "@graphql-codegen/visitor-plugin-common": "^6.3.0",
+    "change-case-all": "1.0.15",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@graphql-codegen/testing": "4.0.5"
+  },
+  "publishConfig": {
+    "directory": "dist",
+    "access": "public"
+  },
+  "sideEffects": false,
+  "typescript": {
+    "definition": "dist/typings/index.d.ts"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './keywords.js';
+export * from './member-naming.js';
+export * from './scalars.js';

package/src/keywords.ts

@@ -0,0 +1,56 @@
+/**
+ * Python reserved keywords (from the CPython `keyword` module, incl. the soft
+ * keywords `match`/`case`). Names matching one of these get a trailing `_`
+ * wherever they'd otherwise be used as a Python identifier.
+ */
+export const PYTHON_KEYWORDS = new Set<string>([
+  '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',
+  'yield',
+  'match',
+  'case',
+]);
+
+/** A valid Python identifier (matches the GraphQL Name grammar plus keywords). */
+export const PY_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Whether `name` can be used as a plain Python class/dict attribute: it must
+ * be a valid identifier AND not a reserved keyword. When it cannot, the
+ * containing `TypedDict` must be emitted with functional syntax.
+ */
+export function isValidClassAttr(name: string): boolean {
+  return PY_IDENT_RE.test(name) && !PYTHON_KEYWORDS.has(name);
+}

package/src/member-naming.ts

@@ -0,0 +1,48 @@
+import { constantCase, pascalCase, snakeCase } from 'change-case-all';
+import { PYTHON_KEYWORDS } from './keywords.js';
+
+/**
+ * This module is the single place in the Python plugin family that imports
+ * `change-case-all`. The plugins route their snake / pascal / constant casing
+ * through these exports so the generated names line up exactly and no consumer
+ * hand-rolls (or diverges on) the acronym-splitting rules.
+ */
+
+/**
+ * snake_case a GraphQL name for use as a Python identifier (field, method, or
+ * document-constant base name), appending a trailing `_` when the result
+ * collides with a reserved keyword.
+ *
+ * Uses change-case-all's `snakeCase` — the same implementation
+ * `@graphql-codegen/python`'s `pascalCase` (via `BaseVisitor.convertName`)
+ * already relies on — so acronym runs split identically on both sides, e.g.
+ * `httpURL` -> `http_url` lines up with `HttpUrl`. A hand-rolled
+ * implementation previously diverged for `pascalCase` on `GetHTTPStatus`.
+ *
+ * Each consumer previously duplicated this exact function under a locally
+ * meaningful name (`methodName`, `pyFieldName`, `snakeFieldName`); import and
+ * alias it the same way here instead of re-implementing it.
+ */
+export function pythonFieldName(name: string): string {
+  const snake = snakeCase(name);
+  return PYTHON_KEYWORDS.has(snake) ? `${snake}_` : snake;
+}
+
+/**
+ * Whether a GraphQL response key maps to a Python reserved keyword once
+ * snake-cased (before any trailing-`_` escaping is applied).
+ */
+export function isReservedField(name: string): boolean {
+  return PYTHON_KEYWORDS.has(snakeCase(name));
+}
+
+/**
+ * PascalCase a name for a generated Python class / result-type name.
+ *
+ * This is the exact `change-case-all` `pascalCase` that
+ * `@graphql-codegen/python` and `@graphql-codegen/python-operations` use via
+ * `BaseVisitor.convertName`, re-exported so a plugin that does NOT extend the
+ * base visitor produces byte-identical class names, including acronym runs,
+ * e.g. `GetHTTPStatus` -> `GetHttpStatus`.
+ */
+export { constantCase, pascalCase };

package/src/scalars.ts

@@ -0,0 +1,13 @@
+import type { NormalizedScalarsMap } from '@graphql-codegen/visitor-plugin-common';
+
+/**
+ * Default GraphQL scalar -> Python type mapping. Custom scalars fall back to
+ * `Any`.
+ */
+export const PYTHON_SCALARS: NormalizedScalarsMap = {
+  ID: { input: 'str', output: 'str' },
+  String: { input: 'str', output: 'str' },
+  Int: { input: 'int', output: 'int' },
+  Float: { input: 'float', output: 'float' },
+  Boolean: { input: 'bool', output: 'bool' },
+};

package/tests/python-common.spec.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from 'vitest';
+import {
+  constantCase,
+  isReservedField,
+  isValidClassAttr,
+  pascalCase,
+  PY_IDENT_RE,
+  PYTHON_KEYWORDS,
+  PYTHON_SCALARS,
+  pythonFieldName,
+} from '../src/index.js';
+
+describe('@graphql-codegen/python-common', () => {
+  describe('PYTHON_KEYWORDS', () => {
+    it('contains hard keywords', () => {
+      expect(PYTHON_KEYWORDS.has('class')).toBe(true);
+      expect(PYTHON_KEYWORDS.has('from')).toBe(true);
+      expect(PYTHON_KEYWORDS.has('import')).toBe(true);
+    });
+
+    it('contains the soft keywords match/case', () => {
+      expect(PYTHON_KEYWORDS.has('match')).toBe(true);
+      expect(PYTHON_KEYWORDS.has('case')).toBe(true);
+    });
+
+    it('does not flag ordinary identifiers', () => {
+      expect(PYTHON_KEYWORDS.has('id')).toBe(false);
+      expect(PYTHON_KEYWORDS.has('name')).toBe(false);
+    });
+  });
+
+  describe('PY_IDENT_RE / isValidClassAttr', () => {
+    it('accepts valid identifiers that are not keywords', () => {
+      expect(PY_IDENT_RE.test('user_id')).toBe(true);
+      expect(isValidClassAttr('user_id')).toBe(true);
+    });
+
+    it('rejects reserved keywords even though they match the identifier regex', () => {
+      expect(PY_IDENT_RE.test('class')).toBe(true);
+      expect(isValidClassAttr('class')).toBe(false);
+    });
+
+    it('rejects non-identifier strings', () => {
+      expect(isValidClassAttr('2fast')).toBe(false);
+      expect(isValidClassAttr('my-field')).toBe(false);
+    });
+  });
+
+  describe('PYTHON_SCALARS', () => {
+    it('maps built-in GraphQL scalars to native Python types', () => {
+      expect(PYTHON_SCALARS.ID).toEqual({ input: 'str', output: 'str' });
+      expect(PYTHON_SCALARS.Int).toEqual({ input: 'int', output: 'int' });
+      expect(PYTHON_SCALARS.Float).toEqual({ input: 'float', output: 'float' });
+      expect(PYTHON_SCALARS.Boolean).toEqual({ input: 'bool', output: 'bool' });
+    });
+  });
+
+  describe('pythonFieldName', () => {
+    it('converts camelCase to snake_case', () => {
+      expect(pythonFieldName('createdAt')).toBe('created_at');
+      expect(pythonFieldName('firstName')).toBe('first_name');
+    });
+
+    it('splits acronym runs the same way change-case pascalCase does', () => {
+      expect(pythonFieldName('GetHTTPStatus')).toBe('get_http_status');
+      expect(pythonFieldName('httpURL')).toBe('http_url');
+      expect(pythonFieldName('ABTest')).toBe('ab_test');
+    });
+
+    it('escapes reserved keywords with a trailing underscore', () => {
+      expect(pythonFieldName('from')).toBe('from_');
+      expect(pythonFieldName('class')).toBe('class_');
+    });
+
+    it('leaves non-keyword snake_case names untouched', () => {
+      expect(pythonFieldName('user_id')).toBe('user_id');
+    });
+  });
+
+  describe('isReservedField', () => {
+    it('is true when the snake_cased name is a reserved keyword', () => {
+      expect(isReservedField('from')).toBe(true);
+      expect(isReservedField('Class')).toBe(true); // snake_cases to "class"
+    });
+
+    it('is false when the snake_cased name merely contains a keyword as a substring', () => {
+      expect(isReservedField('className')).toBe(false); // snake_cases to "class_name"
+    });
+
+    it('is false for ordinary field names', () => {
+      expect(isReservedField('createdAt')).toBe(false);
+    });
+  });
+
+  describe('pascalCase', () => {
+    it('PascalCases names for class / result types', () => {
+      expect(pascalCase('getUsers')).toBe('GetUsers');
+      expect(pascalCase('get_users')).toBe('GetUsers');
+    });
+
+    it('lowercases acronym runs so class names line up with BaseVisitor.convertName', () => {
+      expect(pascalCase('GetHTTPStatus')).toBe('GetHttpStatus');
+      expect(pascalCase('httpURL')).toBe('HttpUrl');
+    });
+  });
+
+  describe('constantCase', () => {
+    it('CONSTANT_CASEs names for document constants', () => {
+      expect(constantCase('getUsers')).toBe('GET_USERS');
+      expect(constantCase('GetHTTPStatus')).toBe('GET_HTTP_STATUS');
+    });
+  });
+});

package/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineProject, mergeConfig } from 'vitest/config';
+import { sharedConfig } from '../../../../vitest.config.js';
+
+export default mergeConfig(
+  sharedConfig,
+  defineProject({
+    test: {
+      name: 'python-common',
+      include: ['**/*.spec.ts'],
+    },
+  }),
+);