> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Python Docstring
A Python docstring (documentation string) is a string literal specified as the first evaluated statement within a module, class, method, or function definition. Unlike standard inline comments (`#`), docstrings are parsed and evaluated at compile time, stored as constants in the compiled code object (`co_consts`), and bound to the object's `__doc__` attribute at runtime. Because they must be compile-time constants, dynamically evaluated strings (such as f-strings) cannot be used as docstrings.
## Syntax and Conventions
Docstrings are defined using triple quotes. While both `'''` and `"""` are syntactically valid, Python's official style guide for docstrings (PEP 257) strictly mandates the use of double-triple quotes (`"""`) for consistency.
There are two primary structural formats:
**1. One-line Docstrings**
The opening quotes, the string literal, and the closing quotes must reside on the exact same line.
```python theme={"dark"}
def calculate_entropy(probabilities):
"""Calculate the Shannon entropy of a probability distribution."""
pass
```
**2. Multi-line Docstrings**
The structure must consist of a concise summary line, followed by a single blank line, followed by the extended description. The summary line may begin on the exact same line as the opening quotes, or on the line immediately following them. The closing quotes must be placed on a new line by themselves.
```python theme={"dark"}
class TelemetryProcessor:
"""
Process raw telemetry byte streams into normalized structures.
This class handles the ingestion, validation, and transformation
of raw byte streams into structured JSON payloads. It requires
a valid schema definition upon instantiation.
"""
def __init__(self, schema):
"""Initialize the processor with a validation schema."""
self.schema = schema
```
## Placement Rules
To be recognized by the Python interpreter as a docstring, the string literal must be the first evaluated statement in the given scope. Because the Python parser ignores standard comments (`#`), any number of comments can safely precede a docstring.
* **Module-level:** Must be the first statement in the file, preceding all imports and logic. Shebangs (`#!/usr/bin/env python`), encoding declarations (`#-*- coding: utf-8 -*-`), and standard comments may precede the docstring.
* **Class-level:** Must be the first statement following the `class` declaration line.
* **Function/Method-level:** Must be the first statement following the `def` declaration line.
## Runtime Access and Introspection
**Interactive Access via `help()`**
The built-in `help()` function is the primary and most critical tool used to interactively read docstrings within the Python REPL. It formats the docstring and presents it through a pager for readability.
```python theme={"dark"}
help(TelemetryProcessor)
```
**Programmatic Access via `__doc__`**
Because docstrings are bound to the object at runtime, developers can access the raw string programmatically using the `__doc__` dunder (double underscore) attribute of the target object.
```python theme={"dark"}
print(TelemetryProcessor.__doc__)
print(TelemetryProcessor.__init__.__doc__)
```
If a docstring is not defined for an object, its `__doc__` attribute defaults to `None`. When a child class *overrides* a parent's method but omits a new docstring, the overridden method's `__doc__` attribute evaluates to `None`. Conversely, an *inherited* method (one not redefined by the child class) is the exact same function object as the parent's method, meaning it inherently possesses the exact same docstring.
**Advanced Access via `inspect.getdoc()`**
For robust programmatic access, the standard library provides the `inspect.getdoc()` function. This is the standard and preferred way to fetch docstrings programmatically because it automatically cleans up multi-line indentation and resolves missing docstrings by fetching them from parent classes via the Method Resolution Order (MRO).
```python theme={"dark"}
import inspect
class AdvancedProcessor(TelemetryProcessor):
def __init__(self, schema):
# Overridden method omitting a new docstring
super().__init__(schema)
# Direct attribute access evaluates to None
print(AdvancedProcessor.__init__.__doc__)
# inspect.getdoc() resolves the missing docstring from the parent class
print(inspect.getdoc(AdvancedProcessor.__init__))
```
Tired of Poor Python Skills? Fix That With Deep Grasping!
Learn More
