python-dev-environment（Python DEV environment 测试）

Python Development Environment Expertise Skill

Purpose: Provides verified, grounded reference data for writing Chapter 14.1 lessons. Every command, version number, and config option below was extracted from official documentation on 2026-02-20.

Usage: Content-implementer subagents MUST reference this skill when writing Ch 14.1 lessons. Never invent commands or config options — use only what is documented here.

1. uv — Package Manager & Project Orchestrator

Version: 0.10.4 (released February 17, 2026) Written in: Rust Maker: Astral (same company as ruff) Source: docs.astral.sh/uv

Installation Commands

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux (curl)
curl -LsSf https://astral.sh/uv/install.sh | sh

# macOS (Homebrew)
brew install uv

# Windows (WinGet)
winget install --id=astral-sh.uv -e

uv init — Project Scaffolding

uv init smartnotes          # Create new project in subdirectory
uv init                     # Initialize in current directory
uv init --lib <name>        # Library project
uv init --package <name>    # Packaged application (src layout)

Files created by uv init smartnotes:

smartnotes/
├── .gitignore
├── .python-version          # Contains: 3.12 (or detected version)
├── README.md
├── main.py
└── pyproject.toml

Default main.py:

def main():
    print("Hello from smartnotes!")

if __name__ == "__main__":
    main()

Default pyproject.toml:

[project]
name = "smartnotes"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []

Additional files created on first uv run or uv sync:

• .venv/ — virtual environment (not version-controlled)
• uv.lock — cross-platform lockfile with exact versions (should be committed)

uv add — Dependency Management

uv add requests                    # Add runtime dependency
uv add 'requests>=2.28,<3'        # With version constraint
uv add --dev pytest                # Add dev dependency
uv add --dev pytest pyright ruff   # Multiple dev deps at once
uv remove requests                 # Remove a dependency

What uv add does (three steps in one):

1. Updates pyproject.toml
2. Updates uv.lock (lockfile)
3. Syncs the .venv environment

Result in pyproject.toml after uv add --dev pytest pyright ruff:

[dependency-groups]
dev = ["pytest>=9.0.2", "pyright>=1.1.408", "ruff>=0.15.2"]

uv run — Execute in Project Environment

uv run main.py                     # Run a Python file
uv run pytest                      # Run an installed tool
uv run python -c "print('hi')"    # Run inline Python

What happens on uv run:

1. Verifies uv.lock is up-to-date with pyproject.toml
2. Verifies .venv is up-to-date with uv.lock
3. Installs/syncs missing dependencies automatically
4. Runs the command inside the project's virtual environment

No manual venv activation required. Students never need source.venv/bin/activate.

Why uv Over pip

Axiom Callback: uv = Axiom I (Shell as Orchestrator). One command replaces an entire ecosystem.

2. pyright — Static Type Checker

Version: 1.1.408 (released January 8, 2026) Written in: TypeScript (runs via Node.js; pip wrapper handles this transparently) Maker: Microsoft Source: github.com/microsoft/pyright

Installation

uv add --dev pyright               # Recommended via uv

Configuration in pyproject.toml

[tool.pyright]
include = ["src"]
exclude = ["**/__pycache__"]
typeCheckingMode = "strict"
pythonVersion = "3.12"

Also supports pyrightconfig.json (takes precedence if both exist):

{
  "include": ["src"],
  "typeCheckingMode": "strict",
  "pythonVersion": "3.12"
}

Type Checking Modes

Running Pyright

uv run pyright                     # Check entire project
uv run pyright src/main.py         # Check specific file

Clean output:

0 errors, 0 warnings, 0 informations

Error output:

/path/to/file.py:10:5 - error: Type of parameter "name" is unknown (reportUnknownParameterType)
1 error, 0 warnings, 0 informations

What Strict Mode Catches (28 Additional Rules)

Strict mode enables 28 rules that are "none" in standard but "error" in strict:

Missing annotations:

• reportMissingParameterType — parameters without type hints
• reportMissingTypeArgument — generic classes without type args
• reportUnknownParameterType — parameter type resolves to Unknown
• reportUnknownVariableType — variable type resolves to Unknown
• reportUnknownArgumentType — argument type resolves to Unknown
• reportUnknownMemberType — member access resolves to Unknown
• reportUnknownLambdaType — lambda parameters Unknown

