Python Samples
File Structure
Every sample file follows this order:
-
PEP 723 inline script metadata (if external dependencies needed)
-
Copyright header: # Copyright (c) Microsoft. All rights reserved.
-
Required imports
-
Module docstring: """This sample demonstrates..."""
-
Helper functions
-
Main function(s) demonstrating functionality
-
Entry point: if name == "main": asyncio.run(main())
External Dependencies
Use PEP 723 inline script metadata for external packages not in the dev environment:
/// script
requires-python = ">=3.10"
dependencies = [
"some-external-package",
]
///
Run with: uv run samples/path/to/script.py
Copyright (c) Microsoft. All rights reserved.
Do not add sample-only dependencies to the root pyproject.toml dev group.
Syntax Checking
Check samples for syntax errors and missing imports
uv run poe samples-syntax
Lint samples
uv run poe samples-lint
Documentation
Samples should be over-documented:
-
Include a README.md in each set of samples
-
Add a summary docstring under imports explaining the purpose and key components
-
Mark code sections with numbered comments:
1. Create the client instance.
...
2. Create the agent with the client.
...
- Include expected output at the end of the file: """ Sample output: User:> Why is the sky blue? Assistant:> The sky is blue due to Rayleigh scattering... """
Guidelines
-
Incremental complexity — start simple, build up (step1, step2, ...)
-
Getting started naming: step<number>_<name>.py
-
When modifying samples, update associated README files