Add Python adapter RFC

[ThomasNieto]

PR Summary

Add Python adapter RFC

PR Context

RFC for #586

[Copilot]

Pull request overview

Adds a new draft RFC proposing a Python adapter (Microsoft.Adapter/Python) and associated SDK/discovery components to enable authoring DSC v3 resources in idiomatic Python.

Changes:

• Introduces RFC 0001 draft describing the Python adapter design, SDK API surface, and discovery/invocation model.
• Specifies proposed manifest formats, stdin/stdout contracts, logging expectations, and multi-runtime/venv behavior.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (4)

rfc/draft/0001-python-adapter.md:2

• RFC frontmatter should follow the RFC process/template format. The process doc uses RFC: RFCNNNN for drafts and indicates authors should not assign the final number in the draft PR; RFC: 0001 is inconsistent.

RFC:          0001

rfc/draft/0001-python-adapter.md:6

• Frontmatter field name SupercededBy is misspelled; RFC0000 uses SupersededBy. Using the wrong key will break automated parsing/validation of RFC metadata.

SupercededBy: null

rfc/draft/0001-python-adapter.md:9

• CommentsDue should be set to an ISO8601 date at least one month out per RFC0000 (it should not be null in a submitted draft PR).

CommentsDue:  null

rfc/draft/0001-python-adapter.md:4

• Frontmatter Author/Sponsor values are consistently unquoted in existing RFCs (e.g., RFC0000); quoting the @user here is inconsistent and may be parsed differently by YAML tooling.

Author:       "@ThomasNieto"
Sponsor:      "@ThomasNieto"

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

rfc/draft/0001-python-adapter.md:508

• Spelling is inconsistent within this RFC: earlier it uses “behavior”, but here it uses “favour”. Consider changing to “favor” for consistency.

Rejected in favour of the package-based adapter structure.

rfc/draft/0001-python-adapter.md:7

• Front-matter key is spelled SupercededBy, but the RFC process document uses SupersededBy (and the misspelling can make metadata inconsistent across RFCs). Consider aligning this RFC to SupersededBy.

Sponsor:      "@ThomasNieto"
Status:       Draft
SupersededBy: null
Version:      1.0

rfc/draft/0001-python-adapter.md:156

• Spelling is inconsistent within this RFC: elsewhere it uses US spelling (“behavior”), but here it says “behavioural”. Consider changing to “behavioral” for consistency.

This issue also appears on line 508 of the same file.

Annotates a `DscResource` subclass with its DSC type identifier and behavioural

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

rfc/draft/0001-python-adapter.md:2

• Per the RFC process, draft RFCs should keep the placeholder RFC number (RFCNNNN) until the WG assigns the number, and the draft filename should also keep RFCNNNN (see rfc/RFC0000-rfc-process.md:46-49 and rfc/RFCNNNN-New-RFC-Template.md:2). Using RFC0001 in the frontmatter (and 0001-... in the filename) makes this draft look already assigned and may break any tooling/workflow that expects the placeholder during review.

RFC:          RFC0001

rfc/draft/0001-python-adapter.md:254

• dsc-gen manifest is referenced as the way manifests are generated, but there’s no other mention of this command/tool in the repo (current search only finds it in this RFC). If this is a new tool being proposed, it would help to briefly define what ships it (part of dsc? a separate CLI?), and whether it’s intended to replace/extend existing dsc resource ... workflows.

Manifests are generated by `dsc-gen manifest` and packaged as package data at
`<package_name>/dsc/*.dsc.adaptedResource.json`. The `content` field is a JSON
object that encodes the Python module and class used for operation dispatch:

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (5)

rfc/draft/0001-python-adapter.md:408

• There are whitespace-only lines inside this mermaid block (e.g., line 405/407) that show up as trailing whitespace. Please remove the spaces so the blank lines are truly blank (and consider running a trailing-whitespace trim on the whole file).

    A["DSC Engine<br/>adapter resource list"] --> B["Python Adapter<br/>pyadapter"]
    
    B --> C{DSC_PYTHON_VIRTUAL_ENV_PATH<br/>set?}
    
    C -->|No| E["Discover resources via entry points"]

rfc/draft/0001-python-adapter.md:2

• The RFC process/template indicates draft RFCs should keep the placeholder number (RFCNNNN) until the working group assigns the final number (see rfc/RFC0000-rfc-process.md:46-49 and rfc/RFCNNNN-New-RFC-Template.md:2). If this is still in the draft stage, please revert the frontmatter RFC field back to the placeholder (and rename the file accordingly).

RFC:          RFC0001

rfc/draft/0001-python-adapter.md:4

• Frontmatter Author/Sponsor values are quoted here, but other RFCs and the RFC process examples use unquoted @UserName values (e.g., rfc/RFC0000-rfc-process.md:54 and rfc/RFC0000-rfc-process.md:2-4). For consistency (and to avoid surprising YAML parsing differences), consider removing the quotes.

Author:       "@ThomasNieto"
Sponsor:      "@ThomasNieto"

rfc/draft/0001-python-adapter.md:339

• This section contains trailing whitespace (e.g., lines 336 and 338). Trailing whitespace can cause noisy diffs and may fail whitespace checks. Please trim trailing whitespace in this section (and the other whitespace-only lines in the mermaid block below).

This issue also appears on line 404 of the same file.

source virtual environment(s) using the canonical `Type@Version` format. This allows 
multiple versions of the same resource to be discovered across different VENVs, and
multiple locations for the same resource version (for DSC engine to select); 
DSC engine handles deduplication and selection.

