From 93a00fb3ae9d13ebd78086b7208f576d5172a4e7 Mon Sep 17 00:00:00 2001 From: Davshiv20 Date: Thu, 16 Oct 2025 11:34:40 +0530 Subject: [PATCH 1/3] Add comprehensive docstring to Example class - Add detailed class-level docstring following Google Python style guide - Include comprehensive usage examples showing various initialization patterns - Document key features: dictionary-like access, input/output separation, serialization - Cover all major use cases: basic usage, dictionary initialization, copying, input/output handling - Provide practical examples for common operations like iteration, key checking, and field access This improves DSPy's docstring coverage and makes the Example class more accessible to users. --- dspy/primitives/example.py | 89 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/dspy/primitives/example.py b/dspy/primitives/example.py index abbc381f74..5500eed5b6 100644 --- a/dspy/primitives/example.py +++ b/dspy/primitives/example.py @@ -1,4 +1,93 @@ class Example: + """A flexible data container for DSPy examples and training data. + + The Example class provides a dictionary-like interface for storing and manipulating + structured data used throughout DSPy. It supports initialization from various sources + and provides convenient methods for handling input/output separation, which is crucial + for DSPy's training and evaluation workflows. + + Key features: + - Dictionary-like access patterns (item access, iteration, etc.) + - Flexible initialization from dictionaries, other Examples, or keyword arguments + - Input/output field separation for training data + - Serialization support for saving/loading examples + - Immutable operations that return new Example instances + + Args: + base: Optional base data source. Can be: + - Another Example instance (copies its data) + - A dictionary (copies its key-value pairs) + - None (creates empty Example) + **kwargs: Additional key-value pairs to store in the Example + + Examples: + Basic usage with keyword arguments: + + ```python + import dspy + + # Create an example with input and output fields + example = dspy.Example( + question="What is the capital of France?", + answer="Paris" + ) + print(example.question) # "What is the capital of France?" + print(example.answer) # "Paris" + ``` + + Initialize from a dictionary: + + ```python + data = {"question": "What is 2+2?", "answer": "4"} + example = dspy.Example(data) + print(example["question"]) # "What is 2+2?" + ``` + + Copy from another Example: + + ```python + original = dspy.Example(question="Hello", answer="World") + copy = dspy.Example(original) + print(copy.question) # "Hello" + ``` + + Working with input/output separation: + + ```python + # Mark which fields are inputs for training + example = dspy.Example( + question="What is the weather?", + answer="It's sunny" + ).with_inputs("question") + + # Get only input fields + inputs = example.inputs() + print(inputs.question) # "What is the weather?" + + # Get only output fields (labels) + labels = example.labels() + print(labels.answer) # "It's sunny" + ``` + + Dictionary-like operations: + + ```python + example = dspy.Example(name="Alice", age=30) + + # Check if key exists + if "name" in example: + print("Name field exists") + + # Iterate over items + for key, value in example.items(): + print(f"{key}: {value}") + + # Get with default value + city = example.get("city", "Unknown") + print(city) # "Unknown" + ``` + """ + def __init__(self, base=None, **kwargs): # Internal storage and other attributes self._store = {} From 8b8e2028ee50d811eef29e57482699d12f3435f4 Mon Sep 17 00:00:00 2001 From: Davshiv20 Date: Fri, 17 Oct 2025 12:05:32 +0530 Subject: [PATCH 2/3] Fixes made according to the comments and suggestions --- dspy/primitives/example.py | 28 ++++++++++++---------------- 1 file changed, 12 insertions(+), 16 deletions(-) diff --git a/dspy/primitives/example.py b/dspy/primitives/example.py index 5500eed5b6..f3d33ed18d 100644 --- a/dspy/primitives/example.py +++ b/dspy/primitives/example.py @@ -1,10 +1,7 @@ class Example: """A flexible data container for DSPy examples and training data. - The Example class provides a dictionary-like interface for storing and manipulating - structured data used throughout DSPy. It supports initialization from various sources - and provides convenient methods for handling input/output separation, which is crucial - for DSPy's training and evaluation workflows. + The Example class is the standard data format used in DSPy evaluation and optimization. Key features: - Dictionary-like access patterns (item access, iteration, etc.) @@ -13,13 +10,6 @@ class Example: - Serialization support for saving/loading examples - Immutable operations that return new Example instances - Args: - base: Optional base data source. Can be: - - Another Example instance (copies its data) - - A dictionary (copies its key-value pairs) - - None (creates empty Example) - **kwargs: Additional key-value pairs to store in the Example - Examples: Basic usage with keyword arguments: @@ -29,7 +19,7 @@ class Example: # Create an example with input and output fields example = dspy.Example( question="What is the capital of France?", - answer="Paris" + answer="Paris", ) print(example.question) # "What is the capital of France?" print(example.answer) # "Paris" @@ -57,7 +47,7 @@ class Example: # Mark which fields are inputs for training example = dspy.Example( question="What is the weather?", - answer="It's sunny" + answer="It's sunny", ).with_inputs("question") # Get only input fields @@ -78,9 +68,6 @@ class Example: if "name" in example: print("Name field exists") - # Iterate over items - for key, value in example.items(): - print(f"{key}: {value}") # Get with default value city = example.get("city", "Unknown") @@ -89,6 +76,15 @@ class Example: """ def __init__(self, base=None, **kwargs): + """Initialize an Example instance. + + Args: + base: Optional base data source. Can be: + - Another Example instance (copies its data) + - A dictionary (copies its key-value pairs) + - None (creates empty Example) + **kwargs: Additional key-value pairs to store in the Example. + """ # Internal storage and other attributes self._store = {} self._demos = [] From 4397a3a5ec5b64d3ac678a21f1377f42720fc915 Mon Sep 17 00:00:00 2001 From: chenmoneygithub Date: Fri, 17 Oct 2025 13:16:04 -0700 Subject: [PATCH 3/3] lint --- dspy/primitives/example.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/dspy/primitives/example.py b/dspy/primitives/example.py index f3d33ed18d..549da6bce7 100644 --- a/dspy/primitives/example.py +++ b/dspy/primitives/example.py @@ -1,16 +1,17 @@ class Example: """A flexible data container for DSPy examples and training data. - The Example class is the standard data format used in DSPy evaluation and optimization. + The `Example` class is the standard data format used in DSPy evaluation and optimization. Key features: - Dictionary-like access patterns (item access, iteration, etc.) - - Flexible initialization from dictionaries, other Examples, or keyword arguments + - Flexible initialization from dictionaries, other `Example` instances, or keyword arguments - Input/output field separation for training data - - Serialization support for saving/loading examples - - Immutable operations that return new Example instances + - Serialization support for saving/loading `Example` instances + - Immutable operations that return new `Example` instances Examples: + Basic usage with keyword arguments: ```python @@ -63,12 +64,11 @@ class Example: ```python example = dspy.Example(name="Alice", age=30) - + # Check if key exists if "name" in example: print("Name field exists") - - + # Get with default value city = example.get("city", "Unknown") print(city) # "Unknown"