DC009: CodeExamplesRun

Overview

Property Value
ID DC009
Name CodeExamplesRun
Group documentation
Severity WARNING

Description

Verifies that Python code examples in README.md have valid syntax.

Code examples in documentation that contain syntax errors frustrate users trying to get started with your package. This check extracts Python code blocks from your README and verifies they are syntactically valid.

What it checks

The check:

  1. Extracts all ```python code blocks from README.md
  2. Compiles each block to verify Python syntax
  3. Reports any syntax errors with line numbers

Results

  • PASSED: All code examples have valid Python syntax
  • FAILED: One or more code examples have syntax errors
  • NOT_APPLICABLE: No README.md found, or no Python code blocks in README

Skipping code blocks

Code blocks with skip annotations are ignored:

```python {.no-run}
# This code block will be skipped
incomplete_code(

Supported skip patterns:

- `{.no-run}`
- `{.skip}`
- `{.ignore}`
- `{.noexec}`

## How to fix

### Fix syntax errors

Check the error message for the line number within the code block:

README.md:42: SyntaxError: unexpected EOF while parsing (line 3 in block)


This means:

- Line 42 of README.md is where the code block starts
- Line 3 within that code block has the syntax error

Common syntax errors:

```python
# Missing closing parenthesis
result = my_function(arg1, arg2

# Missing colon
def my_function()
    pass

# Incomplete string
message = "Hello

Verify your examples work

After fixing syntax, test that examples actually run:

# Extract and run code blocks manually
python -c "
from my_package import something
result = something()
print(result)
"

Mark incomplete examples

If you have intentionally incomplete code (showing patterns, not runnable code), mark it:

```python {.no-run}
# This shows the pattern but isn't complete
class MyClass:
    def method(self):
        ...  # implementation here

Or use a different language tag:

```markdown

Pseudo-code, not actual Python

do_thing() -> result result.process()

Use doctest-style examples

Consider using doctest format for examples that should be verified:

"""My Package

Examples:
    >>> from my_package import greet
    >>> greet("World")
    'Hello, World!'
"""

Then test with:

python -m doctest README.md

Code block extraction

The check extracts code from fenced blocks:

This is extracted:

```python
print("hello")

This is also extracted:

print("world")

This is NOT extracted (not Python):

pip install my-package

## Configuration

### Skip this check

```toml
[tool.pycmdcheck]
skip = ["DC009"]

CLI

pycmdcheck --skip DC009

Why WARNING severity?

This check is a WARNING because:

  • Syntax errors in documentation directly impact user experience
  • Users copy-paste examples expecting them to work
  • Broken examples suggest the package may not be well-maintained
  • Unlike typos, syntax errors prevent code from running at all

Best practices for code examples

Keep examples simple and complete

# Good - complete and runnable
from my_package import process

result = process("input data")
print(result)
# Bad - missing imports, won't run
result = process("input data")  # NameError: process not defined

Show expected output

from my_package import calculate

result = calculate(5, 3)
print(result)  # Output: 8

Test examples in CI

Add a step to verify README examples:

- name: Test README examples
  run: |
    # Extract and test code blocks
    python scripts/test_readme_examples.py

References