windows python step 40, python setup step 40 windows
**Windows Python Setup Step 40 is TLS and certificates: produce a verified HTTPS trust configuration that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **valid chains succeed and invalid identities fail closed**. The main failure to design against is **disabling certificate verification to bypass setup errors**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | TLS and certificates behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 40 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 40 boundary
The deliverable is **verified HTTPS trust configuration**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns TLS and certificates. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "TLS and certificates"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the TLS and certificates policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 40 exercise command is:
```powershell
python -c "import ssl; print(ssl.get_default_verify_paths())"
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 40 threat review must directly address **disabling certificate verification to bypass setup errors**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to TLS and certificates. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 40
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 40 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | verified HTTPS trust configuration exists in reviewed source | machine-only hidden state |
| normal behavior | valid chains succeed and invalid identities fail closed | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses disabling certificate verification to bypass setup errors | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 40 completion gate
Step 40 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -c "import ssl; print(ssl.get_default_verify_paths())"
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 41 continues with **Tkinter desktop application**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 40 succeeds when valid chains succeed and invalid identities fail closed, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 41, python setup step 41 windows
**Windows Python Setup Step 41 is Tkinter desktop application: produce a responsive minimal Windows GUI that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **the window starts, handles errors, and exits without orphan work**. The main failure to design against is **running long tasks on the UI thread**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Tkinter desktop application behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 41 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 41 boundary
The deliverable is **responsive minimal Windows GUI**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Tkinter desktop application. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Tkinter desktop application"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Tkinter desktop application policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 41 exercise command is:
```powershell
python -m app.gui
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 41 threat review must directly address **running long tasks on the UI thread**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Tkinter desktop application. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 41
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 41 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | responsive minimal Windows GUI exists in reviewed source | machine-only hidden state |
| normal behavior | the window starts, handles errors, and exits without orphan work | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses running long tasks on the UI thread | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 41 completion gate
Step 41 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m app.gui
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 42 continues with **PowerShell integration**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 41 succeeds when the window starts, handles errors, and exits without orphan work, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 42, python setup step 42 windows
**Windows Python Setup Step 42 is PowerShell integration: produce a quoted PowerShell-to-Python interface that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **paths with spaces, exit codes, and parameters survive round trips**. The main failure to design against is **string-built commands and execution-policy workarounds**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | PowerShell integration behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 42 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 42 boundary
The deliverable is **quoted PowerShell-to-Python interface**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns PowerShell integration. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "PowerShell integration"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the PowerShell integration policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 42 exercise command is:
```powershell
powershell -NoProfile -File .\scripts\run_app.ps1
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 42 threat review must directly address **string-built commands and execution-policy workarounds**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to PowerShell integration. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 42
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 42 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | quoted PowerShell-to-Python interface exists in reviewed source | machine-only hidden state |
| normal behavior | paths with spaces, exit codes, and parameters survive round trips | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses string-built commands and execution-policy workarounds | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 42 completion gate
Step 42 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
powershell -NoProfile -File .\scripts\run_app.ps1
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 43 continues with **Windows Task Scheduler**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 42 succeeds when paths with spaces, exit codes, and parameters survive round trips, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 43, python setup step 43 windows
**Windows Python Setup Step 43 is Windows Task Scheduler: produce a non-interactive scheduled invocation that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **the task runs under the intended identity and records an exit result**. The main failure to design against is **embedding credentials or assuming an interactive desktop**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Windows Task Scheduler behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 43 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 43 boundary
The deliverable is **non-interactive scheduled invocation**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Windows Task Scheduler. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Windows Task Scheduler"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Windows Task Scheduler policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 43 exercise command is:
```powershell
schtasks /Query /TN PythonAppTask /V /FO LIST
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 43 threat review must directly address **embedding credentials or assuming an interactive desktop**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Windows Task Scheduler. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 43
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 43 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | non-interactive scheduled invocation exists in reviewed source | machine-only hidden state |
| normal behavior | the task runs under the intended identity and records an exit result | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses embedding credentials or assuming an interactive desktop | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 43 completion gate
Step 43 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
schtasks /Query /TN PythonAppTask /V /FO LIST
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 44 continues with **Windows service design**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 43 succeeds when the task runs under the intended identity and records an exit result, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 44, python setup step 44 windows
**Windows Python Setup Step 44 is Windows service design: produce a service-ready worker lifecycle that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **start, health, stop, timeout, and recovery paths are deterministic**. The main failure to design against is **deploying a script as a service without graceful shutdown**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Windows service design behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 44 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 44 boundary
The deliverable is **service-ready worker lifecycle**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Windows service design. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Windows service design"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Windows service design policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 44 exercise command is:
```powershell
python -m pytest tests\test_service_lifecycle.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 44 threat review must directly address **deploying a script as a service without graceful shutdown**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Windows service design. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 44
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 44 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | service-ready worker lifecycle exists in reviewed source | machine-only hidden state |
| normal behavior | start, health, stop, timeout, and recovery paths are deterministic | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses deploying a script as a service without graceful shutdown | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 44 completion gate
Step 44 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_service_lifecycle.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 45 continues with **File permissions and ACLs**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 44 succeeds when start, health, stop, timeout, and recovery paths are deterministic, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 45, python setup step 45 windows
**Windows Python Setup Step 45 is File permissions and ACLs: produce a least-privilege data-directory ACL plan that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **only intended service and administrator identities can modify data**. The main failure to design against is **granting Everyone full control to fix access errors**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | File permissions and ACLs behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 45 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 45 boundary
The deliverable is **least-privilege data-directory ACL plan**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns File permissions and ACLs. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "File permissions and ACLs"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the File permissions and ACLs policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 45 exercise command is:
```powershell
icacls .\data
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 45 threat review must directly address **granting Everyone full control to fix access errors**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to File permissions and ACLs. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 45
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 45 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | least-privilege data-directory ACL plan exists in reviewed source | machine-only hidden state |
| normal behavior | only intended service and administrator identities can modify data | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses granting Everyone full control to fix access errors | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 45 completion gate
Step 45 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
icacls .\data
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 46 continues with **Temporary files**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 45 succeeds when only intended service and administrator identities can modify data, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 46, python setup step 46 windows
**Windows Python Setup Step 46 is Temporary files: produce a private atomic temporary-file workflow that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **unique creation, atomic replace, cleanup, and failure behavior pass**. The main failure to design against is **predictable names and cross-volume non-atomic moves**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Temporary files behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 46 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 46 boundary
The deliverable is **private atomic temporary-file workflow**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Temporary files. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Temporary files"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Temporary files policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 46 exercise command is:
```powershell
python -m pytest tests\test_tempfiles.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 46 threat review must directly address **predictable names and cross-volume non-atomic moves**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Temporary files. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 46
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 46 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | private atomic temporary-file workflow exists in reviewed source | machine-only hidden state |
| normal behavior | unique creation, atomic replace, cleanup, and failure behavior pass | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses predictable names and cross-volume non-atomic moves | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 46 completion gate
Step 46 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_tempfiles.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 47 continues with **Archives and extraction**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 46 succeeds when unique creation, atomic replace, cleanup, and failure behavior pass, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 47, python setup step 47 windows
**Windows Python Setup Step 47 is Archives and extraction: produce a validated ZIP archive boundary that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **size, member paths, duplicates, and extraction limits are enforced**. The main failure to design against is **zip-slip traversal and decompression bombs**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Archives and extraction behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 47 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 47 boundary
The deliverable is **validated ZIP archive boundary**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Archives and extraction. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Archives and extraction"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Archives and extraction policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 47 exercise command is:
```powershell
python -m pytest tests\test_archives.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 47 threat review must directly address **zip-slip traversal and decompression bombs**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Archives and extraction. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 47
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 47 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | validated ZIP archive boundary exists in reviewed source | machine-only hidden state |
| normal behavior | size, member paths, duplicates, and extraction limits are enforced | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses zip-slip traversal and decompression bombs | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 47 completion gate
Step 47 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_archives.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 48 continues with **Hashes and integrity**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 47 succeeds when size, member paths, duplicates, and extraction limits are enforced, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 48, python setup step 48 windows
**Windows Python Setup Step 48 is Hashes and integrity: produce a SHA-256 manifest verification that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **tampering and missing files fail before use**. The main failure to design against is **confusing an untrusted checksum with authenticity**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Hashes and integrity behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 48 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 48 boundary
The deliverable is **SHA-256 manifest verification**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Hashes and integrity. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Hashes and integrity"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Hashes and integrity policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 48 exercise command is:
```powershell
Get-FileHash .\dist\artifact.whl -Algorithm SHA256
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 48 threat review must directly address **confusing an untrusted checksum with authenticity**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Hashes and integrity. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 48
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 48 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | SHA-256 manifest verification exists in reviewed source | machine-only hidden state |
| normal behavior | tampering and missing files fail before use | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses confusing an untrusted checksum with authenticity | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 48 completion gate
Step 48 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
Get-FileHash .\dist\artifact.whl -Algorithm SHA256
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 49 continues with **Cryptography boundaries**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 48 succeeds when tampering and missing files fail before use, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 49, python setup step 49 windows
**Windows Python Setup Step 49 is Cryptography boundaries: produce a library-backed encryption envelope that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **round trip, wrong key, tampering, and rotation cases pass**. The main failure to design against is **custom cryptographic algorithms or nonce reuse**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Cryptography boundaries behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 49 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 49 boundary
The deliverable is **library-backed encryption envelope**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Cryptography boundaries. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Cryptography boundaries"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Cryptography boundaries policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 49 exercise command is:
```powershell
python -m pytest tests\test_crypto_envelope.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 49 threat review must directly address **custom cryptographic algorithms or nonce reuse**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Cryptography boundaries. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 49
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 49 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | library-backed encryption envelope exists in reviewed source | machine-only hidden state |
| normal behavior | round trip, wrong key, tampering, and rotation cases pass | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses custom cryptographic algorithms or nonce reuse | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 49 completion gate
Step 49 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_crypto_envelope.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 50 continues with **Secret stores**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 49 succeeds when round trip, wrong key, tampering, and rotation cases pass, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
pythonw exe windows, python executable pythonw, pythonw vs python, fix pythonw exe, windows python console executable, sys executable pythonw, python314 pythonw, python console vs windowed
**Windows Python Setup Step 5 is to distinguish console Python from windowed Python, identify which application selected the host, and make terminal, Run, and Debug launch the intended project `.venv\Scripts\python.exe`.** A result ending in `pythonw.exe` is not evidence that Python 3.14 is damaged. It means the current process was started through Python’s windowed executable, which is designed to avoid creating a console window.
The reported client case is:
```python
import sys
print(sys.executable)
```
with output matching this pattern:
```text
C:\Users\\AppData\Local\Programs\Python\Python314\pythonw.exe
```
That observation contains **two independent facts**:
1. The process host is `pythonw.exe`, the windowed variant.
2. The executable is in the per-user global Python 3.14 installation, not in the project `.venv` established in Step 2.
If this output appeared inside IDLE, a GUI application, or another tool that captures standard output, `pythonw.exe` may be intentional. If it appeared while testing a console script in VS Code, a terminal, a shortcut, or a scheduled task, the launch owner is likely misconfigured.
| Launch context | `pythonw.exe` meaning | Correct action |
|---|---|---|
| IDLE Shell | commonly intentional GUI host | use terminal for console proof |
| desktop GUI app | intentional no-console host | keep if output is logged safely |
| VS Code Run/Debug | usually wrong for this tutorial | select `.venv` console Python |
| PowerShell command | wrong command was invoked | use `python`, not `pythonw` |
| double-clicked script | file association chose host | verify from terminal instead |
| shortcut or task | target explicitly chose host | change reviewed target |
| `.pyw` file | windowed intent by convention | use `.py` for console script |
## What `pythonw.exe` is
On Windows, CPython provides console and windowed launch forms. The console form is `python.exe`; the windowed form is `pythonw.exe`. The newer Python Install Manager similarly provides windowed commands such as `pythonw`, `pyw`, and `pymanagerw`.
The windowed form avoids creating a console window. That is useful for Tkinter, tray applications, and other GUI programs that should not open a terminal. It also means normal standard streams may be unavailable or redirected by the host. A plain `print()` may disappear when a script is launched directly through `pythonw.exe`.
If the client saw printed output anyway, an IDE such as IDLE may be capturing or replacing the stream and displaying it in its own Shell window. The visible output does not turn `pythonw.exe` into the console executable.
Do not rename, delete, or overwrite `pythonw.exe`. It is a legitimate part of the installation and may be required by GUI programs. Correct the program, editor, association, shortcut, or task that selected it.
## The expected Step 5 target
For the tutorial project created in Steps 2–4, the console identity should end in:
```text
hello-python\.venv\Scripts\python.exe
```
The exact prefix depends on the user’s project location. The important properties are:
- the final filename is `python.exe`, not `pythonw.exe`;
- the path is inside the intended project `.venv`;
- `pip` and imported packages resolve inside the same environment;
- terminal, VS Code Run, and Debug agree.
The global console sibling for the reported classic Python 3.14 installation would normally follow this pattern:
```text
C:\Users\\AppData\Local\Programs\Python\Python314\python.exe
```
That global `python.exe` is useful for diagnosis and for creating `.venv`, but the project should run through its local `.venv\Scripts\python.exe` after Step 2.
## First reproduce in a real PowerShell console
Open a new PowerShell window. Do not run this test from IDLE, a notebook, a generic editor button, or a file double-click. Run the exact single-line command:
```powershell
python -c "import sys; print(sys.executable)"
```
Then inspect command ownership:
```powershell
Get-Command python -All
where.exe python
Get-Command pythonw -All
where.exe pythonw
```
Expected results differ by installation method, but `python` and `pythonw` should be distinguishable. If typing `python` reports `pythonw.exe`, an alias, association, wrapper, or PATH entry is wrong. If `python` reports the global `python.exe`, Step 1 is working and the remaining task is project activation/selection.
## Return to the project `.venv`
Use the Step 2 project:
```powershell
Set-Location "$HOME\Projects\hello-python"
Test-Path .\.venv\Scripts\python.exe
```
The second command should return `True`. Activate:
```powershell
.\.venv\Scripts\Activate.ps1
```
Now run:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip --version
```
Both paths should point inside `.venv`. This is the preferred correction for a console-based project.
If PowerShell activation is blocked, call the environment explicitly:
```powershell
.\.venv\Scripts\python.exe -c "import sys; print(sys.executable)"
.\.venv\Scripts\python.exe -m pip --version
```
Do not use `.venv\Scripts\pythonw.exe` for this console verification.
## Run a script with the console interpreter
Create `step5_host_probe.py`:
```python
from __future__ import annotations
from pathlib import Path
import sys
def stream_name(stream: object) -> str:
return "None" if stream is None else type(stream).__name__
print(f"executable: {sys.executable}")
print(f"prefix: {sys.prefix}")
print(f"cwd: {Path.cwd()}")
print(f"stdout: {stream_name(sys.stdout)}")
print(f"stderr: {stream_name(sys.stderr)}")
```
Run it from activated PowerShell:
```powershell
python .\step5_host_probe.py
```
The executable should be project-local, and stdout/stderr should be available console streams. If launched through raw `pythonw.exe`, the script may show no window and no visible output at all; that absence is the reason to log GUI failures to a file or structured logging destination rather than relying on `print()`.
## Diagnose IDLE correctly
IDLE is a GUI development environment distributed with CPython. On Windows it may run through the windowed executable so that opening IDLE does not create an extra console. IDLE’s Shell captures program output and displays it inside the application.
Therefore, seeing a global `pythonw.exe` path inside an IDLE Shell can be normal for IDLE. It does not prove that PowerShell or VS Code is configured the same way.
For this tutorial, do not use IDLE’s host identity as the Step 5 console acceptance test. Instead:
1. Save the script in the project folder.
2. Open PowerShell in that folder.
3. Activate `.venv`.
4. Run `python .\step5_host_probe.py`.
5. Verify `.venv\Scripts\python.exe`.
If the client prefers IDLE, it can be started from the desired environment with the console interpreter:
```powershell
python -m idlelib
```
Then verify the resulting Shell identity. IDLE behavior can vary with how it starts/restarts its execution subprocess, so the project terminal remains the authoritative acceptance surface.
## Correct VS Code interpreter selection
Open the actual project folder in VS Code. Use `Ctrl+Shift+P`, run:
```text
Python: Select Interpreter
```
Choose:
```text
.venv\Scripts\python.exe
```
Do not select the global `Python314\pythonw.exe`, a windowed alias, `.venv-check`, or another project’s environment.
Close integrated terminals created before the change and create a new one. Run:
```powershell
python -c "import sys; print(sys.executable)"
```
Use **Run Python File in Terminal** on `step5_host_probe.py`. The printed executable must be the same `.venv\Scripts\python.exe`.
If `pythonw.exe` remains, inspect the status-bar interpreter, environment selector, workspace settings, and extension owners. A generic Code Runner extension may use a custom executor unrelated to Microsoft’s selected Python interpreter. Disable the competing runner or correct its configuration; do not install another Python.
## Correct the VS Code debugger
The Python debugger normally uses the workspace-selected interpreter. Inspect `.vscode\launch.json`. A portable console configuration should resemble:
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Step 5: Console Python",
"type": "debugpy",
"request": "launch",
"program": "${file}",
"console": "integratedTerminal",
"justMyCode": true
}
]
}
```
There is no `python` override, so the selected `.venv` controls the debugger. Remove an accidental override that points to `pythonw.exe` only after reviewing why it exists. Do not replace it with a personal absolute path in shared configuration.
Set a breakpoint in `step5_host_probe.py`, press `F5`, and evaluate in the Debug Console:
```python
sys.executable
```
The result must end in the project `.venv\Scripts\python.exe`.
## Check for an explicitly configured windowed host
Search the project’s reviewed configuration files for `pythonw`:
```powershell
Get-ChildItem -Recurse -File `
-Include *.json,*.ps1,*.cmd,*.bat `
| Select-String -Pattern "pythonw"
```
Review each match. Possible owners include `launch.json`, `tasks.json`, a batch wrapper, a PowerShell script, or a third-party runner setting. Do not perform a blind global replacement: GUI tasks may intentionally need `pythonw.exe`.
For a console task, prefer the selected environment or the project-relative console interpreter. For a GUI task, document why the windowed host is intentional and how errors are logged.
## Inspect shortcuts
If the client starts the program from a desktop or Start-menu shortcut:
1. Right-click the shortcut and open **Properties**.
2. Inspect **Target** and **Start in**.
3. Determine whether Target names `pythonw.exe`.
4. Determine whether the script is a console or GUI program.
5. For a console program, change the reviewed target to the project environment’s `python.exe` and quote paths containing spaces.
6. Set **Start in** to the project directory when relative files are required.
A conceptual console target is:
```text
"\.venv\Scripts\python.exe" "\app.py"
```
Do not copy placeholder brackets literally. Do not publish the client’s username or full private path in a shared configuration.
## Inspect Windows Task Scheduler
For a scheduled task, open its **Actions** tab. A console/background distinction still matters even though the task may run without an interactive desktop.
For a reviewed console Python task:
- **Program/script** should be the full project `.venv\Scripts\python.exe` path.
- **Add arguments** should contain the script path and safe arguments.
- **Start in** should be the project working directory.
- The task account must have access to the environment, project, logs, and required resources.
For a background GUI/no-console task, `pythonw.exe` may be deliberate, but stdout/stderr cannot be the only diagnostic channel. Use application logging and ensure unhandled exceptions are recorded.
Do not store secrets directly in task arguments or shared scripts. Test under the actual task identity and noninteractive environment.
## File Explorer double-click is not a console test
Double-clicking a `.py` file uses Windows file associations and may open a transient console, an editor, a launcher, or a windowed host. The console may close before errors can be read. Newer Python Windows tooling also changes association/launcher behavior over time.
Run console scripts explicitly:
```powershell
python .\app.py
```
or:
```powershell
.\.venv\Scripts\python.exe .\app.py
```
Do not edit the registry by hand as the first fix. If association behavior must change, use supported Windows Default Apps and Python installation/launcher configuration after documenting the desired behavior.
## `.py` versus `.pyw`
The `.pyw` extension conventionally signals a windowed Python program on Windows. It is appropriate for a GUI that manages errors without a console. A console tutorial or CLI should use `.py`.
Renaming a file from `.pyw` to `.py` changes association intent but does not override an editor, shortcut, or task that explicitly calls `pythonw.exe`. Inspect both the extension and the launching command.
Never rename `pythonw.exe` itself. Rename the application script only when its interface genuinely changed from GUI/windowed to console.
## App execution aliases
The Python Install Manager exposes console and windowed aliases. If `pythonw`/`pyw` launch a different runtime than `python`/`py`, open **Manage app execution aliases** from Start and inspect the Python default, windowed, and install-manager entries.
Refresh or correct aliases only when the observed commands are inconsistent. Existing classic installs and legacy launchers can compete with newer manager aliases. Record `Get-Command ... -All` and `where.exe ...` output before changing anything.
Aliases are global command-discovery configuration, while VS Code workspace selection is project configuration. Fix the smallest owner that explains the symptom.
## Verify the base Python 3.14 console sibling
For the reported per-user classic installation, use an environment-variable-based path rather than typing the client’s username:
```powershell
$base = Join-Path `
$env:LocalAppData `
"Programs\Python\Python314\python.exe"
Test-Path $base
& $base -c "import sys; print(sys.executable)"
```
This diagnostic should identify the base `python.exe`. It safely handles spaces in the account path because PowerShell’s call operator invokes the quoted variable value.
The base diagnostic does **not** replace project isolation. Use it to prove the installation has a console executable, then recreate or activate `.venv` as needed.
## Recreate `.venv` only if its host is wrong or missing
Check:
```powershell
Test-Path .\.venv\Scripts\python.exe
Test-Path .\.venv\pyvenv.cfg
```
If both exist and the explicit environment command works, do not recreate it. The launching application is the problem.
If `.venv` was created from the wrong base runtime, is broken, or lacks `python.exe`, preserve source/dependency declarations, deactivate it, and recreate it through Step 2 using the intended base console Python. Then reinstall from the Step 3 requirements/lock workflow. Do not copy `python.exe` into an environment manually.
## Console and GUI error handling differ
Console applications can write diagnostics to stdout/stderr and return an exit code. GUI/windowed applications should use structured logs, an event log, a visible error dialog where appropriate, and an exception boundary that records tracebacks.
Code that assumes `sys.stdout` always exists can fail under a windowed host. Libraries should use the `logging` module rather than unconditional prints for operational diagnostics. The application entry point decides handlers and destinations.
For a GUI application, keeping `pythonw.exe` may be correct. Step 5 then passes when the windowed choice is documented, no console is expected, logs capture startup/errors, and development Run/Debug still uses a controlled interpreter.
## Do not expose client-specific paths
The provided output includes an account name. Treat full user paths as operational details that may reveal personal or organization information. In tickets, documentation, screenshots, and public issues, sanitize them:
```text
C:\Users\\AppData\Local\Programs\Python\Python314\pythonw.exe
```
Preserve the meaningful suffix and installation pattern. Do not remove evidence needed by internal support records, but follow the client’s privacy and data-handling policy.
## Common failures and targeted fixes
**The output is `pythonw.exe` in IDLE.** This can be normal. Verify the console project from PowerShell and do not delete the windowed executable.
**The output is global `python.exe`, not `.venv`.** Activate/select the project environment. The windowed-host issue is fixed, but project isolation is not.
**VS Code status shows `.venv`, but Run prints `pythonw.exe`.** Identify the Run button’s extension owner and inspect runner settings. Use Microsoft’s Run Python File in Terminal.
**Terminal is correct, but Debug prints `pythonw.exe`.** Inspect `launch.json` for a `python` override and confirm `type` is `debugpy`.
**Double-click produces no output.** Run from PowerShell. The association may be windowed or the console may close immediately.
**A GUI app shows no traceback.** Add approved logging/error handling. Do not change to console Python solely to obtain logs in production.
**`where.exe python` shows several installations.** Use `Get-Command -All`, `py list`, and `sys.executable`; remove or reconfigure only an identified unwanted owner.
**The client path contains spaces.** Use PowerShell’s call operator with a quoted path/variable. Do not remove the space or rename the account folder.
**Changing aliases did not fix VS Code.** VS Code workspace selection and `launch.json` can override global discovery. Fix the workspace owner.
## What not to do in Step 5
- Do not delete, rename, or overwrite `pythonw.exe`.
- Do not reinstall Python merely because IDLE uses a windowed host.
- Do not change every `pythonw` reference blindly; GUI apps may need it.
- Do not verify a console project by double-clicking the script.
- Do not select global Python when the project `.venv` exists.
- Do not hard-code a client username in shared configuration.
- Do not put a personal absolute path in committed `launch.json`.
- Do not set PowerShell policy to `Unrestricted` to fix an interpreter choice.
- Do not mix the base Python fix with dependency installation until ownership is proven.
- Do not rely on `print()` as the only error channel for a windowed application.
| Step 5 gate | Pass condition | If it fails |
|---|---|---|
| launch owner | application is identified | reproduce by surface |
| program intent | console or GUI is declared | choose interface first |
| PowerShell identity | console `python.exe` | inspect aliases/PATH |
| project identity | local `.venv` path | activate or select `.venv` |
| VS Code Run | same local console path | fix runner/interpreter |
| VS Code Debug | same local console path | remove windowed override |
| GUI exception path | durable logging exists | add approved handlers |
| privacy review | client path is sanitized | redact account details |
## Step 5 completion gate
For a **console project**, Step 5 is complete only when:
1. The application that originally launched `pythonw.exe` is identified.
2. PowerShell runs the exact console identity command successfully.
3. The project `.venv\Scripts\python.exe` exists and is selected.
4. Integrated terminal, Run Python File, and Debug all report that local console executable.
5. `python -m pip --version` points to the same `.venv`.
6. No reviewed console task, shortcut, or debug configuration explicitly selects `pythonw.exe`.
7. The client’s private path is sanitized in shared reports.
Use this final evidence set from the project terminal:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip --version
python .\step5_host_probe.py
```
For an **intentional GUI project**, Step 5 passes when the windowed host choice is documented, no console is expected, dependencies come from the intended environment, and startup/unhandled errors are written to an approved durable log rather than disappearing with unavailable standard streams.
The next setup step can return to project quality tooling—tests, formatting, linting, and type checking—after interpreter-host ownership is unambiguous. Those tools should run through the same project console environment, even if the shipped GUI entry point uses a windowed host.
**Windows Python Setup Step 5 succeeds when `pythonw.exe` is treated as an intentional interface choice rather than a mystery: identify the launch owner, use project `python.exe` for console development, and retain windowed execution only where GUI behavior and durable diagnostics require it.**
windows python step 50, python setup step 50 windows
**Windows Python Setup Step 50 is Secret stores: produce a Windows-backed secret retrieval adapter that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **retrieval, absence, denial, and redaction are deterministic**. The main failure to design against is **falling back to plaintext files silently**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Secret stores behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 50 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 50 boundary
The deliverable is **Windows-backed secret retrieval adapter**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Secret stores. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Secret stores"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Secret stores policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 50 exercise command is:
```powershell
python -m pytest tests\test_secret_provider.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 50 threat review must directly address **falling back to plaintext files silently**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Secret stores. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 50
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 50 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | Windows-backed secret retrieval adapter exists in reviewed source | machine-only hidden state |
| normal behavior | retrieval, absence, denial, and redaction are deterministic | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses falling back to plaintext files silently | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 50 completion gate
Step 50 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_secret_provider.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 51 continues with **Configuration layering**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 50 succeeds when retrieval, absence, denial, and redaction are deterministic, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 51, python setup step 51 windows
**Windows Python Setup Step 51 is Configuration layering: produce a documented defaults-file-environment-CLI precedence that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **every precedence edge and invalid value is covered**. The main failure to design against is **surprising overrides and environment-dependent tests**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Configuration layering behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 51 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 51 boundary
The deliverable is **documented defaults-file-environment-CLI precedence**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Configuration layering. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Configuration layering"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Configuration layering policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 51 exercise command is:
```powershell
python -m pytest tests\test_config.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 51 threat review must directly address **surprising overrides and environment-dependent tests**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Configuration layering. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 51
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 51 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | documented defaults-file-environment-CLI precedence exists in reviewed source | machine-only hidden state |
| normal behavior | every precedence edge and invalid value is covered | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses surprising overrides and environment-dependent tests | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 51 completion gate
Step 51 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_config.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 52 continues with **Structured logging**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 51 succeeds when every precedence edge and invalid value is covered, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 52, python setup step 52 windows
**Windows Python Setup Step 52 is Structured logging: produce a JSON event schema with correlation identifiers that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **events are parseable, correlated, bounded, and redacted**. The main failure to design against is **high-cardinality or secret-bearing fields**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Structured logging behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 52 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 52 boundary
The deliverable is **JSON event schema with correlation identifiers**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Structured logging. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Structured logging"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Structured logging policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 52 exercise command is:
```powershell
python -m pytest tests\test_structured_logging.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 52 threat review must directly address **high-cardinality or secret-bearing fields**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Structured logging. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 52
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 52 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | JSON event schema with correlation identifiers exists in reviewed source | machine-only hidden state |
| normal behavior | events are parseable, correlated, bounded, and redacted | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses high-cardinality or secret-bearing fields | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 52 completion gate
Step 52 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_structured_logging.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 53 continues with **Metrics and health**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 52 succeeds when events are parseable, correlated, bounded, and redacted, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 53, python setup step 53 windows
**Windows Python Setup Step 53 is Metrics and health: produce a bounded health and metrics surface that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **liveness, readiness, dependency failure, and metric names pass**. The main failure to design against is **reporting healthy before dependencies are ready**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Metrics and health behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 53 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 53 boundary
The deliverable is **bounded health and metrics surface**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Metrics and health. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Metrics and health"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Metrics and health policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 53 exercise command is:
```powershell
python -m pytest tests\test_health.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 53 threat review must directly address **reporting healthy before dependencies are ready**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Metrics and health. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 53
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 53 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | bounded health and metrics surface exists in reviewed source | machine-only hidden state |
| normal behavior | liveness, readiness, dependency failure, and metric names pass | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses reporting healthy before dependencies are ready | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 53 completion gate
Step 53 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_health.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 54 continues with **CPU profiling**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 53 succeeds when liveness, readiness, dependency failure, and metric names pass, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 54, python setup step 54 windows
**Windows Python Setup Step 54 is CPU profiling: produce a reproducible CPU profile experiment that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **the same workload identifies measured hot paths**. The main failure to design against is **optimizing intuition instead of representative evidence**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | CPU profiling behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 54 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 54 boundary
The deliverable is **reproducible CPU profile experiment**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns CPU profiling. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "CPU profiling"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the CPU profiling policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 54 exercise command is:
```powershell
python -m cProfile -o profile.pstats -m app
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 54 threat review must directly address **optimizing intuition instead of representative evidence**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to CPU profiling. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 54
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 54 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | reproducible CPU profile experiment exists in reviewed source | machine-only hidden state |
| normal behavior | the same workload identifies measured hot paths | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses optimizing intuition instead of representative evidence | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 54 completion gate
Step 54 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m cProfile -o profile.pstats -m app
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 55 continues with **Memory profiling**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 54 succeeds when the same workload identifies measured hot paths, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 55, python setup step 55 windows
**Windows Python Setup Step 55 is Memory profiling: produce a bounded memory experiment that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **snapshots identify retained allocations and peak limits**. The main failure to design against is **treating normal caching as a leak or ignoring unbounded growth**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Memory profiling behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 55 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 55 boundary
The deliverable is **bounded memory experiment**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Memory profiling. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Memory profiling"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Memory profiling policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 55 exercise command is:
```powershell
python -X tracemalloc -m pytest tests\test_memory.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 55 threat review must directly address **treating normal caching as a leak or ignoring unbounded growth**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Memory profiling. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 55
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 55 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | bounded memory experiment exists in reviewed source | machine-only hidden state |
| normal behavior | snapshots identify retained allocations and peak limits | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses treating normal caching as a leak or ignoring unbounded growth | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 55 completion gate
Step 55 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -X tracemalloc -m pytest tests\test_memory.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 56 continues with **Performance benchmarks**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 55 succeeds when snapshots identify retained allocations and peak limits, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 56, python setup step 56 windows
**Windows Python Setup Step 56 is Performance benchmarks: produce a stable benchmark baseline that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **distributions are compared on controlled workloads**. The main failure to design against is **using noisy single timings as regression gates**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Performance benchmarks behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 56 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 56 boundary
The deliverable is **stable benchmark baseline**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Performance benchmarks. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Performance benchmarks"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Performance benchmarks policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 56 exercise command is:
```powershell
python -m pytest tests\test_benchmarks.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 56 threat review must directly address **using noisy single timings as regression gates**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Performance benchmarks. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 56
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 56 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | stable benchmark baseline exists in reviewed source | machine-only hidden state |
| normal behavior | distributions are compared on controlled workloads | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses using noisy single timings as regression gates | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 56 completion gate
Step 56 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_benchmarks.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 57 continues with **Pytest fixtures**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 56 succeeds when distributions are compared on controlled workloads, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 57, python setup step 57 windows
**Windows Python Setup Step 57 is Pytest fixtures: produce a scoped composable test resources that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **fixture ownership and teardown order are visible and reliable**. The main failure to design against is **autouse fixtures that hide global behavior**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Pytest fixtures behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 57 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 57 boundary
The deliverable is **scoped composable test resources**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Pytest fixtures. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Pytest fixtures"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Pytest fixtures policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 57 exercise command is:
```powershell
python -m pytest --setup-show
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 57 threat review must directly address **autouse fixtures that hide global behavior**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Pytest fixtures. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 57
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 57 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | scoped composable test resources exists in reviewed source | machine-only hidden state |
| normal behavior | fixture ownership and teardown order are visible and reliable | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses autouse fixtures that hide global behavior | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 57 completion gate
Step 57 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest --setup-show
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 58 continues with **Mocks and fakes**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 57 succeeds when fixture ownership and teardown order are visible and reliable, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 58, python setup step 58 windows
**Windows Python Setup Step 58 is Mocks and fakes: produce a contract-focused test doubles that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **failure modes are simulated without asserting private calls**. The main failure to design against is **mocks that pass while real integrations break**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Mocks and fakes behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 58 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 58 boundary
The deliverable is **contract-focused test doubles**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Mocks and fakes. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Mocks and fakes"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Mocks and fakes policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 58 exercise command is:
```powershell
python -m pytest tests\test_adapters.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 58 threat review must directly address **mocks that pass while real integrations break**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Mocks and fakes. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 58
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 58 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | contract-focused test doubles exists in reviewed source | machine-only hidden state |
| normal behavior | failure modes are simulated without asserting private calls | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses mocks that pass while real integrations break | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 58 completion gate
Step 58 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_adapters.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 59 continues with **Property-based testing**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 58 succeeds when failure modes are simulated without asserting private calls, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 59, python setup step 59 windows
**Windows Python Setup Step 59 is Property-based testing: produce a invariant-driven generated tests that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **failures shrink to reproducible counterexamples**. The main failure to design against is **unbounded strategies and vague invariants**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Property-based testing behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 59 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 59 boundary
The deliverable is **invariant-driven generated tests**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Property-based testing. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Property-based testing"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Property-based testing policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 59 exercise command is:
```powershell
python -m pytest tests\test_properties.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 59 threat review must directly address **unbounded strategies and vague invariants**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Property-based testing. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 59
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 59 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | invariant-driven generated tests exists in reviewed source | machine-only hidden state |
| normal behavior | failures shrink to reproducible counterexamples | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses unbounded strategies and vague invariants | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 59 completion gate
Step 59 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_properties.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 60 continues with **Integration testing**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 59 succeeds when failures shrink to reproducible counterexamples, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
python quality tools windows, pytest windows setup, ruff windows setup, mypy windows setup, python test lint format windows, vscode python testing windows, python dev dependencies windows, python quality gate beginner
**Windows Python Setup Step 6 is to add a small, repeatable quality gate—tests, linting, formatting verification, and static type checking—inside the same project `.venv` proven in Steps 2–5.** The gate must run from PowerShell with explicit commands, surface the same results in VS Code, and return a nonzero exit code when quality fails.
This tutorial uses `pytest` for behavioral tests, Ruff for linting/import organization/formatting, and mypy for static type checks. These are development dependencies, not runtime features of the example application. An existing repository may use unittest, Black, Flake8, Pyright, Pylint, tox, nox, Hatch, uv, Poetry, or another established stack. Follow the project’s declared tools rather than layering this tutorial on top of them.
| Quality surface | Question answered | Pass evidence |
|---|---|---|
| pytest | does behavior match examples? | all selected tests pass |
| Ruff check | are selected code rules satisfied? | zero diagnostics |
| Ruff format check | is formatting canonical? | no file would change |
| mypy | are declared types consistent? | zero type errors |
| VS Code Test Explorer | does editor reproduce tests? | same tests and interpreter |
| aggregate gate | can automation trust one command? | every command exits zero |
| clean recreation | are tools declared? | fresh `.venv` runs gate |
## Step 6 prerequisites
Open a fresh PowerShell window and return to the tutorial project:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
```
Prove the console host and dependency state:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
```
The executable must end in `.venv\Scripts\python.exe`, not the global runtime or `pythonw.exe`, and `pip check` must pass. If not, return to the relevant earlier step.
Inspect the project before adding tools:
```powershell
Get-ChildItem
git status
```
If this is not the tutorial project or it already contains quality configuration, stop and follow its documentation. Do not create competing `pyproject.toml`, pytest, Ruff, or mypy configurations.
## Development tools belong to the project environment
Install the tools through the verified interpreter:
```powershell
python -m pip install pytest ruff mypy
```
Do not use an elevated terminal, global package installation, or `--user`. The tools should be available only because this project environment declares them.
Verify ownership and versions:
```powershell
python -m pytest --version
python -m ruff --version
python -m mypy --version
python -m pip check
```
Version numbers change over time; record them but do not copy versions from this article. The environment’s dependency snapshot or lock should preserve the tested set.
## Record development intent
Create `requirements-dev.in` containing the direct development tools:
```text
pytest
ruff
mypy
```
This file communicates intent for the tutorial. It is not automatically resolved by plain `pip`. If an existing project uses `pyproject.toml` dependency groups, optional dependencies, or a lock manager, declare the tools there instead.
Capture a same-environment tutorial snapshot after installation:
```powershell
python -m pip freeze `
| Set-Content requirements-dev.txt
```
This snapshot includes runtime and development distributions present in `.venv`, including transitive dependencies. It is a recreation artifact, not an explanation of why each package exists.
## Create one project configuration file
Create `pyproject.toml` in the project root:
```toml
[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-ra"
[tool.ruff]
line-length = 100
extend-exclude = [".venv", ".venv-check"]
[tool.ruff.lint]
select = ["E4", "E7", "E9", "F", "B", "I"]
[tool.mypy]
files = ["calculator.py", "tests"]
check_untyped_defs = true
disallow_untyped_defs = true
warn_unused_configs = true
```
`[tool.pytest.ini_options]` is broadly compatible and points discovery at `tests`. Ruff’s rule selection includes core pycodestyle errors, Pyflakes, bugbear-style checks, and import sorting. Ruff’s formatter and linter share configuration but remain separate commands. The mypy settings require annotations on function definitions in this bounded example without enabling every strict-mode option at once.
Do not copy a rule set without team agreement. A quality tool encodes policy, not universal truth. Start with a justified baseline, fix existing findings, and tighten deliberately.
## Add code with explicit behavior and types
Create `calculator.py`:
```python
from __future__ import annotations
def add(left: int, right: int) -> int:
"""Return the sum of two integers."""
return left + right
def mean(values: list[float]) -> float:
"""Return the arithmetic mean of a nonempty list."""
if not values:
raise ValueError("mean requires at least one value")
return sum(values) / len(values)
```
The code has one normal operation and one explicit failure contract. Type annotations make the intended inputs and outputs available to both readers and mypy; runtime tests still prove actual behavior.
## Add focused tests
Create a `tests` folder and `tests\test_calculator.py`:
```python
from __future__ import annotations
import pytest
from calculator import add, mean
@pytest.mark.parametrize(
("left", "right", "expected"),
[(1, 2, 3), (-1, 1, 0), (0, 0, 0)],
)
def test_add(left: int, right: int, expected: int) -> None:
assert add(left, right) == expected
def test_mean() -> None:
assert mean([1.0, 2.5, 4.0]) == 2.5
def test_mean_rejects_empty_input() -> None:
with pytest.raises(ValueError, match="at least one"):
mean([])
```
Test names state the behavior. Parameterization covers several equivalent examples without duplicated test bodies. The error test checks exception type and a stable message fragment, not an entire traceback.
Avoid tests that depend on internet services, current time, random global state, user-specific paths, test order, or the developer’s machine unless those dependencies are explicitly controlled.
## Run pytest from the project root
Run:
```powershell
python -m pytest
```
The expected result is five passing test items: three parameterized `add` examples, the mean example, and the empty-input test. Pytest counts each parameter set as an individual item; trust the collected/passed summary rather than an old screenshot.
Run verbose collection when diagnosing:
```powershell
python -m pytest -vv
```
Use `python -m pytest` rather than a bare `pytest` to tie the runner to the active project interpreter.
## Understand discovery before fixing it
Pytest discovers files/functions using naming conventions and configuration. This tutorial’s `testpaths = ["tests"]` limits the starting directory. Test files use `test_*.py`, and test functions begin with `test_`.
If no tests are collected:
```powershell
python -m pytest --collect-only -q
```
Check the working directory, configuration root, file names, import errors, and selected interpreter. Do not rename files randomly until the discovery report explains the mismatch.
## Run Ruff lint checks
Run:
```powershell
python -m ruff check .
```
Ruff reads the nearest project configuration and respects common ignore files/directories. Passing output indicates no diagnostics under the selected rule set.
To inspect the effective configuration for a file:
```powershell
python -m ruff check calculator.py `
--show-settings
```
This is useful when a parent/user config, wrong working directory, or multiple Ruff configuration files cause surprising results.
Do not use `--fix` on an unreviewed working tree. First inspect diagnostics and diff. Some fixes are safe, some change code structure, and a clean exit does not replace tests.
## Check formatting without changing files
Run the non-mutating gate:
```powershell
python -m ruff format --check .
```
If it fails, preview the difference:
```powershell
python -m ruff format --diff .
```
Then apply formatting intentionally:
```powershell
python -m ruff format .
```
Review `git diff`, rerun tests, and rerun the check. Formatting and linting are different: `ruff format` makes canonical layout changes, while `ruff check` evaluates selected lint rules.
## Run mypy
Run:
```powershell
python -m mypy
```
The `files` setting in `pyproject.toml` supplies the targets. A pass means the analyzed annotations and inferred types are consistent under the configured mypy policy. It does not prove runtime behavior, validate untyped third-party code, or replace tests.
If a dependency lacks type information, read the specific mypy diagnostic and the dependency’s official typing guidance. Do not globally add `ignore_missing_imports = true` merely to silence one package; that can hide real import/type defects throughout the project.
## Run the complete local quality gate
From the project root, run these four commands in order:
```powershell
python -m ruff format --check .
python -m ruff check .
python -m mypy
python -m pytest
```
The order fails fast on cheap deterministic checks before running behavioral tests. A project can choose another order, but local and automated environments must agree.
PowerShell continues after a failed native command when commands are pasted line by line. Inspect each exit code/output. For an aggregate script, explicitly stop on nonzero status rather than assuming `$ErrorActionPreference` handles native process exit codes.
## Add a portable Python gate runner
Create `quality_gate.py`:
```python
from __future__ import annotations
import subprocess
import sys
COMMANDS = [
[sys.executable, "-m", "ruff", "format", "--check", "."],
[sys.executable, "-m", "ruff", "check", "."],
[sys.executable, "-m", "mypy"],
[sys.executable, "-m", "pytest"],
]
def main() -> int:
for command in COMMANDS:
print("+", " ".join(command), flush=True)
result = subprocess.run(command, check=False)
if result.returncode != 0:
return result.returncode
return 0
if __name__ == "__main__":
raise SystemExit(main())
```
Run:
```powershell
python .\quality_gate.py
```
Using `sys.executable` ensures each tool module runs through the same interpreter as the gate. The runner stops on the first failing command and returns its exit code, making it suitable for local use and a later CI step.
The script does not use `shell=True`, interpolate untrusted input, or hide output. Keep automation explicit and reviewable.
## Prove the gate can fail
A gate that has never failed is not yet trusted. Temporarily change an assertion in a local uncommitted edit, run the gate, and confirm a nonzero exit. Restore the edit and confirm a pass.
Similarly, introduce a harmless formatting difference and confirm `ruff format --check` reports it without modifying the file. Restore or run the formatter, review the diff, and rerun all checks.
Do not commit intentionally failing changes. The objective is to verify failure propagation, not pollute history.
## Configure VS Code Test Explorer
Step 4 already selected the project `.venv`. In VS Code, open the Testing view (beaker icon) or run:
```text
Python: Configure Tests
```
Choose **pytest**, then choose the `tests` folder. Because pytest is already declared and installed in `.venv`, the editor should not need to install it silently.
A portable `.vscode\settings.json` testing section can be:
```json
{
"python.testing.pytestEnabled": true,
"python.testing.unittestEnabled": false,
"python.testing.pytestArgs": ["tests"]
}
```
Review and merge with existing settings rather than overwriting the file. This chooses one framework and a relative test path; it does not contain a personal interpreter path.
Refresh Test Explorer. The displayed tests should correspond to terminal collection. Run all tests and one individual test. If results differ, inspect the Python Output/Test Results panels and verify the selected `.venv`.
## Debug a failing test
Set a breakpoint inside `calculator.py` or a test. In Test Explorer choose **Debug Test**. Evaluate:
```python
sys.executable
```
after importing `sys` if needed. The debugger must use `.venv\Scripts\python.exe`.
If a coverage plugin later interferes with breakpoints, follow current VS Code/pytest-cov guidance rather than disabling debugger safeguards globally. Step 6 does not require coverage.
## Editor formatting and linting remain secondary to the gate
The Ruff VS Code extension can provide diagnostics, code actions, and formatting. Configure it to read the project’s `pyproject.toml`; current Ruff editor behavior does so by default unless editor-specific settings override it.
If enabling format-on-save, first establish a clean baseline and team agreement. A save action that rewrites unrelated files can surprise contributors. Command-line `ruff format --check .` remains the authoritative non-mutating gate.
Similarly, a mypy editor extension can provide feedback, but the project’s `python -m mypy` result is the shareable authority. Bundled extension tool versions can differ from `.venv`; prefer an explicitly documented strategy.
## Keep one source of quality policy
Avoid repeating the same line length, selected rules, test paths, and mypy options across `pyproject.toml`, VS Code settings, command arguments, and CI. Duplication drifts.
Use project configuration for tool behavior. Use editor settings only to enable the tool and point to relative project targets. Use automation to call the same commands developers run locally.
When a command-line override is necessary, document why; overrides take precedence and can make local results differ from the project file.
## Separate checks from fixes
Automation and pre-commit gates should generally run non-mutating commands:
```powershell
python -m ruff format --check .
python -m ruff check .
python -m mypy
python -m pytest
```
Developer repair commands are intentional mutations:
```powershell
python -m ruff format .
python -m ruff check . --fix
```
Review diffs after fixes. Do not allow a CI job to modify source and then report success without committing/reviewing the changes.
## Decide what belongs in runtime and development dependencies
The application imports `requests` at runtime in earlier tutorial probes, so it is a runtime dependency for those files. Pytest, Ruff, and mypy are development tools. Production deployment generally should not install them unless runtime diagnostics or policy requires it.
The tutorial’s simple requirements snapshots may mix layers. A mature `pyproject.toml` or lock workflow should express runtime and development groups explicitly. Step 6’s essential rule is that every tool version used by the gate is declared and reproducible.
## Recreate and rerun
Use a clean disposable environment to verify declarations before claiming reproducibility. Create a new environment through the intended base Python, install runtime and development snapshots/lock according to the project workflow, then run:
```powershell
.\.venv-check\Scripts\python.exe .\quality_gate.py
```
If the check environment already exists from Step 3, recreate it only after confirming no needed state lives solely inside it. Never copy the working `.venv` as the test.
A clean pass detects undeclared tools, hidden editable installs, user-site leakage, stale caches, and machine-only dependencies.
## Caches and generated state
Quality tools create caches such as `.pytest_cache`, `.ruff_cache`, `.mypy_cache`, and `__pycache__`. They are generated and normally excluded from version control.
Add to `.gitignore` if needed:
```gitignore
.pytest_cache/
.ruff_cache/
.mypy_cache/
__pycache__/
```
Do not delete caches reflexively when a real diagnostic appears. Clear a cache only when investigating stale behavior and after identifying the exact target. A clean-environment run is stronger evidence than repeated cache deletion.
## Test quality, not only test count
Passing tests can still be weak. Each test should protect a behavior that matters, contain a clear failure message through assertions/context, avoid implementation trivia, and be deterministic.
Do not chase coverage percentage before defining risk. Coverage shows executed lines/branches, not assertion quality, input diversity, or production realism. Add coverage in a later step with an explicit threshold and rationale.
## Static typing is gradual
Mypy checks annotated code against configuration. It does not execute branches or validate external data. Begin with code under active ownership, fix real issues, and expand scope deliberately.
Avoid mass `# type: ignore` comments. A narrow ignore should include the relevant error code and explanation when possible. Review ignores as technical debt because they create unchecked boundaries.
Runtime validation is still required for files, environment variables, JSON, HTTP responses, databases, and user input. Types describe developer expectations; validation establishes facts at trust boundaries.
## Common failures and targeted fixes
**`pytest` is not found.** Run `python -m pytest --version`; if it fails, verify `.venv` and install the declared development dependencies there.
**No tests are discovered.** Run `python -m pytest --collect-only -q`, inspect root/config/names/import errors, and compare VS Code’s selected interpreter.
**Terminal tests pass but VS Code fails.** Verify Step 4 environment selection, testing framework settings, relative test path, and Python output logs.
**Ruff reports different results in editor and terminal.** Inspect editor overrides and `ruff check ... --show-settings`; keep project config authoritative.
**Ruff format changes files after lint passes.** Lint and format are separate. Apply/review formatting, then rerun both checks and tests.
**Mypy reports third-party import errors.** Check whether the package ships types or needs an official stub package. Do not silence every missing import globally.
**A tool runs from global Python.** Use `python -m ` through the verified project interpreter and inspect `sys.executable`.
**The gate passes locally but fails clean recreation.** A tool/dependency/configuration is undeclared, platform-sensitive, or hidden by user/global state. Repair the declaration.
**Formatting creates a huge first diff.** Establish the baseline in a dedicated reviewed change before combining it with behavior changes.
**A quality command modifies files in CI.** Replace it with check mode; fixes belong in a reviewed developer workflow.
## What not to do in Step 6
- Do not install pytest, Ruff, or mypy globally for this project.
- Do not enable two competing test frameworks in VS Code.
- Do not assume editor diagnostics equal command-line gates.
- Do not use mutating format/fix commands as CI checks.
- Do not copy strict settings without establishing a clean baseline.
- Do not silence type errors or lint rules broadly to obtain green output.
- Do not commit tool caches or virtual environments.
- Do not hard-code personal interpreter paths in settings/tasks.
- Do not add network-dependent tests without explicit isolation.
- Do not treat coverage percentage as proof of test quality.
- Do not trust a gate until a deliberate local failure returns nonzero.
| Step 6 gate | Pass condition | If it fails |
|---|---|---|
| interpreter owner | project console `.venv` | fix Steps 2–5 |
| dev dependencies | declared and local | install through local Python |
| project config | one reviewed policy file | remove duplication |
| format/lint/type/test | every command exits zero | fix cause, not symptom |
| failure propagation | deliberate failure is nonzero | repair gate runner |
| VS Code parity | same tests and interpreter | fix selection/settings |
| clean environment | gate passes from declarations | repair reproducibility |
| source control | code/config only | ignore generated state |
## Step 6 completion gate
Step 6 is complete only when:
1. Pytest, Ruff, and mypy are declared development tools inside the project `.venv`.
2. `pyproject.toml` contains one reviewed policy for discovery, linting/formatting, and types.
3. The example tests cover normal, parameterized, and error behavior.
4. Formatting check, lint, type check, and tests all pass from PowerShell.
5. `quality_gate.py` returns nonzero for a deliberate local failure and zero after restoration.
6. VS Code Test Explorer discovers/runs the same pytest suite through the selected `.venv`.
7. A clean environment can install the declared tools and run the same gate.
8. Caches and virtual environments remain outside version control.
Run the final evidence command:
```powershell
python .\quality_gate.py
```
Then record interpreter identity and tool versions:
```powershell
python -c "import sys; print(sys.executable)"
python -m pytest --version
python -m ruff --version
python -m mypy --version
```
All commands must use the project console interpreter. Do not publish private paths, internal indexes, or credentials in logs/screenshots.
The next setup step can move this exact non-mutating gate into continuous integration, define supported Python versions, add dependency caching without trusting it as state, and require the gate on pull requests. CI should call the same project commands rather than inventing a second quality policy.
**Windows Python Setup Step 6 succeeds when tests, style, lint, and types are one declared local contract: PowerShell and VS Code agree, a clean environment reproduces it, and failure reliably stops the gate.**
windows python step 60, python setup step 60 windows
**Windows Python Setup Step 60 is Integration testing: produce a isolated multi-component test boundary that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **real adapters cooperate with controlled dependencies**. The main failure to design against is **calling shared production services from CI**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Integration testing behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 60 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 60 boundary
The deliverable is **isolated multi-component test boundary**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Integration testing. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Integration testing"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Integration testing policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 60 exercise command is:
```powershell
python -m pytest -m integration
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 60 threat review must directly address **calling shared production services from CI**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Integration testing. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 60
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 60 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | isolated multi-component test boundary exists in reviewed source | machine-only hidden state |
| normal behavior | real adapters cooperate with controlled dependencies | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses calling shared production services from CI | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 60 completion gate
Step 60 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest -m integration
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 61 continues with **End-to-end testing**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 60 succeeds when real adapters cooperate with controlled dependencies, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 61, python setup step 61 windows
**Windows Python Setup Step 61 is End-to-end testing: produce a small user-journey acceptance suite that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **critical journeys pass with diagnostic evidence**. The main failure to design against is **large brittle suites that duplicate unit coverage**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | End-to-end testing behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 61 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 61 boundary
The deliverable is **small user-journey acceptance suite**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns End-to-end testing. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "End-to-end testing"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the End-to-end testing policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 61 exercise command is:
```powershell
python -m pytest -m e2e
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 61 threat review must directly address **large brittle suites that duplicate unit coverage**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to End-to-end testing. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 61
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 61 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | small user-journey acceptance suite exists in reviewed source | machine-only hidden state |
| normal behavior | critical journeys pass with diagnostic evidence | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses large brittle suites that duplicate unit coverage | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 61 completion gate
Step 61 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest -m e2e
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 62 continues with **Test-data management**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 61 succeeds when critical journeys pass with diagnostic evidence, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 62, python setup step 62 windows
**Windows Python Setup Step 62 is Test-data management: produce a deterministic factory and fixture data that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **data is minimal, valid, isolated, and free of personal information**. The main failure to design against is **copying production data into repositories**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Test-data management behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 62 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 62 boundary
The deliverable is **deterministic factory and fixture data**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Test-data management. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Test-data management"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Test-data management policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 62 exercise command is:
```powershell
python -m pytest tests\test_factories.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 62 threat review must directly address **copying production data into repositories**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Test-data management. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 62
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 62 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | deterministic factory and fixture data exists in reviewed source | machine-only hidden state |
| normal behavior | data is minimal, valid, isolated, and free of personal information | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses copying production data into repositories | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 62 completion gate
Step 62 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_factories.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 63 continues with **Multi-environment automation**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 62 succeeds when data is minimal, valid, isolated, and free of personal information, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 63, python setup step 63 windows
**Windows Python Setup Step 63 is Multi-environment automation: produce a nox-driven version and task sessions that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **local sessions mirror CI tasks and Python support**. The main failure to design against is **creating a second tool-policy source**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Multi-environment automation behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 63 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 63 boundary
The deliverable is **nox-driven version and task sessions**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Multi-environment automation. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Multi-environment automation"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Multi-environment automation policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 63 exercise command is:
```powershell
python -m nox --list
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 63 threat review must directly address **creating a second tool-policy source**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Multi-environment automation. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 63
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 63 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | nox-driven version and task sessions exists in reviewed source | machine-only hidden state |
| normal behavior | local sessions mirror CI tasks and Python support | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses creating a second tool-policy source | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 63 completion gate
Step 63 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m nox --list
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 64 continues with **Pre-commit checks**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 63 succeeds when local sessions mirror CI tasks and Python support, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 64, python setup step 64 windows
**Windows Python Setup Step 64 is Pre-commit checks: produce a fast reviewed pre-commit hooks that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **hooks reproduce documented check-mode commands**. The main failure to design against is **mutating large trees without review**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Pre-commit checks behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 64 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 64 boundary
The deliverable is **fast reviewed pre-commit hooks**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Pre-commit checks. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Pre-commit checks"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Pre-commit checks policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 64 exercise command is:
```powershell
python -m pre_commit run --all-files
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 64 threat review must directly address **mutating large trees without review**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Pre-commit checks. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 64
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 64 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | fast reviewed pre-commit hooks exists in reviewed source | machine-only hidden state |
| normal behavior | hooks reproduce documented check-mode commands | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses mutating large trees without review | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 64 completion gate
Step 64 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pre_commit run --all-files
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 65 continues with **Git hook governance**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 64 succeeds when hooks reproduce documented check-mode commands, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 65, python setup step 65 windows
**Windows Python Setup Step 65 is Git hook governance: produce a portable hook installation policy that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **hooks assist locally while CI remains authoritative**. The main failure to design against is **treating bypassable local hooks as enforcement**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Git hook governance behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 65 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 65 boundary
The deliverable is **portable hook installation policy**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Git hook governance. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Git hook governance"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Git hook governance policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 65 exercise command is:
```powershell
git config --get core.hooksPath
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 65 threat review must directly address **treating bypassable local hooks as enforcement**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Git hook governance. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 65
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 65 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | portable hook installation policy exists in reviewed source | machine-only hidden state |
| normal behavior | hooks assist locally while CI remains authoritative | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses treating bypassable local hooks as enforcement | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 65 completion gate
Step 65 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
git config --get core.hooksPath
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 66 continues with **Release versioning**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 65 succeeds when hooks assist locally while CI remains authoritative, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 66, python setup step 66 windows
**Windows Python Setup Step 66 is Release versioning: produce a single-source semantic release version that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **source, built metadata, tag, and release notes agree**. The main failure to design against is **manually duplicating versions across files**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Release versioning behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 66 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 66 boundary
The deliverable is **single-source semantic release version**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Release versioning. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Release versioning"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Release versioning policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 66 exercise command is:
```powershell
python -c "import importlib.metadata; print(importlib.metadata.version('app'))"
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 66 threat review must directly address **manually duplicating versions across files**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Release versioning. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 66
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 66 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | single-source semantic release version exists in reviewed source | machine-only hidden state |
| normal behavior | source, built metadata, tag, and release notes agree | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses manually duplicating versions across files | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 66 completion gate
Step 66 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -c "import importlib.metadata; print(importlib.metadata.version('app'))"
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 67 continues with **Build distributions**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 66 succeeds when source, built metadata, tag, and release notes agree, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 67, python setup step 67 windows
**Windows Python Setup Step 67 is Build distributions: produce a clean wheel and source archive that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **both artifacts install and pass smoke tests in clean environments**. The main failure to design against is **shipping untracked files or machine-specific paths**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Build distributions behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 67 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 67 boundary
The deliverable is **clean wheel and source archive**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Build distributions. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Build distributions"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Build distributions policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 67 exercise command is:
```powershell
python -m build
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 67 threat review must directly address **shipping untracked files or machine-specific paths**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Build distributions. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 67
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 67 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | clean wheel and source archive exists in reviewed source | machine-only hidden state |
| normal behavior | both artifacts install and pass smoke tests in clean environments | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses shipping untracked files or machine-specific paths | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 67 completion gate
Step 67 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m build
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 68 continues with **Test package publishing**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 67 succeeds when both artifacts install and pass smoke tests in clean environments, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 68, python setup step 68 windows
**Windows Python Setup Step 68 is Test package publishing: produce a non-production package publication rehearsal that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **metadata renders and the staged package installs by version**. The main failure to design against is **uploading credentials in commands or testing against production first**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Test package publishing behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 68 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 68 boundary
The deliverable is **non-production package publication rehearsal**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Test package publishing. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Test package publishing"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Test package publishing policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 68 exercise command is:
```powershell
python -m twine check dist\*
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 68 threat review must directly address **uploading credentials in commands or testing against production first**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Test package publishing. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 68
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 68 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | non-production package publication rehearsal exists in reviewed source | machine-only hidden state |
| normal behavior | metadata renders and the staged package installs by version | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses uploading credentials in commands or testing against production first | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 68 completion gate
Step 68 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m twine check dist\*
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 69 continues with **Private package indexes**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 68 succeeds when metadata renders and the staged package installs by version, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 69, python setup step 69 windows
**Windows Python Setup Step 69 is Private package indexes: produce a authenticated private-index policy that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **source priority, trust, credentials, and fallback behavior are explicit**. The main failure to design against is **dependency confusion and leaked repository tokens**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Private package indexes behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 69 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 69 boundary
The deliverable is **authenticated private-index policy**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Private package indexes. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Private package indexes"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Private package indexes policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 69 exercise command is:
```powershell
python -m pip config debug
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 69 threat review must directly address **dependency confusion and leaked repository tokens**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Private package indexes. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 69
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 69 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | authenticated private-index policy exists in reviewed source | machine-only hidden state |
| normal behavior | source priority, trust, credentials, and fallback behavior are explicit | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses dependency confusion and leaked repository tokens | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 69 completion gate
Step 69 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pip config debug
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 70 continues with **Supply-chain controls**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 69 succeeds when source priority, trust, credentials, and fallback behavior are explicit, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
python github actions windows, python ci windows setup, github actions python quality gate, windows python ci matrix, setup python github actions, pytest ruff mypy ci, python workflow windows, python ci beginner
**Windows Python Setup Step 7 is to run the exact Step 6 quality gate in GitHub Actions on clean Windows runners for every supported Python version.** This turns a local agreement into continuous-integration evidence: a pull request cannot rely on one developer's `.venv`, editor state, caches, or global packages.
This step uses GitHub-hosted `windows-latest`, `actions/checkout@v6`, and `actions/setup-python@v6`. It gives the workflow token read-only repository-content access, caches pip downloads through the dependency declarations, and calls the existing `quality_gate.py`. It does not deploy, publish, use secrets, or modify source.
| CI surface | Decision | Evidence |
|---|---|---|
| event | pull request, main push, manual | intended runs appear |
| token | `contents: read` only | least privilege |
| runner | GitHub-hosted Windows | clean ephemeral job |
| Python | explicit 3.13 and 3.14 matrix | both supported versions pass |
| dependencies | declared requirement files | clean install succeeds |
| cache | pip download cache only | speed without hidden environment |
| command | `python .\quality_gate.py` | local and CI policy agree |
| enforcement | required status check | merge waits for green |
## Step 7 prerequisites
Start from the Step 6 project root in a normal PowerShell window:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python .\quality_gate.py
git status
```
The identity command must print the project's console interpreter ending in `.venv\Scripts\python.exe`; the gate must return zero; and source-control status must be understood. Do not create CI around a failing or unexplained local baseline.
The repository must already contain the files Step 7 needs: source code, tests, `pyproject.toml`, `quality_gate.py`, runtime/development dependency declarations, and `.gitignore`. A file present only on one computer cannot be installed or tested by a clean runner.
## Decide the supported Python contract
A matrix is a product-support declaration, not a collection of interesting versions. This tutorial tests Python 3.13 and 3.14 because it demonstrates more than one supported interpreter and includes the client's Python 3.14 environment. Change the list to match the project's documented support policy.
Before publishing that policy, test each version locally where practical. The Python Install Manager can install side-by-side runtimes, but do not replace or unregister a working runtime merely to build a matrix. CI is useful precisely because hosted runners isolate versions.
Use quoted YAML strings such as `"3.13"` and `"3.14"`. Quoting prevents YAML from treating version-like values as numbers. Avoid broad selectors such as `3.x` when a support contract requires repeatable version selection.
Patch releases within a selected minor line can advance as hosted images/tool caches update. This tutorial promises minor-version compatibility, not bit-for-bit interpreter immutability. A project requiring a specific patch must state and maintain that stronger contract intentionally.
## Keep dependency intent reviewable
Step 6 created tutorial snapshots. Confirm both files are tracked:
```powershell
git ls-files requirements.txt requirements-dev.txt pyproject.toml quality_gate.py
```
If a command prints nothing for a required file, add the file deliberately and review it. If the actual repository uses dependency groups, a lock file, pip-tools, Poetry, uv, Hatch, or another established manager, translate the install step to that system. Do not maintain two competing sources of truth.
The simple tutorial workflow installs `requirements.txt` and then `requirements-dev.txt`. A full Step 6 freeze may repeat runtime distributions in the development snapshot; pip can resolve that, but mature projects should use a documented lock/group model so runtime and development intent remain clear.
Run a local dependency consistency check before CI:
```powershell
python -m pip check
```
Do not place index credentials, tokens, proxy passwords, or private package URLs containing secrets in requirement files. Private registries require a separately designed secret and trust boundary; they are outside this no-secret beginner workflow.
## Create the workflow directory and file
Create `.github\workflows` if it does not exist:
```powershell
New-Item -ItemType Directory -Force .github\workflows
New-Item -ItemType File -Force .github\workflows\python-quality.yml
```
Open `.github\workflows\python-quality.yml` and add:
```yaml
name: Python quality
on:
pull_request:
push:
branches:
- main
workflow_dispatch:
permissions:
contents: read
concurrency:
group: python-quality-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
quality:
name: Windows / Python ${{ matrix.python-version }}
runs-on: windows-latest
timeout-minutes: 15
strategy:
fail-fast: false
matrix:
python-version:
- "3.13"
- "3.14"
steps:
- name: Check out repository
uses: actions/checkout@v6
- name: Set up Python
uses: actions/setup-python@v6
with:
python-version: ${{ matrix.python-version }}
cache: pip
cache-dependency-path: |
requirements.txt
requirements-dev.txt
- name: Show interpreter
shell: pwsh
run: |
python --version
python -c "import sys; print(sys.executable)"
python -m pip --version
- name: Install dependencies
shell: pwsh
run: |
python -m pip install -r requirements.txt
python -m pip install -r requirements-dev.txt
python -m pip check
- name: Run quality gate
shell: pwsh
run: python .\quality_gate.py
```
The diagnostic `python -c "import sys; print(sys.executable)"` is one complete physical command line. Do not place a PowerShell continuation backtick between `-c` and its Python code. A split form changes parsing and can make troubleshooting evidence misleading.
If the repository's default branch is not `main`, replace the branch name. Do not add every branch to `push`; pull-request runs normally supply review evidence, while the default-branch push confirms the merged result.
## Understand each trust boundary
`pull_request` tests proposed code without granting the elevated context associated with `pull_request_target`. Tests execute repository code and dependency build hooks, so untrusted contributions must run on isolated hosted runners without secrets.
`permissions: contents: read` narrows the automatic `GITHUB_TOKEN`. This workflow needs to check out code; it does not need to write contents, issues, pull requests, packages, deployments, or attestations. Add a permission only when a named job genuinely needs it.
Do not change this workflow to `pull_request_target` and then check out/execute contributor code. That event operates in the base repository's privileged context and needs a separate threat model. Do not use secrets in pull-request test commands, echo contexts wholesale, or upload environment dumps.
GitHub-hosted runners are disposable job environments. A self-hosted Windows machine changes the threat model: untrusted code could reach persistent files, credentials, network services, or later jobs. Do not substitute a reused workstation for `windows-latest` without isolation and security ownership.
## Why the action versions are explicit
The workflow uses the current supported major tags shown by the official action projects: checkout v6 and setup-python v6. Major tags receive compatible updates and are readable for a tutorial. Review action upgrades like dependencies and let an approved update process keep them current.
Higher-assurance organizations often pin actions to full commit SHAs and use automated review/update tooling. If that is policy, replace tags with reviewed immutable SHAs; do not invent or truncate a hash. A full SHA improves immutability but still needs maintenance for security fixes.
`setup-python@v6` and checkout v6 use a Node 24 action runtime. GitHub-hosted runners satisfy current requirements. Self-hosted runners must meet the action's documented runner-version prerequisite before adopting these majors.
## What setup-python proves
The setup action selects the requested interpreter and adds it to `PATH` for later steps. The Show interpreter step records the effective version, executable, and pip owner. On a hosted runner the executable will not end in the local project `.venv`; that is expected.
Local parity means the same supported Python line, dependency declarations, configuration, and quality commands—not the same absolute executable path. CI should never copy a developer's `.venv` or hard-code `C:\Users\Danny Li\...`.
Because every job gets a clean runner, this workflow installs into the job's selected Python environment rather than activating the developer's `.venv`. `python -m pip` and `python .\quality_gate.py` keep package installation and gate execution bound to the selected interpreter.
## Cache downloads, not correctness
`cache: pip` makes repeated installs faster by caching pip's download/wheel cache. It does not cache an installed virtual environment and does not make undeclared packages available. The requirement files feed the cache key so dependency edits cause a new cache identity.
Never cache `.venv`, `site-packages`, `.pytest_cache`, `.ruff_cache`, or `.mypy_cache` as a substitute for installation and execution. Installed environments embed paths and interpreter/platform details; tool caches may hide stale analysis. Every job must still run install, `pip check`, and the gate after cache restoration.
A cache miss is normal, not a failure. A cache hit improves time, not trust. If a restored artifact appears suspicious, the clean install and checks remain authoritative. Avoid broad restore keys that let unrelated dependency states masquerade as current.
If only one dependency file exists, remove the missing path from `cache-dependency-path` and install commands. Do not create an empty file merely to satisfy copied YAML.
## Reuse the Step 6 command contract
The final step calls `quality_gate.py`, which invokes format check, lint, mypy, and pytest through `sys.executable` and propagates the first nonzero exit. That is the key parity mechanism: tool order and policy live with the project rather than being duplicated in workflow YAML.
Do not replace check-mode commands with mutating commands such as:
```powershell
python -m ruff format .
python -m ruff check . --fix
```
CI should report the reviewed source's state, not rewrite it inside a disposable runner. Developers can apply fixes locally, inspect `git diff`, rerun the gate, and commit the reviewed result.
If `quality_gate.py` grows platform-specific behavior, keep path construction portable and avoid invoking shell-only syntax from Python. Its Step 6 use of `sys.executable` plus argument lists is safer and more portable than command strings.
## Validate YAML before pushing
Review the exact diff:
```powershell
git diff -- .github\workflows\python-quality.yml
git status --short
```
Check indentation with spaces, especially beneath `jobs`, `steps`, `with`, and the matrix. YAML tabs are invalid. Confirm that `${{ ... }}` expressions remain literal workflow syntax and were not expanded or altered by another template system.
The workflow file name must end in `.yml` or `.yaml` and live directly under `.github/workflows`. A workflow stored elsewhere will not be discovered.
GitHub performs workflow parsing after the commit reaches the repository. A local YAML parser can catch syntax problems but may not understand GitHub expressions or workflow semantics. Treat the Actions run itself as the authoritative integration check.
## Commit and push the reviewable change
Stage only intended files:
```powershell
git add .github\workflows\python-quality.yml
git status --short
git diff --cached
git commit -m "Add Windows Python quality workflow"
git push
```
Do not use `git add .` without reviewing unrelated files. Verify that `.venv`, caches, credentials, editor history, and local paths are not staged. Pushing changes remote state, so use the correct branch and repository according to the team's normal review process.
Open the repository's Actions page or pull request checks. The matrix should create a separately named job for each Python version. Expand logs and confirm the selected interpreter version, clean dependency installation, `pip check`, and all four Step 6 quality surfaces.
## Read matrix results correctly
`fail-fast: false` lets both interpreter jobs finish, preserving evidence when one version fails early. A Python 3.13 failure alongside a 3.14 pass usually signals a declared compatibility issue, dependency marker difference, or tool support boundary—not a reason to delete the failing matrix entry silently.
`timeout-minutes: 15` bounds a hung beginner project job. Adjust only from measured normal runtime. A timeout is not equivalent to a test failure; inspect the last active command, network/install behavior, deadlocks, or accidentally collected paths.
Concurrency cancels an obsolete run when a newer commit updates the same workflow/ref. The newest commit becomes the relevant evidence. Cancellation does not mean green or red and should not be used to hide the current run.
## Prove the gate can fail
A workflow that has only ever passed may be skipped, mis-scoped, or unable to propagate errors. On a temporary review branch, make one small deliberate failing change—for example change an expected calculator result—then push and confirm both relevant jobs report failure at the test/gate step.
Restore the test immediately, review the diff, push again, and require a clean pass. Do not make the experiment on the protected default branch, do not weaken assertions, and do not merge the broken commit.
This proves the event fired, the tests were collected, `quality_gate.py` propagated nonzero status, and GitHub displayed the failure. Preserve the run URL in the review record if the team requires audit evidence.
## Make the check required
A green workflow is informative but does not automatically block merging. A repository administrator must configure a branch ruleset or branch protection for the default branch and require the intended status checks.
Choose stable check names produced by this workflow and matrix. Revisit rules after renaming the workflow, job, or matrix because a stale required name can block every merge or leave the intended gate optional.
Require branches to be up to date only if the team's merge-risk and queue strategy justify the extra reruns. Do not bypass required checks casually. Emergency bypass authority, if any, should be narrow and audited.
Ruleset configuration changes repository governance and may require administrator approval. The workflow author should verify enforcement with a pull request, not assume that committing YAML changed merge policy.
## Diagnose common failures
**The workflow does not appear.** Confirm it was pushed, lives under `.github/workflows`, has valid YAML, and its event/branch filters match the change. Inspect repository Actions policy if workflows are disabled or restricted.
**`setup-python` cannot find 3.14.** Confirm the version string is quoted, the runner is `windows-latest`, and the requested release exists for the chosen architecture. Do not enable prereleases unless the project deliberately supports them.
**The cache step reports a miss.** Continue; first runs and dependency changes commonly miss. The install must still succeed. Never make correctness depend on a hit.
**A dependency file is not found.** Compare repository-relative names and case. Windows is case-insensitive in many contexts, but repository paths and other runners expose case mistakes; fix the canonical filename.
**Install fails only on one Python version.** Inspect package version constraints, environment markers, wheel availability, and source-build output. Do not use `--no-deps`, ignore the failed version, or globally loosen constraints without compatibility analysis.
**Mypy, Ruff, or pytest is missing.** Verify development declarations were committed and installed. The runner correctly exposes machine-only packages that were never declared.
**CI finds different tests than VS Code.** Compare repository root, `pyproject.toml`, test paths, working directory, and collected-test output. Editor discovery is not the CI authority.
**`pythonw.exe` appears.** The workflow must resolve the console `python.exe` supplied by setup-python. Search workflow/scripts for explicit `pythonw`, GUI launchers, or hard-coded user paths.
**The gate passes although a test is broken.** Inspect `quality_gate.py` return-code handling and pytest collection. Run `python -m pytest --collect-only -q`; prove the deliberate failure again.
**Pull-request jobs request secrets.** Remove that dependency from the untrusted test path or design a separate privileged workflow that never executes untrusted code. Do not switch events as a shortcut.
**A required check is stuck expected.** Compare the branch rule's exact check name with the latest pull request, event filters, path filters, and workflow/job renames.
## What not to do in Step 7
- Do not paste the client's absolute Python path into workflow YAML.
- Do not split `python -c` from its quoted code with a PowerShell backtick.
- Do not commit or cache a developer `.venv`.
- Do not use `pull_request_target` to execute untrusted pull-request code.
- Do not grant write permissions to a read-only quality workflow.
- Do not expose secrets or dump the entire environment/context to logs.
- Do not use mutating formatter/fixer commands as a passing CI gate.
- Do not use unquoted, floating Python selectors for a declared support matrix.
- Do not remove a failing supported version merely to obtain green checks.
- Do not assume a workflow is merge-blocking until a ruleset requires it.
- Do not bypass dependency declarations with global or preinstalled packages.
- Do not trust cache hits as proof of reproducibility.
- Do not run untrusted contributions on a persistent workstation runner.
| Step 7 gate | Pass condition | If it fails |
|---|---|---|
| local baseline | Step 6 gate exits zero | repair locally first |
| workflow discovery | intended events start runs | fix path/YAML/filter |
| permissions | contents read only | remove excess access |
| Python matrix | every supported version runs | fix contract/compatibility |
| clean install | declarations install and pass check | repair dependency source |
| cache behavior | hit or miss remains correct | decouple state from cache |
| quality parity | same project gate runs | remove duplicated policy |
| negative proof | deliberate defect makes red | repair collection/exit handling |
| governance | current green check required | configure/verify ruleset |
## Step 7 completion gate
Step 7 is complete only when:
1. `.github/workflows/python-quality.yml` is tracked and valid.
2. Pull requests, default-branch pushes, and manual dispatches have the intended trigger behavior.
3. The automatic token has only `contents: read` for this workflow.
4. Clean Windows jobs select every documented supported Python version.
5. Both dependency declarations install without relying on a copied environment.
6. A cache miss and a cache hit both proceed through install, `pip check`, and the quality gate.
7. CI invokes the same `quality_gate.py` used locally.
8. A deliberate temporary defect causes a nonzero failed run, and its restoration passes.
9. The repository ruleset requires the current quality checks before merge.
10. No secrets, private paths, virtual environments, or generated caches were committed or logged.
Run the final local evidence before the final push:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
Then inspect the latest GitHub Actions run and the pull request's merge box. Both Python matrix jobs must be green, and the repository must show that the checks are required—not merely present.
The next setup step can add coverage policy and artifacts deliberately: define which coverage risks matter, produce a machine-readable report, retain only non-sensitive evidence, and set a justified threshold without confusing line percentage with test quality.
**Windows Python Setup Step 7 succeeds when every supported Python version rebuilds on a clean Windows runner, executes the exact local non-mutating gate with least privilege, visibly fails a controlled defect, returns green after restoration, and is required before merge.**
windows python step 70, python setup step 70 windows
**Windows Python Setup Step 70 is Supply-chain controls: produce a reviewed dependency provenance policy that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **resolved packages, origins, hashes, and licenses are reviewable**. The main failure to design against is **trusting names and latest versions without provenance**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Supply-chain controls behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 70 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 70 boundary
The deliverable is **reviewed dependency provenance policy**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Supply-chain controls. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Supply-chain controls"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Supply-chain controls policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 70 exercise command is:
```powershell
python -m pip inspect
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 70 threat review must directly address **trusting names and latest versions without provenance**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Supply-chain controls. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 70
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 70 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | reviewed dependency provenance policy exists in reviewed source | machine-only hidden state |
| normal behavior | resolved packages, origins, hashes, and licenses are reviewable | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses trusting names and latest versions without provenance | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 70 completion gate
Step 70 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pip inspect
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 71 continues with **Software bill of materials**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 70 succeeds when resolved packages, origins, hashes, and licenses are reviewable, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 71, python setup step 71 windows
**Windows Python Setup Step 71 is Software bill of materials: produce a machine-readable dependency inventory that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **the release has a retained, versioned component inventory**. The main failure to design against is **claiming an SBOM proves absence of vulnerabilities**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Software bill of materials behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 71 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 71 boundary
The deliverable is **machine-readable dependency inventory**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Software bill of materials. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Software bill of materials"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Software bill of materials policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 71 exercise command is:
```powershell
python -m pip list --format=json
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 71 threat review must directly address **claiming an SBOM proves absence of vulnerabilities**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Software bill of materials. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 71
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 71 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | machine-readable dependency inventory exists in reviewed source | machine-only hidden state |
| normal behavior | the release has a retained, versioned component inventory | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses claiming an SBOM proves absence of vulnerabilities | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 71 completion gate
Step 71 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pip list --format=json
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 72 continues with **Vulnerability scanning**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 71 succeeds when the release has a retained, versioned component inventory, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 72, python setup step 72 windows
**Windows Python Setup Step 72 is Vulnerability scanning: produce a triaged dependency vulnerability report that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **findings have ownership, reachability review, and remediation decisions**. The main failure to design against is **blind upgrades or ignored scanner noise**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Vulnerability scanning behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 72 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 72 boundary
The deliverable is **triaged dependency vulnerability report**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Vulnerability scanning. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Vulnerability scanning"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Vulnerability scanning policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 72 exercise command is:
```powershell
python -m pip_audit
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 72 threat review must directly address **blind upgrades or ignored scanner noise**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Vulnerability scanning. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 72
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 72 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | triaged dependency vulnerability report exists in reviewed source | machine-only hidden state |
| normal behavior | findings have ownership, reachability review, and remediation decisions | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses blind upgrades or ignored scanner noise | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 72 completion gate
Step 72 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pip_audit
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 73 continues with **Artifact signing**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 72 succeeds when findings have ownership, reachability review, and remediation decisions, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 73, python setup step 73 windows
**Windows Python Setup Step 73 is Artifact signing: produce a verified release-artifact signature that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **consumer verification rejects a modified artifact**. The main failure to design against is **signing an artifact without protecting identity and key lifecycle**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Artifact signing behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 73 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 73 boundary
The deliverable is **verified release-artifact signature**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Artifact signing. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Artifact signing"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Artifact signing policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 73 exercise command is:
```powershell
Get-FileHash .\dist\artifact.whl -Algorithm SHA256
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 73 threat review must directly address **signing an artifact without protecting identity and key lifecycle**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Artifact signing. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 73
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 73 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | verified release-artifact signature exists in reviewed source | machine-only hidden state |
| normal behavior | consumer verification rejects a modified artifact | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses signing an artifact without protecting identity and key lifecycle | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 73 completion gate
Step 73 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
Get-FileHash .\dist\artifact.whl -Algorithm SHA256
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 74 continues with **Windows containers**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 73 succeeds when consumer verification rejects a modified artifact, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 74, python setup step 74 windows
**Windows Python Setup Step 74 is Windows containers: produce a reproducible Windows container build boundary that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **the image builds from pinned inputs and runs as a non-admin user**. The main failure to design against is **assuming Linux and Windows container behavior is identical**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Windows containers behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 74 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 74 boundary
The deliverable is **reproducible Windows container build boundary**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Windows containers. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Windows containers"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Windows containers policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 74 exercise command is:
```powershell
docker build -t python-app:step74 .
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 74 threat review must directly address **assuming Linux and Windows container behavior is identical**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Windows containers. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 74
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 74 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | reproducible Windows container build boundary exists in reviewed source | machine-only hidden state |
| normal behavior | the image builds from pinned inputs and runs as a non-admin user | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses assuming Linux and Windows container behavior is identical | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 74 completion gate
Step 74 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
docker build -t python-app:step74 .
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 75 continues with **WSL interoperability**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 74 succeeds when the image builds from pinned inputs and runs as a non-admin user, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 75, python setup step 75 windows
**Windows Python Setup Step 75 is WSL interoperability: produce a explicit Windows-versus-WSL execution boundary that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **files, interpreters, ports, and line endings stay in the intended environment**. The main failure to design against is **mixing Windows virtual environments with Linux Python**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | WSL interoperability behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 75 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 75 boundary
The deliverable is **explicit Windows-versus-WSL execution boundary**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns WSL interoperability. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "WSL interoperability"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the WSL interoperability policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 75 exercise command is:
```powershell
wsl.exe python3 -c "import sys; print(sys.executable)"
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 75 threat review must directly address **mixing Windows virtual environments with Linux Python**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to WSL interoperability. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 75
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 75 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | explicit Windows-versus-WSL execution boundary exists in reviewed source | machine-only hidden state |
| normal behavior | files, interpreters, ports, and line endings stay in the intended environment | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses mixing Windows virtual environments with Linux Python | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 75 completion gate
Step 75 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
wsl.exe python3 -c "import sys; print(sys.executable)"
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 76 continues with **Development containers**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 75 succeeds when files, interpreters, ports, and line endings stay in the intended environment, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 76, python setup step 76 windows
**Windows Python Setup Step 76 is Development containers: produce a reviewed disposable development environment that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **a new developer can rebuild tools without host-specific state**. The main failure to design against is **mounting secrets or the Docker socket unnecessarily**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Development containers behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 76 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 76 boundary
The deliverable is **reviewed disposable development environment**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Development containers. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Development containers"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Development containers policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 76 exercise command is:
```powershell
docker compose config
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 76 threat review must directly address **mounting secrets or the Docker socket unnecessarily**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Development containers. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 76
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 76 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | reviewed disposable development environment exists in reviewed source | machine-only hidden state |
| normal behavior | a new developer can rebuild tools without host-specific state | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses mounting secrets or the Docker socket unnecessarily | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 76 completion gate
Step 76 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
docker compose config
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 77 continues with **Cloud deployment foundations**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 76 succeeds when a new developer can rebuild tools without host-specific state, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 77, python setup step 77 windows
**Windows Python Setup Step 77 is Cloud deployment foundations: produce a environment-neutral deployment contract that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **startup, configuration, health, and shutdown work without local assumptions**. The main failure to design against is **deploying before defining ownership and rollback**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Cloud deployment foundations behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 77 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 77 boundary
The deliverable is **environment-neutral deployment contract**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Cloud deployment foundations. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Cloud deployment foundations"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Cloud deployment foundations policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 77 exercise command is:
```powershell
python -m pytest tests\test_deploy_config.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 77 threat review must directly address **deploying before defining ownership and rollback**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Cloud deployment foundations. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 77
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 77 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | environment-neutral deployment contract exists in reviewed source | machine-only hidden state |
| normal behavior | startup, configuration, health, and shutdown work without local assumptions | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses deploying before defining ownership and rollback | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 77 completion gate
Step 77 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_deploy_config.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 78 continues with **Environment parity**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 77 succeeds when startup, configuration, health, and shutdown work without local assumptions, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 78, python setup step 78 windows
**Windows Python Setup Step 78 is Environment parity: produce a documented development-staging-production differences that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **approved differences are explicit and secrets remain redacted**. The main failure to design against is **calling unequal environments identical**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Environment parity behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 78 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 78 boundary
The deliverable is **documented development-staging-production differences**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Environment parity. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Environment parity"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Environment parity policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 78 exercise command is:
```powershell
python -m app.diagnostics
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 78 threat review must directly address **calling unequal environments identical**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Environment parity. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 78
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 78 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | documented development-staging-production differences exists in reviewed source | machine-only hidden state |
| normal behavior | approved differences are explicit and secrets remain redacted | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses calling unequal environments identical | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 78 completion gate
Step 78 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m app.diagnostics
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 79 continues with **Deployment automation**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 78 succeeds when approved differences are explicit and secrets remain redacted, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 79, python setup step 79 windows
**Windows Python Setup Step 79 is Deployment automation: produce a approval-gated deployment workflow that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **only a verified artifact advances with an auditable result**. The main failure to design against is **rebuilding different bits during deployment**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Deployment automation behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 79 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 79 boundary
The deliverable is **approval-gated deployment workflow**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Deployment automation. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Deployment automation"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Deployment automation policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 79 exercise command is:
```powershell
python -m pytest tests\test_release_smoke.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 79 threat review must directly address **rebuilding different bits during deployment**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Deployment automation. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 79
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 79 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | approval-gated deployment workflow exists in reviewed source | machine-only hidden state |
| normal behavior | only a verified artifact advances with an auditable result | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses rebuilding different bits during deployment | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 79 completion gate
Step 79 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_release_smoke.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 80 continues with **Rollback design**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 79 succeeds when only a verified artifact advances with an auditable result, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 8, python setup step 8 windows
**Windows Python Setup Step 8 is Coverage measurement: produce a reviewed HTML and XML coverage reports that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **the intended tests pass and risk-relevant missing lines are reviewed**. The main failure to design against is **treating a percentage as proof of test quality**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Coverage measurement behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 8 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 8 boundary
The deliverable is **reviewed HTML and XML coverage reports**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Coverage measurement. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Coverage measurement"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Coverage measurement policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 8 exercise command is:
```powershell
python -m pytest --cov=. --cov-report=term-missing --cov-report=xml
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 8 threat review must directly address **treating a percentage as proof of test quality**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Coverage measurement. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 8
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 8 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | reviewed HTML and XML coverage reports exists in reviewed source | machine-only hidden state |
| normal behavior | the intended tests pass and risk-relevant missing lines are reviewed | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses treating a percentage as proof of test quality | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 8 completion gate
Step 8 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest --cov=. --cov-report=term-missing --cov-report=xml
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 9 continues with **CI artifacts and retention**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 8 succeeds when the intended tests pass and risk-relevant missing lines are reviewed, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 80, python setup step 80 windows
**Windows Python Setup Step 80 is Rollback design: produce a rehearsed application rollback runbook that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **previous artifact and compatible data path restore within objective**. The main failure to design against is **assuming code rollback reverses database changes**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Rollback design behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 80 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 80 boundary
The deliverable is **rehearsed application rollback runbook**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Rollback design. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Rollback design"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Rollback design policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 80 exercise command is:
```powershell
python -m app --version
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 80 threat review must directly address **assuming code rollback reverses database changes**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Rollback design. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 80
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 80 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | rehearsed application rollback runbook exists in reviewed source | machine-only hidden state |
| normal behavior | previous artifact and compatible data path restore within objective | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses assuming code rollback reverses database changes | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 80 completion gate
Step 80 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m app --version
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 81 continues with **Backup design**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 80 succeeds when previous artifact and compatible data path restore within objective, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 81, python setup step 81 windows
**Windows Python Setup Step 81 is Backup design: produce a measured backup and retention policy that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **scope, encryption, retention, and failure alerts are verified**. The main failure to design against is **calling untested file copies backups**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Backup design behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 81 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 81 boundary
The deliverable is **measured backup and retention policy**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Backup design. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Backup design"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Backup design policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 81 exercise command is:
```powershell
python -m app.backup --dry-run
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 81 threat review must directly address **calling untested file copies backups**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Backup design. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 81
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 81 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | measured backup and retention policy exists in reviewed source | machine-only hidden state |
| normal behavior | scope, encryption, retention, and failure alerts are verified | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses calling untested file copies backups | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 81 completion gate
Step 81 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m app.backup --dry-run
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 82 continues with **Restore testing**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 81 succeeds when scope, encryption, retention, and failure alerts are verified, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 82, python setup step 82 windows
**Windows Python Setup Step 82 is Restore testing: produce a isolated restore rehearsal that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **restored data passes integrity and application smoke checks**. The main failure to design against is **discovering unusable backups during an incident**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Restore testing behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 82 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 82 boundary
The deliverable is **isolated restore rehearsal**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Restore testing. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Restore testing"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Restore testing policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 82 exercise command is:
```powershell
python -m app.restore --verify-only
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 82 threat review must directly address **discovering unusable backups during an incident**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Restore testing. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 82
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 82 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | isolated restore rehearsal exists in reviewed source | machine-only hidden state |
| normal behavior | restored data passes integrity and application smoke checks | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses discovering unusable backups during an incident | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 82 completion gate
Step 82 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m app.restore --verify-only
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 83 continues with **Message queues**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 82 succeeds when restored data passes integrity and application smoke checks, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 83, python setup step 83 windows
**Windows Python Setup Step 83 is Message queues: produce a idempotent queued-work contract that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **acknowledgment, retry, poison-message, and shutdown paths pass**. The main failure to design against is **duplicate effects and infinite redelivery**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Message queues behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 83 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 83 boundary
The deliverable is **idempotent queued-work contract**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Message queues. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Message queues"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Message queues policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 83 exercise command is:
```powershell
python -m pytest tests\test_queue_worker.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 83 threat review must directly address **duplicate effects and infinite redelivery**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Message queues. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 83
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 83 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | idempotent queued-work contract exists in reviewed source | machine-only hidden state |
| normal behavior | acknowledgment, retry, poison-message, and shutdown paths pass | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses duplicate effects and infinite redelivery | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 83 completion gate
Step 83 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_queue_worker.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 84 continues with **Background jobs**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 83 succeeds when acknowledgment, retry, poison-message, and shutdown paths pass, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 84, python setup step 84 windows
**Windows Python Setup Step 84 is Background jobs: produce a observable scheduled worker that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **leases, retries, timeouts, and concurrency limits are deterministic**. The main failure to design against is **overlapping jobs and silent partial completion**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Background jobs behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 84 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 84 boundary
The deliverable is **observable scheduled worker**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Background jobs. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Background jobs"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Background jobs policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 84 exercise command is:
```powershell
python -m pytest tests\test_jobs.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 84 threat review must directly address **overlapping jobs and silent partial completion**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Background jobs. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 84
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 84 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | observable scheduled worker exists in reviewed source | machine-only hidden state |
| normal behavior | leases, retries, timeouts, and concurrency limits are deterministic | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses overlapping jobs and silent partial completion | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 84 completion gate
Step 84 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_jobs.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 85 continues with **Application caching**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 84 succeeds when leases, retries, timeouts, and concurrency limits are deterministic, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 85, python setup step 85 windows
**Windows Python Setup Step 85 is Application caching: produce a bounded cache-aside adapter that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **miss, hit, expiry, invalidation, and backend failure pass**. The main failure to design against is **treating cache data as authoritative state**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Application caching behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 85 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 85 boundary
The deliverable is **bounded cache-aside adapter**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Application caching. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Application caching"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Application caching policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 85 exercise command is:
```powershell
python -m pytest tests\test_cache.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 85 threat review must directly address **treating cache data as authoritative state**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Application caching. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 85
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 85 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | bounded cache-aside adapter exists in reviewed source | machine-only hidden state |
| normal behavior | miss, hit, expiry, invalidation, and backend failure pass | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses treating cache data as authoritative state | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 85 completion gate
Step 85 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_cache.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 86 continues with **Concurrency safety**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 85 succeeds when miss, hit, expiry, invalidation, and backend failure pass, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**