Skip to content

armgit / dspy

Public Imported from GitHub
0

DSPy: The framework for programming—not prompting—language models

Python

[docs]Add Google-Style comprehensive docstring to dspy/primitives/example Example class (#8949)

Shivam davebbcfe087d78e
diff --git a/dspy/primitives/example.py b/dspy/primitives/example.py
index abbc381f7..549da6bce 100644
--- a/dspy/primitives/example.py
+++ b/dspy/primitives/example.py
@@ -1,5 +1,90 @@
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.
+
+ Key features:
+ - Dictionary-like access patterns (item access, iteration, etc.)
+ - Flexible initialization from dictionaries, other `Example` instances, or keyword arguments
+ - Input/output field separation for training data
+ - Serialization support for saving/loading `Example` instances
+ - Immutable operations that return new `Example` instances
+
+ 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")
+
+ # Get with default value
+ city = example.get("city", "Unknown")
+ print(city) # "Unknown"
+ ```
+ """
+
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 = []