v.0.1.5

CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.5] - 2026-03-22
+
+### Added
+
+- `SyntaxKind::GOOGLE_YIELDS` — dedicated node kind for entries inside a Google
+  `Yields:` section. Previously these were emitted as `GOOGLE_RETURNS`.
+- `SyntaxKind::NUMPY_YIELDS` — dedicated node kind for entries inside a NumPy
+  `Yields` section. Previously these were emitted as `NUMPY_RETURNS`.
+- `GoogleYields` typed wrapper with `return_type()`, `colon()`, and
+  `description()` accessors (analogous to `GoogleReturns`).
+- `NumPyYields` typed wrapper with `name()`, `colon()`, `return_type()`, and
+  `description()` accessors (analogous to `NumPyReturns`).
+- `GoogleSection::yields()` — accessor returning the `GoogleYields` node for
+  a Yields section, distinct from `returns()`.
+- `NumPySection::yields()` — accessor returning an iterator of `NumPyYields`
+  nodes for a Yields section, distinct from `returns()`.
+- Python bindings: `SyntaxKind.GOOGLE_YIELDS`, `SyntaxKind.NUMPY_YIELDS`,
+  `GoogleYields` class, `NumPyYields` class, `GoogleSection.yields` property,
+  and `NumPySection.yields` property.
+
+### Changed
+
+- Google parser: `Yields:` sections now produce `GOOGLE_YIELDS` child nodes
+  instead of `GOOGLE_RETURNS`.
+- NumPy parser: `Yields` sections now produce `NUMPY_YIELDS` child nodes
+  instead of `NUMPY_RETURNS`.
+- `to_model` (Google & NumPy): `Yields` sections now use the `yields()`
+  accessor on the typed section wrapper rather than sharing the `returns()`
+  code path.
+
 ## [0.1.4] - 2026-03-20
 
 ### Added

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pydocstring"
-version = "0.1.4"
+version = "0.1.5"
 edition = "2024"
 authors = ["Ryuma Asai"]
 description = "A zero-dependency Rust parser for Python docstrings (Google and NumPy styles) with a unified syntax tree and byte-precise source locations"

README.md

