diff --git a/.chronus/changes/preserve-pyproject-fields-2026-06-15-feature.md b/.chronus/changes/preserve-pyproject-fields-2026-06-15-feature.md new file mode 100644 index 00000000000..7f34b9afc5a --- /dev/null +++ b/.chronus/changes/preserve-pyproject-fields-2026-06-15-feature.md @@ -0,0 +1,16 @@ +--- +changeKind: feature +packages: + - "@typespec/http-client-python" +--- + +Add a `keep-pyproject-fields` emitter option that selects which `[project]` fields to preserve in an existing `pyproject.toml` instead of overwriting them on regeneration. Supported fields: `authors`, `description`, `classifiers`, `urls`. + +```yaml +# tspconfig.yaml +options: + "@typespec/http-client-python": + keep-pyproject-fields: + authors: true + description: true +``` diff --git a/packages/http-client-python/emitter/src/emitter.ts b/packages/http-client-python/emitter/src/emitter.ts index 0208795e024..32561475861 100644 --- a/packages/http-client-python/emitter/src/emitter.ts +++ b/packages/http-client-python/emitter/src/emitter.ts @@ -210,6 +210,14 @@ async function onEmitMain(context: EmitContext) { commandArgs["packaging-files-config"] = keyValuePairs.join("|"); resolvedOptions["packaging-files-config"] = undefined; } + if (resolvedOptions["keep-pyproject-fields"]) { + // Flatten the object of enabled fields into a comma-separated list for the generator. + const enabledFields = Object.entries(resolvedOptions["keep-pyproject-fields"]) + .filter(([, value]) => value === true) + .map(([key]) => key); + commandArgs["keep-pyproject-fields"] = enabledFields.join(","); + resolvedOptions["keep-pyproject-fields"] = undefined; + } for (const [key, value] of Object.entries(resolvedOptions)) { if (key === "license") continue; // skip license since it is passed in codeModel diff --git a/packages/http-client-python/emitter/src/lib.ts b/packages/http-client-python/emitter/src/lib.ts index b267c836bf3..650dff7ea48 100644 --- a/packages/http-client-python/emitter/src/lib.ts +++ b/packages/http-client-python/emitter/src/lib.ts @@ -24,6 +24,12 @@ export interface PythonEmitterOptions { "head-as-boolean"?: boolean; "use-pyodide"?: boolean; "keep-setup-py"?: boolean; + "keep-pyproject-fields"?: { + authors?: boolean; + description?: boolean; + classifiers?: boolean; + urls?: boolean; + }; "clear-output-folder"?: boolean; "emit-yaml-only"?: boolean; } @@ -105,6 +111,36 @@ export const PythonEmitterOptionsSchema: JSONSchemaType = description: "Whether to keep the existing `setup.py` when `generate-packaging-files` is `true`. If set to `false` and by default, `pyproject.toml` will be generated instead. To generate `setup.py`, use `basic-setup-py`.", }, + "keep-pyproject-fields": { + type: "object", + nullable: true, + description: + "Which manually customized `[project]` fields to preserve in an existing `pyproject.toml` instead of overwriting them on regeneration. Set a field to `true` to keep it. By default no fields are preserved.", + properties: { + authors: { + type: "boolean", + nullable: true, + description: "Preserve the `authors` field (e.g. a custom author name and email).", + }, + description: { + type: "boolean", + nullable: true, + description: "Preserve the `description` field.", + }, + classifiers: { + type: "boolean", + nullable: true, + description: "Preserve the `classifiers` field.", + }, + urls: { + type: "boolean", + nullable: true, + description: "Preserve the `[project.urls]` table.", + }, + }, + required: [], + additionalProperties: false, + }, "clear-output-folder": { type: "boolean", nullable: true, diff --git a/packages/http-client-python/generator/pygen/__init__.py b/packages/http-client-python/generator/pygen/__init__.py index ce6b4d3c7bb..99c890b9553 100644 --- a/packages/http-client-python/generator/pygen/__init__.py +++ b/packages/http-client-python/generator/pygen/__init__.py @@ -29,6 +29,7 @@ class OptionsDict(MutableMapping): "from-typespec": False, "generate-sample": False, "keep-setup-py": False, + "keep-pyproject-fields": "", "generate-test": False, "head-as-boolean": True, "keep-version-file": False, diff --git a/packages/http-client-python/generator/pygen/codegen/serializers/general_serializer.py b/packages/http-client-python/generator/pygen/codegen/serializers/general_serializer.py index 6c022c9259b..c55dc359c65 100644 --- a/packages/http-client-python/generator/pygen/codegen/serializers/general_serializer.py +++ b/packages/http-client-python/generator/pygen/codegen/serializers/general_serializer.py @@ -66,7 +66,26 @@ def _update_version_map(self, version_map: dict[str, str], dep_name: str, dep: s if dep_version > default_version: version_map[dep_name] = str(dep_version) - def external_lib_version_map(self, file_content: str, additional_version_map: dict[str, str]) -> dict: + # Project-level pyproject.toml fields that may be preserved across regeneration + # via the "keep-pyproject-fields" option. + KEEPABLE_PROJECT_FIELDS = ("authors", "description", "classifiers", "urls") + + @staticmethod + def _parse_keep_pyproject_fields(value: Any) -> tuple[str, ...]: + # The "keep-pyproject-fields" option may be a comma-separated string (e.g. + # "authors,description") or an already-parsed sequence of field names. + if not value: + return () + if isinstance(value, str): + return tuple(field.strip() for field in value.split(",") if field.strip()) + return tuple(value) + + def external_lib_version_map( + self, + file_content: str, + additional_version_map: dict[str, str], + keep_pyproject_fields: tuple[str, ...] = (), + ) -> dict: # Load the pyproject.toml file if it exists and extract fields to keep. result: dict = {"KEEP_FIELDS": {}} try: @@ -85,6 +104,14 @@ def external_lib_version_map(self, file_content: str, additional_version_map: di # Process dependencies if "project" in loaded_pyproject_toml: + project = loaded_pyproject_toml["project"] + + # Keep manually customized project fields the emitter would otherwise overwrite. + # Only the fields explicitly listed in the "keep-pyproject-fields" option are preserved. + for field in keep_pyproject_fields: + if field in self.KEEPABLE_PROJECT_FIELDS and field in project: + result["KEEP_FIELDS"][f"project.{field}"] = project[field] + # Handle main dependencies if "dependencies" in loaded_pyproject_toml["project"]: kept_deps = [] @@ -127,7 +154,10 @@ def serialize_package_file(self, template_name: str, file_content: str, **kwargs # Add fields to keep from an existing pyproject.toml if template_name == "pyproject.toml.jinja2": - params = self.external_lib_version_map(file_content, additional_version_map) + keep_pyproject_fields = self._parse_keep_pyproject_fields( + self.code_model.options.get("keep-pyproject-fields") + ) + params = self.external_lib_version_map(file_content, additional_version_map, keep_pyproject_fields) else: params = {} diff --git a/packages/http-client-python/generator/pygen/codegen/templates/packaging_templates/pyproject.toml.jinja2 b/packages/http-client-python/generator/pygen/codegen/templates/packaging_templates/pyproject.toml.jinja2 index 4a012849501..68915429341 100644 --- a/packages/http-client-python/generator/pygen/codegen/templates/packaging_templates/pyproject.toml.jinja2 +++ b/packages/http-client-python/generator/pygen/codegen/templates/packaging_templates/pyproject.toml.jinja2 @@ -11,15 +11,32 @@ build-backend = "setuptools.build_meta" [project] name = "{{ options.get('package-name')|lower }}" {% if options.get('package-mode') %} +{% if KEEP_FIELDS and KEEP_FIELDS.get('project.authors') %} +authors = [ + {% for author in KEEP_FIELDS.get('project.authors') %} + { {% for key, val in author.items() %}{{ key }} = {{ val|tojson }}{% if not loop.last %}, {% endif %}{% endfor %} }, + {% endfor %} +] +{% else %} authors = [ { name = "{{ code_model.company_name }}"{% if code_model.is_azure_flavor %}, email = "azpysdkhelp@microsoft.com"{% endif %} }, ] -{% if options.get("azure-arm") %} +{% endif %} +{% if KEEP_FIELDS and KEEP_FIELDS.get('project.description') %} +description = {{ KEEP_FIELDS.get('project.description')|tojson }} +{% elif options.get("azure-arm") %} description = "Microsoft Azure {{ options.get('package-pprint-name') }} Client Library for Python" {% else %} description = "{{ code_model.company_name }} {% if code_model.is_azure_flavor and not options.get('package-pprint-name').startswith('Azure ') %}Azure {% endif %}{{ options.get('package-pprint-name') }} Client Library for Python" {% endif %} license = "MIT" +{% if KEEP_FIELDS and KEEP_FIELDS.get('project.classifiers') %} +classifiers = [ + {% for classifier in KEEP_FIELDS.get('project.classifiers') %} + {{ classifier|tojson }}, + {% endfor %} +] +{% else %} classifiers = [ "Development Status :: {{ dev_status }}", "Programming Language :: Python", @@ -29,10 +46,15 @@ classifiers = [ "Programming Language :: Python :: 3.{{ version }}", {% endfor %} ] +{% endif %} requires-python = ">={{ MIN_PYTHON_VERSION }}" {% else %} +{% if KEEP_FIELDS and KEEP_FIELDS.get('project.description') %} +description = {{ KEEP_FIELDS.get('project.description')|tojson }} +{% else %} description = "{{ options.get('package-name') }}" {% endif %} +{% endif %} {% if code_model.is_azure_flavor %} keywords = ["azure", "azure sdk"] {% endif %} @@ -77,7 +99,13 @@ version = "{{ options.get("package-version", "unknown") }}" ] {% endfor %} {% endif %} -{% if code_model.is_azure_flavor %} +{% if KEEP_FIELDS and KEEP_FIELDS.get('project.urls') %} + +[project.urls] +{% for key, val in KEEP_FIELDS.get('project.urls').items() %} +{{ key }} = {{ val|tojson }} +{% endfor %} +{% elif code_model.is_azure_flavor %} [project.urls] repository = "https://github.com/Azure/azure-sdk-for-python" diff --git a/packages/http-client-python/tests/unit/test_pyproject_keep_fields.py b/packages/http-client-python/tests/unit/test_pyproject_keep_fields.py new file mode 100644 index 00000000000..b58c4ef6000 --- /dev/null +++ b/packages/http-client-python/tests/unit/test_pyproject_keep_fields.py @@ -0,0 +1,239 @@ +# ------------------------------------------------------------------------- +# Copyright (c) Microsoft Corporation. All rights reserved. +# Licensed under the MIT License. See License.txt in the project root for +# license information. +# -------------------------------------------------------------------------- +"""Unit tests for preserving manually customized pyproject.toml fields. + +The emitter regenerates pyproject.toml on every emit. Manual edits to fields +the emitter doesn't own (description, classifiers, project URLs) must be +preserved so they are not clobbered (see GitHub issue #10311). +""" +from pygen.codegen.serializers.general_serializer import GeneralSerializer + + +_ALL_FIELDS = ("authors", "description", "classifiers", "urls") + + +def _keep_fields(file_content: str, keep_pyproject_fields=_ALL_FIELDS) -> dict: + # external_lib_version_map only relies on module-level helpers, not on + # instance state, so we can bypass __init__ for a focused unit test. + serializer = GeneralSerializer.__new__(GeneralSerializer) + return serializer.external_lib_version_map(file_content, {}, keep_pyproject_fields)["KEEP_FIELDS"] + + +def test_preserve_description(): + content = """ +[project] +name = "azure-ai-sample" +description = "Microsoft Azure AI Sample Client Library for Python" +""" + keep_fields = _keep_fields(content) + assert keep_fields["project.description"] == "Microsoft Azure AI Sample Client Library for Python" + + +def test_preserve_classifiers(): + content = """ +[project] +name = "azure-ai-sample" +classifiers = [ + "Development Status :: 5 - Production/Stable", + "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", +] +""" + keep_fields = _keep_fields(content) + assert "Programming Language :: Python :: 3.14" in keep_fields["project.classifiers"] + + +def test_preserve_project_urls(): + content = """ +[project] +name = "azure-ai-sample" + +[project.urls] +repository = "https://github.com/Azure/azure-sdk-for-python-custom" +documentation = "https://aka.ms/custom-docs" +""" + keep_fields = _keep_fields(content) + assert keep_fields["project.urls"]["repository"] == "https://github.com/Azure/azure-sdk-for-python-custom" + assert keep_fields["project.urls"]["documentation"] == "https://aka.ms/custom-docs" + + +def test_preserve_authors(): + content = """ +[project] +name = "azure-ai-sample" +authors = [ + { name = "Custom Team", email = "custom-team@contoso.com" }, +] +""" + keep_fields = _keep_fields(content) + assert keep_fields["project.authors"] == [{"name": "Custom Team", "email": "custom-team@contoso.com"}] + + +def test_fields_not_kept_when_option_empty(): + content = """ +[project] +name = "azure-ai-sample" +description = "Microsoft Azure AI Sample Client Library for Python" +classifiers = ["Programming Language :: Python :: 3.14"] +authors = [{ name = "Custom Team", email = "custom-team@contoso.com" }] + +[project.urls] +repository = "https://github.com/Azure/azure-sdk-for-python-custom" +""" + keep_fields = _keep_fields(content, keep_pyproject_fields=()) + assert "project.description" not in keep_fields + assert "project.classifiers" not in keep_fields + assert "project.urls" not in keep_fields + assert "project.authors" not in keep_fields + + +def test_only_selected_fields_kept(): + content = """ +[project] +name = "azure-ai-sample" +description = "Microsoft Azure AI Sample Client Library for Python" +classifiers = ["Programming Language :: Python :: 3.14"] +authors = [{ name = "Custom Team", email = "custom-team@contoso.com" }] + +[project.urls] +repository = "https://github.com/Azure/azure-sdk-for-python-custom" +""" + keep_fields = _keep_fields(content, keep_pyproject_fields=("authors", "description")) + assert "project.authors" in keep_fields + assert "project.description" in keep_fields + assert "project.classifiers" not in keep_fields + assert "project.urls" not in keep_fields + + +def test_unknown_field_ignored(): + content = """ +[project] +name = "azure-ai-sample" +description = "kept" +""" + keep_fields = _keep_fields(content, keep_pyproject_fields=("description", "not-a-real-field")) + assert keep_fields["project.description"] == "kept" + assert "project.not-a-real-field" not in keep_fields + + +def test_parse_keep_pyproject_fields(): + parse = GeneralSerializer._parse_keep_pyproject_fields + assert parse(None) == () + assert parse("") == () + assert parse("authors,description") == ("authors", "description") + assert parse(" authors , description ") == ("authors", "description") + assert parse(["authors", "description"]) == ("authors", "description") + + +def test_missing_fields_not_kept(): + content = """ +[project] +name = "azure-ai-sample" +""" + keep_fields = _keep_fields(content) + assert "project.description" not in keep_fields + assert "project.classifiers" not in keep_fields + assert "project.urls" not in keep_fields + assert "project.authors" not in keep_fields + + +def test_invalid_toml_returns_empty(): + assert _keep_fields("this is : not valid = toml [[[") == {} + + +# --- Integration test: option string -> OptionsDict -> parse -> keep -> render --- + +import tomli # noqa: E402 +from pathlib import Path # noqa: E402 +from types import SimpleNamespace # noqa: E402 +from jinja2 import Environment, FileSystemLoader # noqa: E402 +from pygen import OptionsDict # noqa: E402 + + +_TEMPLATE_DIR = str((Path(__file__).resolve().parents[2] / "generator" / "pygen" / "codegen" / "templates")) + + +def _render_pyproject(option_value, existing_content): + """Mirror the relevant wiring in GeneralSerializer.serialize_package_file: + read the option off a real OptionsDict, parse it, extract KEEP_FIELDS from + the existing pyproject.toml, then render the actual template.""" + options = OptionsDict( + { + "package-name": "azure-ai-sample", + "package-mode": "azure-dataplane", + "package-version": "1.0.0", + "keep-pyproject-fields": option_value, + } + ) + serializer = GeneralSerializer.__new__(GeneralSerializer) + parsed = serializer._parse_keep_pyproject_fields(options.get("keep-pyproject-fields")) + keep_fields = serializer.external_lib_version_map(existing_content, {}, parsed)["KEEP_FIELDS"] + + env = Environment(loader=FileSystemLoader(_TEMPLATE_DIR)) + template = env.get_template("packaging_templates/pyproject.toml.jinja2") + code_model = SimpleNamespace( + license_header="", + is_azure_flavor=True, + company_name="Microsoft Corporation", + is_tsp=True, + namespace="azure.ai.sample", + ) + rendered = template.render( + KEEP_FIELDS=keep_fields, + code_model=code_model, + options=options, + dev_status="5 - Production/Stable", + token_credential=False, + pkgutil_names=[], + init_names=[], + client_name="X", + VERSION_MAP={"isodate": "0.6.1", "azure-core": "1.37.0", "typing-extensions": "4.6.0"}, + MIN_PYTHON_VERSION="3.10", + MAX_PYTHON_VERSION="3.14", + ADDITIONAL_DEPENDENCIES=[], + ) + return tomli.loads(rendered) + + +_EXISTING = """ +[project] +name = "azure-ai-sample" +description = "Microsoft Azure AI Sample Client Library for Python" +classifiers = [ + "Development Status :: 5 - Production/Stable", + "Programming Language :: Python :: 3.99", +] +authors = [{ name = "Custom Team", email = "custom-team@contoso.com" }] + +[project.urls] +repository = "https://github.com/Azure/azure-sdk-for-python-custom" +""" + + +def test_render_keeps_selected_fields(): + parsed = _render_pyproject("authors,description", _EXISTING)["project"] + # Selected fields are preserved from the existing file. + assert parsed["authors"] == [{"name": "Custom Team", "email": "custom-team@contoso.com"}] + assert parsed["description"] == "Microsoft Azure AI Sample Client Library for Python" + # Unselected fields are regenerated (custom values dropped). + assert "Programming Language :: Python :: 3.99" not in parsed["classifiers"] + assert parsed["urls"]["repository"] == "https://github.com/Azure/azure-sdk-for-python" + + +def test_render_keeps_nothing_by_default(): + parsed = _render_pyproject("", _EXISTING)["project"] + assert parsed["authors"] == [{"name": "Microsoft Corporation", "email": "azpysdkhelp@microsoft.com"}] + assert parsed["description"] != "Microsoft Azure AI Sample Client Library for Python" + assert "Programming Language :: Python :: 3.99" not in parsed["classifiers"] + assert parsed["urls"]["repository"] == "https://github.com/Azure/azure-sdk-for-python" + + +def test_render_keeps_all_fields(): + parsed = _render_pyproject("authors,description,classifiers,urls", _EXISTING)["project"] + assert parsed["authors"] == [{"name": "Custom Team", "email": "custom-team@contoso.com"}] + assert parsed["description"] == "Microsoft Azure AI Sample Client Library for Python" + assert "Programming Language :: Python :: 3.99" in parsed["classifiers"] + assert parsed["urls"]["repository"] == "https://github.com/Azure/azure-sdk-for-python-custom" diff --git a/website/src/content/docs/docs/emitters/clients/http-client-python/reference/emitter.md b/website/src/content/docs/docs/emitters/clients/http-client-python/reference/emitter.md index bab8db81a1a..438f8ae11f5 100644 --- a/website/src/content/docs/docs/emitters/clients/http-client-python/reference/emitter.md +++ b/website/src/content/docs/docs/emitters/clients/http-client-python/reference/emitter.md @@ -114,6 +114,12 @@ The subdirectory to generate the code in. If not specified, the code will be gen Whether to keep the existing `setup.py` when `generate-packaging-files` is `true`. If set to `false` and by default, `pyproject.toml` will be generated instead. To generate `setup.py`, use `basic-setup-py`. +### `keep-pyproject-fields` + +**Type:** `object` + +Which manually customized `[project]` fields to preserve in an existing `pyproject.toml` instead of overwriting them on regeneration. Set a field to `true` to keep it. Supported fields: `authors`, `description`, `classifiers`, `urls`. By default no fields are preserved. + ### `clear-output-folder` **Type:** `boolean`