DC003: HasExamples

Overview

Property Value
ID DC003
Name HasExamples
Group documentation
Severity NOTE

Description

Checks for an examples/ directory or example code in the package.

Examples are valuable for:

  • Demonstrating real-world usage
  • Onboarding new users quickly
  • Testing integration scenarios
  • Providing copy-paste starting points

What it checks

The check looks for example content in these locations:

  • examples/ directory
  • example/ directory
  • Example scripts in documentation

Additionally checks for example Python files:

  • examples/*.py
  • examples/**/*.py

How to fix

Create an examples/ directory with sample code:

mkdir examples

Basic example structure

examples/
├── README.md           # Overview of examples
├── basic_usage.py      # Simple getting started
├── advanced_usage.py   # Complex scenarios
└── config_example.py   # Configuration examples

Example file template

Create examples/basic_usage.py:

"""Basic usage example for my_package.

This example demonstrates the most common operations.

Run with:
    python examples/basic_usage.py
"""

from my_package import MyClass

def main():
    # Create an instance
    obj = MyClass()

    # Perform basic operations
    result = obj.process("input data")
    print(f"Result: {result}")

if __name__ == "__main__":
    main()

Document examples in README

Reference examples in your README.md:

## Examples

See the [examples/](examples/) directory for complete working examples:

- [basic_usage.py](examples/basic_usage.py) - Getting started
- [advanced_usage.py](examples/advanced_usage.py) - Advanced features

Why NOTE severity?

This check is a NOTE because:

  • Small packages may not need separate examples
  • Docstrings may contain sufficient examples
  • README examples may be adequate

Configuration

Skip this check

[tool.pycmdcheck]
skip = ["DC003"]

CLI

pycmdcheck --skip DC003