@@ -24,7 +24,7 @@ Python bindings are also available as [`pydocstring-rs`](https://pypi.org/projec
 
 ```toml
 [dependencies]
-pydocstring = "0.1.4"
+pydocstring = "0.1.5"
 ```
 
 ## Usage
@@ -226,7 +226,8 @@ Both styles support the following section categories. Typed accessor methods are
 | Category                          | Google                                   | NumPy                                   |
 |-----------------------------------|------------------------------------------|-----------------------------------------|
 | Parameters                        | `args()` → `GoogleArg`                   | `parameters()` → `NumPyParameter`       |
-| Returns / Yields                  | `returns()` → `GoogleReturns`            | `returns()` → `NumPyReturns`            |
+| Returns                           | `returns()` → `GoogleReturns`            | `returns()` → `NumPyReturns`            |
+| Yields                            | `yields()` → `GoogleYields`              | `yields()` → `NumPyYields`              |
 | Raises                            | `exceptions()` → `GoogleException`       | `exceptions()` → `NumPyException`       |
 | Warns                             | `warnings()` → `GoogleWarning`           | `warnings()` → `NumPyWarning`           |
 | See Also                          | `see_also_items()` → `GoogleSeeAlsoItem` | `see_also_items()` → `NumPySeeAlsoItem` |

bindings/python/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pydocstring-python"
-version = "0.1.4"
+version = "0.1.5"
 edition = "2024"
 authors = ["Ryuma Asai"]
 description = "Python bindings for pydocstring — a fast docstring parser for Google and NumPy styles"
@@ -12,5 +12,5 @@ name = "pydocstring"
 crate-type = ["cdylib"]
 
 [dependencies]
-pydocstring_core = { package = "pydocstring", version = "0.1.4", path = "../.." }
+pydocstring_core = { package = "pydocstring", version = "0.1.5", path = "../.." }
 pyo3 = { version = "0.24", features = ["extension-module"] }

bindings/python/README.md

@@ -301,15 +301,17 @@ print(numpy_text)  # Contains "Parameters\n----------"
 |-------------------|------------------------------------------------------------------------------------------------------------------|
 | `Style`           | `GOOGLE`, `NUMPY`, `PLAIN` (enum)                                                                                |
 | `GoogleDocstring` | `style`, `summary`, `extended_summary`, `sections`, `node`, `source`, `pretty_print()`, `to_model()`             |
-| `GoogleSection`   | `kind`, `args`, `returns`, `exceptions`, `body_text`, `node`                                                     |
+| `GoogleSection`   | `kind`, `args`, `returns`, `yields`, `exceptions`, `body_text`, `node`                                           |
 | `GoogleArg`       | `name`, `type`, `description`, `optional`                                                                        |
 | `GoogleReturns`   | `return_type`, `description`                                                                                     |
+| `GoogleYields`    | `return_type`, `description`                                                                                     |
 | `GoogleException` | `type`, `description`                                                                                            |
 | `PlainDocstring`  | `style`, `summary`, `extended_summary`, `node`, `source`, `pretty_print()`, `to_model()`                         |
 | `NumPyDocstring`  | `style`, `summary`, `extended_summary`, `sections`, `node`, `source`, `pretty_print()`, `to_model()`             |
-| `NumPySection`    | `kind`, `parameters`, `returns`, `exceptions`, `body_text`, `node`                                               |
+| `NumPySection`    | `kind`, `parameters`, `returns`, `yields`, `exceptions`, `body_text`, `node`                                     |
 | `NumPyParameter`  | `names`, `type`, `description`, `optional`, `default_value`                                                      |
 | `NumPyReturns`    | `name`, `return_type`, `description`                                                                             |
+| `NumPyYields`     | `name`, `return_type`, `description`                                                                             |
 | `NumPyException`  | `type`, `description`                                                                                            |
 | `Token`           | `kind`, `text`, `range`                                                                                          |
 | `Node`            | `kind`, `range`, `children`                                                                                      |

bindings/python/pydocstring.pyi

@@ -39,6 +39,7 @@ class SyntaxKind(enum.IntEnum):
     GOOGLE_SECTION_HEADER = ...
     GOOGLE_ARG = ...
     GOOGLE_RETURNS = ...
+    GOOGLE_YIELDS = ...
     GOOGLE_EXCEPTION = ...
     GOOGLE_WARNING = ...
     GOOGLE_SEE_ALSO_ITEM = ...
@@ -51,6 +52,7 @@ class SyntaxKind(enum.IntEnum):
     NUMPY_DEPRECATION = ...
     NUMPY_PARAMETER = ...
     NUMPY_RETURNS = ...
+    NUMPY_YIELDS = ...
     NUMPY_EXCEPTION = ...
     NUMPY_WARNING = ...
     NUMPY_SEE_ALSO_ITEM = ...
@@ -111,6 +113,12 @@ class GoogleReturns:
     @property
     def description(self) -> Token | None: ...
 
+class GoogleYields:
+    @property
+    def return_type(self) -> Token | None: ...
+    @property
+    def description(self) -> Token | None: ...
+
 class GoogleException:
     @property
     def type(self) -> Token: ...
@@ -125,6 +133,8 @@ class GoogleSection:
     @property
     def returns(self) -> GoogleReturns | None: ...
     @property
+    def yields(self) -> GoogleYields | None: ...
+    @property
     def exceptions(self) -> list[GoogleException]: ...
     @property
     def body_text(self) -> Token | None: ...
@@ -176,6 +186,14 @@ class NumPyReturns:
     @property
     def description(self) -> Token | None: ...
 
+class NumPyYields:
+    @property
+    def name(self) -> Token | None: ...
+    @property
+    def return_type(self) -> Token | None: ...
+    @property
+    def description(self) -> Token | None: ...
+
 class NumPyException:
     @property
     def type(self) -> Token: ...
@@ -190,6 +208,8 @@ class NumPySection:
     @property
     def returns(self) -> list[NumPyReturns]: ...
     @property
+    def yields(self) -> list[NumPyYields]: ...
+    @property
     def exceptions(self) -> list[NumPyException]: ...
     @property
     def body_text(self) -> Token | None: ...

bindings/python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "pydocstring-rs"
-version = "0.1.4"
+version = "0.1.5"
 description = "Python bindings for pydocstring — a zero-dependency Rust parser for Python docstrings (Google and NumPy styles) with a unified syntax tree and byte-precise source locations"
 license = {text = "MIT"}
 authors = [{name = "Ryuma Asai"}]

bindings/python/src/lib.rs

@@ -132,6 +132,7 @@ enum PySyntaxKind {
     GOOGLE_SECTION_HEADER,
     GOOGLE_ARG,
     GOOGLE_RETURNS,
+    GOOGLE_YIELDS,
     GOOGLE_EXCEPTION,
     GOOGLE_WARNING,
     GOOGLE_SEE_ALSO_ITEM,
@@ -144,6 +145,7 @@ enum PySyntaxKind {
     NUMPY_DEPRECATION,
     NUMPY_PARAMETER,
     NUMPY_RETURNS,
+    NUMPY_YIELDS,
     NUMPY_EXCEPTION,
     NUMPY_WARNING,
     NUMPY_SEE_ALSO_ITEM,
@@ -196,6 +198,7 @@ impl PySyntaxKind {
             SyntaxKind::GOOGLE_SECTION_HEADER => Self::GOOGLE_SECTION_HEADER,
             SyntaxKind::GOOGLE_ARG => Self::GOOGLE_ARG,
             SyntaxKind::GOOGLE_RETURNS => Self::GOOGLE_RETURNS,
+            SyntaxKind::GOOGLE_YIELDS => Self::GOOGLE_YIELDS,
             SyntaxKind::GOOGLE_EXCEPTION => Self::GOOGLE_EXCEPTION,
             SyntaxKind::GOOGLE_WARNING => Self::GOOGLE_WARNING,
             SyntaxKind::GOOGLE_SEE_ALSO_ITEM => Self::GOOGLE_SEE_ALSO_ITEM,
@@ -207,6 +210,7 @@ impl PySyntaxKind {
             SyntaxKind::NUMPY_DEPRECATION => Self::NUMPY_DEPRECATION,
             SyntaxKind::NUMPY_PARAMETER => Self::NUMPY_PARAMETER,
             SyntaxKind::NUMPY_RETURNS => Self::NUMPY_RETURNS,
+            SyntaxKind::NUMPY_YIELDS => Self::NUMPY_YIELDS,
             SyntaxKind::NUMPY_EXCEPTION => Self::NUMPY_EXCEPTION,
             SyntaxKind::NUMPY_WARNING => Self::NUMPY_WARNING,
             SyntaxKind::NUMPY_SEE_ALSO_ITEM => Self::NUMPY_SEE_ALSO_ITEM,
@@ -247,6 +251,7 @@ impl PySyntaxKind {
             Self::GOOGLE_SECTION_HEADER => SyntaxKind::GOOGLE_SECTION_HEADER,
             Self::GOOGLE_ARG => SyntaxKind::GOOGLE_ARG,
             Self::GOOGLE_RETURNS => SyntaxKind::GOOGLE_RETURNS,
+            Self::GOOGLE_YIELDS => SyntaxKind::GOOGLE_YIELDS,
             Self::GOOGLE_EXCEPTION => SyntaxKind::GOOGLE_EXCEPTION,
             Self::GOOGLE_WARNING => SyntaxKind::GOOGLE_WARNING,
             Self::GOOGLE_SEE_ALSO_ITEM => SyntaxKind::GOOGLE_SEE_ALSO_ITEM,
@@ -258,6 +263,7 @@ impl PySyntaxKind {
             Self::NUMPY_DEPRECATION => SyntaxKind::NUMPY_DEPRECATION,
             Self::NUMPY_PARAMETER => SyntaxKind::NUMPY_PARAMETER,
             Self::NUMPY_RETURNS => SyntaxKind::NUMPY_RETURNS,
+            Self::NUMPY_YIELDS => SyntaxKind::NUMPY_YIELDS,
             Self::NUMPY_EXCEPTION => SyntaxKind::NUMPY_EXCEPTION,
             Self::NUMPY_WARNING => SyntaxKind::NUMPY_WARNING,
             Self::NUMPY_SEE_ALSO_ITEM => SyntaxKind::NUMPY_SEE_ALSO_ITEM,
@@ -415,6 +421,24 @@ impl PyGoogleReturns {
     }
 }
 
+#[pyclass(name = "GoogleYields", frozen)]
+struct PyGoogleYields {
+    return_type: Option<Py<PyToken>>,
+    description: Option<Py<PyToken>>,
+}
+
+#[pymethods]
+impl PyGoogleYields {
+    #[getter]
+    fn return_type(&self, py: Python<'_>) -> Option<Py<PyToken>> {
+        self.return_type.as_ref().map(|t| t.clone_ref(py))
+    }
+    #[getter]
+    fn description(&self, py: Python<'_>) -> Option<Py<PyToken>> {
+        self.description.as_ref().map(|t| t.clone_ref(py))
+    }
+}
+
 #[pyclass(name = "GoogleException", frozen)]
 struct PyGoogleException {
     r#type: Py<PyToken>,
@@ -438,6 +462,7 @@ struct PyGoogleSection {
     kind: String,
     args: Vec<Py<PyGoogleArg>>,
     returns: Option<Py<PyGoogleReturns>>,
+    yields: Option<Py<PyGoogleYields>>,
     exceptions: Vec<Py<PyGoogleException>>,
     body_text: Option<Py<PyToken>>,
     node: Py<PyNode>,
@@ -458,6 +483,10 @@ impl PyGoogleSection {
         self.returns.as_ref().map(|r| r.clone_ref(py))
     }
     #[getter]
+    fn yields(&self, py: Python<'_>) -> Option<Py<PyGoogleYields>> {
+        self.yields.as_ref().map(|r| r.clone_ref(py))
+    }
+    #[getter]
     fn exceptions(&self, py: Python<'_>) -> Vec<Py<PyGoogleException>> {
         self.exceptions.iter().map(|e| e.clone_ref(py)).collect()
     }
@@ -595,6 +624,29 @@ impl PyNumPyReturns {
     }
 }
 
+#[pyclass(name = "NumPyYields", frozen)]
+struct PyNumPyYields {
+    name: Option<Py<PyToken>>,
+    return_type: Option<Py<PyToken>>,
+    description: Option<Py<PyToken>>,
+}
+
+#[pymethods]
+impl PyNumPyYields {
+    #[getter]
+    fn name(&self, py: Python<'_>) -> Option<Py<PyToken>> {
+        self.name.as_ref().map(|t| t.clone_ref(py))
+    }
+    #[getter]
+    fn return_type(&self, py: Python<'_>) -> Option<Py<PyToken>> {
+        self.return_type.as_ref().map(|t| t.clone_ref(py))
+    }
+    #[getter]
+    fn description(&self, py: Python<'_>) -> Option<Py<PyToken>> {
+        self.description.as_ref().map(|t| t.clone_ref(py))
+    }
+}
+
 #[pyclass(name = "NumPyException", frozen)]
 struct PyNumPyException {
     r#type: Py<PyToken>,
@@ -618,6 +670,7 @@ struct PyNumPySection {
     kind: String,
     parameters: Vec<Py<PyNumPyParameter>>,
     returns: Vec<Py<PyNumPyReturns>>,
+    yields: Vec<Py<PyNumPyYields>>,
     exceptions: Vec<Py<PyNumPyException>>,
     body_text: Option<Py<PyToken>>,
     node: Py<PyNode>,
@@ -638,6 +691,10 @@ impl PyNumPySection {
         self.returns.iter().map(|r| r.clone_ref(py)).collect()
     }
     #[getter]
+    fn yields(&self, py: Python<'_>) -> Vec<Py<PyNumPyYields>> {
+        self.yields.iter().map(|r| r.clone_ref(py)).collect()
+    }
+    #[getter]
     fn exceptions(&self, py: Python<'_>) -> Vec<Py<PyNumPyException>> {
         self.exceptions.iter().map(|e| e.clone_ref(py)).collect()
     }
@@ -804,6 +861,18 @@ fn build_google_docstring(py: Python<'_>, parsed: &Parsed) -> PyResult<Py<PyGoog
                     )
                 })
                 .transpose()?;
+            let yields = sec
+                .yields()
+                .map(|r| {
+                    Py::new(
+                        py,
+                        PyGoogleYields {
+                            return_type: to_py_token_opt(py, r.return_type(), source)?,
+                            description: to_py_token_opt(py, r.description(), source)?,
+                        },
+                    )
+                })
+                .transpose()?;
             let exceptions: Vec<Py<PyGoogleException>> = sec
                 .exceptions()
                 .map(|e| {
@@ -824,6 +893,7 @@ fn build_google_docstring(py: Python<'_>, parsed: &Parsed) -> PyResult<Py<PyGoog
                     kind,
                     args,
                     returns,
+                    yields,
                     exceptions,
                     body_text,
                     node,
@@ -890,6 +960,19 @@ fn build_numpy_docstring(py: Python<'_>, parsed: &Parsed) -> PyResult<Py<PyNumPy
                     )
                 })
                 .collect::<PyResult<Vec<_>>>()?;
+            let yields: Vec<Py<PyNumPyYields>> = sec
+                .yields()
+                .map(|r| {
+                    Py::new(
+                        py,
+                        PyNumPyYields {
+                            name: to_py_token_opt(py, r.name(), source)?,
+                            return_type: to_py_token_opt(py, r.return_type(), source)?,
+                            description: to_py_token_opt(py, r.description(), source)?,
+                        },
+                    )
+                })
+                .collect::<PyResult<Vec<_>>>()?;
             let exceptions: Vec<Py<PyNumPyException>> = sec
                 .exceptions()
                 .map(|e| {
@@ -910,6 +993,7 @@ fn build_numpy_docstring(py: Python<'_>, parsed: &Parsed) -> PyResult<Py<PyNumPy
                     kind,
                     parameters,
                     returns,
+                    yields,
                     exceptions,
                     body_text,
                     node,
@@ -1744,11 +1828,13 @@ fn pydocstring(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<PyGoogleSection>()?;
     m.add_class::<PyGoogleArg>()?;
     m.add_class::<PyGoogleReturns>()?;
+    m.add_class::<PyGoogleYields>()?;
     m.add_class::<PyGoogleException>()?;
     m.add_class::<PyNumPyDocstring>()?;
     m.add_class::<PyNumPySection>()?;
     m.add_class::<PyNumPyParameter>()?;
     m.add_class::<PyNumPyReturns>()?;
+    m.add_class::<PyNumPyYields>()?;
     m.add_class::<PyNumPyException>()?;
     m.add_class::<PyPlainDocstring>()?;
     m.add_class::<PyModelDocstring>()?;

src/parse/google.rs

@@ -10,6 +10,6 @@ pub mod to_model;
 pub use kind::GoogleSectionKind;
 pub use nodes::{
     GoogleArg, GoogleAttribute, GoogleDocstring, GoogleException, GoogleMethod, GoogleReturns, GoogleSection,
-    GoogleSectionHeader, GoogleSeeAlsoItem, GoogleWarning,
+    GoogleSectionHeader, GoogleSeeAlsoItem, GoogleWarning, GoogleYields,
 };
 pub use parser::parse_google;