rfc/draft/0001-python-adapter.md:93

• The Python examples use newer typing syntax like GreetingSchema | None (Python 3.10+) and list[str] (Python 3.9+). The RFC should either specify a minimum supported Python version for the adapter/SDK, or adjust the examples to use Optional[...]/List[...] so the document doesn't implicitly require 3.10+.

    def export(self, instance: GreetingSchema | None) -> Iterator[GreetingSchema]:

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (5)

rfc/draft/0001-python-adapter.md:341

• Same as the manifest cache above: consider using the established adapter cache naming style (PascalCase, no hyphens) for the venv index filename for consistency with other documented cache artifacts (e.g., PSAdapterCache.json).

**Index file locations:**
- **Windows:** `%LOCALAPPDATA%\dsc\python-venv-index.json`
- **Linux/macOS:** `$HOME/.dsc/python-venv-index.json`

rfc/draft/0001-python-adapter.md:2

• The RFC process doc says the author should not assign an RFC number in the draft; the RFC frontmatter should remain RFCNNNN until the working group assigns the number (see rfc/RFC0000-rfc-process.md:46-49 and rfc/RFCNNNN-New-RFC-Template.md:2).

RFC:          RFC0001

rfc/draft/0001-python-adapter.md:490

• The runtime invocation flow says the adapter may spawn a subprocess using the target venv’s Python executable, but earlier the RFC assumes resources can omit ms-dsc as a runtime dependency. As written, it’s unclear how ms_dsc is guaranteed to be importable inside that venv interpreter (e.g., via PYTHONPATH/sys.path injection, vendoring into the venv, etc.).

5. The adapter:
   - Selects the appropriate Python executable based on venv path
   - Spawns a subprocess with that executable if venv is specified
   - Loads the resource module/class from manifest
   - Invokes the operation and returns results (stdout/stderr)

rfc/draft/0001-python-adapter.md:318

• The cache filename here uses lowercase + hyphens, which is inconsistent with the existing adapter cache filenames documented elsewhere (e.g., $HOME/.dsc/PSAdapterCache.json and %LOCALAPPDATA%\dsc\PSAdapterCache.json in docs/reference/resources/Microsoft/Adapter/PowerShell/index.md:79-84). Using the established naming pattern makes it easier to find/recognize cache artifacts across adapters.

This issue also appears on line 339 of the same file.

**Adapter-generated manifest cache locations:**
- **Windows:** `%LOCALAPPDATA%\dsc\python-adapter-manifest-cache.json`
- **Linux/macOS:** `$HOME/.dsc/python-adapter-manifest-cache.json`

rfc/draft/0001-python-adapter.md:104

• This RFC introduces a dsc-gen manifest command, but dsc-gen isn’t referenced anywhere else in the repo, so it’s unclear what tool provides it and how authors are expected to obtain it. Clarifying whether it’s a proposed new CLI shipped with ms-dsc (vs. part of the dsc CLI) will help readers follow the workflow.

through the `Microsoft.Python/Discover` extension. Manifests can also be generated
manually:

```bash
dsc-gen manifest

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

rfc/draft/RFC0001-python-adapter.md:10

• Per the RFC process, authors should not assign an RFC number for drafts; the draft should keep the RFCNNNN placeholder until the working group assigns a number (see rfc/RFC0000-rfc-process.md:46-49 and rfc/RFCNNNN-New-RFC-Template.md:2). This draft frontmatter currently sets RFC0001, which may break consistency/tooling that expects the placeholder for drafts (and typically the filename should match the placeholder as well until assigned).

---
RFC:          RFC0001
Author:       "@ThomasNieto"
Sponsor:      "@ThomasNieto"
Status:       Draft

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

rfc/draft/RFCNNNN-python-adapter.md:524

• This draft doesn’t include the ## Related work items section from the RFC template. Since this RFC is for issue #586 (per the PR description), adding that section with a link to the issue helps traceability and keeps the document aligned with the required template structure.

## Alternate Proposals and Considerations

### Alternative A: Single Python file adapter

A single-file adapter is simpler to ship but limits testability and extensibility.
Rejected in favor of the package-based adapter structure.

### Alternative B: Require Pydantic for all resources

Pydantic provides excellent runtime validation. Rejected as a hard requirement
because many resources are simple and don't need Pydantic's overhead. Pydantic
remains an optional, fully-supported schema backend.

rfc/draft/RFCNNNN-python-adapter.md:2

• Draft RFCs should keep the RFC number as the RFCNNNN placeholder (the working group assigns the final number). Having RFC0001 here conflicts with the RFC template/process and can break tooling/expectations that NNNN remains until assignment.

RFC:          RFC0001

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

rfc/RFC0000-rfc-process.md:2

• This file documents RFC0000 (and is referenced as RFC0000 in rfc/readme.md). Changing the frontmatter RFC number to RFCNNNN makes the metadata inconsistent with the filename and the RFC index, and could break any tooling that uses the frontmatter as the canonical RFC identifier.

RFC:          RFCNNNN

rfc/draft/RFCNNNN-python-adapter.md:4

• Per the RFC process, draft RFCs should not self-assign a numeric RFC identifier; the frontmatter should keep the RFCNNNN placeholder until the WG assigns a number. Also, the process/template expects GitHub usernames without quotes (e.g., @User).

RFC:          RFC0001
Author:       "@ThomasNieto"
Sponsor:      "@ThomasNieto"