Code quality:

• reportUnusedImport — imported symbols not referenced
• reportUnusedVariable — local variables not referenced
• reportUnusedFunction — functions not referenced
• reportUnusedClass — classes not referenced
• reportDuplicateImport — duplicate imports
• reportPrivateUsage — accessing private members
• reportConstantRedefinition — redefining Final variables
• reportDeprecated — deprecated features

Type safety:

• reportUntypedBaseClass — base class without types
• reportUntypedFunctionDecorator — untyped decorators
• reportUntypedClassDecorator — untyped class decorators
• reportUntypedNamedTuple — NamedTuple without types
• reportMatchNotExhaustive — incomplete match
• reportUnnecessaryCast — unnecessary casts
• reportUnnecessaryComparison — always-true/false comparisons
• reportUnnecessaryContains — unnecessary in checks
• reportUnnecessaryIsInstance — unnecessary isinstance
• reportIncompleteStub, reportInconsistentConstructor, reportInvalidStubStatement, reportTypeCommentUsage

Before/After Example (for Ch 14.1)

# BEFORE: Passes standard, FAILS strict
def greet(name):
    return f"Hello, {name}"

# AFTER: Passes strict
def greet(name: str) -> str:
    return f"Hello, {name}"

Axiom Callback: pyright = Axiom V (Types Are Guardrails). The compiler catches bugs before runtime.

3. ruff — Linter & Formatter

Version: 0.15.2 (released February 19, 2026) Written in: Rust Maker: Astral (same company as uv) Source: docs.astral.sh/ruff

Installation

uv add --dev ruff                  # Add as dev dependency

Running Ruff

# Linting
uv run ruff check .               # Lint all Python files
uv run ruff check --fix .         # Lint and auto-fix

# Formatting
uv run ruff format .              # Format all Python files
uv run ruff format --check .      # Check without modifying

Configuration in pyproject.toml

[tool.ruff]
line-length = 88
target-version = "py312"

[tool.ruff.lint]
select = [
    "E",    # pycodestyle errors
    "W",    # pycodestyle warnings
    "F",    # Pyflakes (unused imports, undefined names)
    "I",    # isort (import sorting)
    "UP",   # pyupgrade (modernize syntax)
    "B",    # flake8-bugbear (common bugs)
    "SIM",  # flake8-simplify (simplifiable code)
]

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

Key Rule Categories (for Teaching)

Default enabled rules: E4, E7, E9, and F (minimal safe set). Total rules: 800+ built-in. Suppress inline: # noqa: F841 on a line.

What Ruff Replaces

Ruff is a single binary replacing: Flake8 (+ dozens of plugins), Black, isort, pydocstyle, pyupgrade, autoflake. Speed: 10-100x faster than these tools individually.

Ruff format is a drop-in Black replacement (>99.9% identical formatting).

Axiom Callback: ruff = Axiom IX (Verification is a Pipeline). Automated quality checks in your CI.

4. pytest — Testing Framework

Version: 9.0.2 (released December 6, 2025) Requires: Python >= 3.10 Source: docs.pytest.org

Installation

uv add --dev pytest                # Add as dev dependency

Test Discovery Conventions

Minimal Test File

# test_example.py
def func(x):
    return x + 1

def test_answer():
    assert func(3) == 4

Key: pytest uses plain assert — no special assertion methods needed.

Running Tests

uv run pytest                      # Run all discovered tests
uv run pytest -v                   # Verbose (one line per test)
uv run pytest -q                   # Quiet (minimal output)
uv run pytest test_example.py      # Run specific file
uv run pytest -k "test_answer"     # Run matching keyword

Output Format

Default (dots):

test_example.py .                                                [100%]
========================== 1 passed in 0.12s ===========================

Verbose (-v):

test_example.py::test_answer PASSED                              [100%]
========================== 1 passed in 0.12s ===========================

Output characters:

Configuration in pyproject.toml

[tool.pytest.ini_options]
addopts = "-ra -q"
testpaths = ["tests"]

Axiom Callback: pytest = Axiom VII (Tests Are the Specification). Tests define what "correct" means.

5. Git — Version Control

Note: Git is not a Python-specific tool and doesn't need version-grounding the same way. The chapter references Git as the fifth discipline tool.

Key Git Commands for SmartNotes

git init                           # Initialize repo (uv init creates .gitignore)
git add .                          # Stage all changes
git commit -m "message"            # Commit with message
git log --oneline                  # View history
git diff                           # See uncommitted changes

Axiom Callback: Git = Axiom VIII (Version Control is Memory). Every change tracked, reversible.

6. The Unified pyproject.toml (SmartNotes After Full Setup)

After running all setup commands, the SmartNotes pyproject.toml looks like:

[project]
name = "smartnotes"
version = "0.1.0"
description = "A personal note-taking assistant"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

[dependency-groups]
dev = ["pytest>=9.0.2", "pyright>=1.1.408", "ruff>=0.15.2"]

[tool.pyright]
typeCheckingMode = "strict"
pythonVersion = "3.12"

[tool.ruff]
line-length = 88
target-version = "py312"

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM"]

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

[tool.pytest.ini_options]
addopts = "-ra -q"
testpaths = ["tests"]

Teaching point: One file configures ALL four tools. This is the power of pyproject.toml as the single source of truth for a Python project.

7. Platform-Specific Notes

Windows

• uv install: PowerShell command (see Section 1)
• Paths use \ but uv handles this transparently
• .venv\Scripts\activate (if manual activation needed, but uv run avoids this)

macOS

• uv install: curl or Homebrew
• .venv/bin/activate (if manual activation needed)

Linux

• uv install: curl
• Same as macOS for venv paths

Key teaching point: uv run works identically on all platforms. Students never need to know activation differences.

8. Chapter 14 Tone Reference (Condensed)

Characters

• James: Junior dev, 3 weeks into first job, e-commerce platform team. Learner surrogate. Makes understandable mistakes. Never mocked. Growth narrative.
• Emma: Senior engineer, 4 years at company. Mentor. Teaches through showing, not lecturing. Delivers quotable one-liners. Calm, slightly dry. Declarative sentences.

Lesson Opening Pattern

1. Bridge sentence from previous lesson
2. James hits a crisis (specific time, specific number, visceral detail)
3. He discovers tools/code are inadequate (shown as code block)
4. Emma arrives, delivers one-line diagnosis
5. Emma fixes it

Lesson Section Flow

1. Title → Narrative opening (4-6 paragraphs)
2. "The Problem Without This Tool" → pain point
3. "The Tool Defined" → blockquote + table + image
4. "From Axiom to Practice" → connects to Ch 14 axiom
5. "Practical Application" → code examples, configs
6. "Anti-Patterns" → narrative + table (3-4 columns)
7. "Try With AI" → exactly 3 prompts with **What you're learning:**
8. "Key Takeaways" → numbered list, 4-6 items
9. "Looking Ahead" → bridge to next lesson

YAML Frontmatter Template

---
sidebar_position: N
title: "Lesson Title"
description: "One sentence"
keywords: ["keyword1", "keyword2"]
chapter: 14.1
lesson: N
duration_minutes: 20-25

skills:
  - name: "Skill Name"
    proficiency_level: "A2|B1"
    category: "Conceptual|Technical|Applied"
    bloom_level: "Understand|Apply"
    digcomp_area: "Computational Thinking|Problem Solving"
    measurable_at_this_level: "Student can..."

learning_objectives:
  - objective: "Full sentence"
    proficiency_level: "A2|B1"
    bloom_level: "Apply|Understand"
    assessment_method: "Full sentence"

cognitive_load:
  new_concepts: 5-7
  assessment: "Justification sentence"

differentiation:
  extension_for_advanced: "Advanced activity"
  remedial_for_struggling: "Simplified approach"
---

Code Style

• Use ``` `python static ``` tag for Python blocks
• BAD code first with # BAD: comments, GOOD code follows
• Inline comments explain intent, not syntax
• Never two code blocks back-to-back without prose

Voice

• Third-person narrator for narrative sections
• "You" for instructional sections (Practical Application, Try With AI)
• Declarative, confident. No hedging, no exclamation marks.
• Tables as primary analytical device.

9. Axiom Callbacks (Ch 14.1 → Ch 14 Mapping)

10. Confidence Assessment