Struct Parsed 

pub struct Parsed { /* private fields */ }

The result of parsing a docstring.

Owns the source text and the root SyntaxNode, and records the Style the docstring was parsed as (the root node kind is the style-neutral SyntaxKind::DOCUMENT).

Implementations

impl Parsed

pub fn edit(&self) -> Edits<'_>

Start an empty edit list anchored on this parse result.

See the edit module docs for the model and an end-to-end example.

impl Parsed

pub fn to_model(&self) -> Docstring

Convert to the normalized model IR (Docstring).

This is the third read lens, next to the Document view and the raw CST: it drops byte positions and normalizes the text, which is what makes it the input to emit. The style is dispatched on internally — a Google and a NumPy docstring with the same content produce the same model.

use pydocstring::parse::parse;

let model = parse("Summary.\n\nArgs:\n    x (int): The value.\n").to_model();
assert_eq!(model.summary.as_deref(), Some("Summary."));

impl Parsed

pub fn replace( &self, pattern: &Pattern, template: &str, ) -> Result<String, RewriteError>

Replace every match of pattern in this document with template rendered against that match’s captures, returning the new source.

Matches are found globally with Pattern::matches (all readings, document order, non-overlapping). Style-strict: a pattern of a different style, or one that matches nothing, returns the source unchanged. See the module docs for the template and re-indentation semantics.

Errors

RewriteError::UnknownMetavar if the template names a metavariable a match’s reading did not bind.

pub fn replace_in( &self, pattern: &Pattern, anchor: &SyntaxNode, template: &str, ) -> Result<String, RewriteError>

Like replace, but scoped to anchor’s subtree via Pattern::matches_in: the anchor’s grammar selects the readings, so the same pattern rewrites $TYPE-shaped entries under a Raises: anchor and $NAME-shaped ones under an Args: anchor. An anchor that is not a node of this document’s tree matches nothing (the source is returned unchanged).

impl Parsed

pub fn new(source: String, root: SyntaxNode, style: Style) -> Self

Creates a new Parsed from source text, root node, and source style.

Invariants

A Parsed is expected to originate from one of this crate’s parsers (parse or a per-style parse_* function). Constructing one by hand is possible but the tree must then uphold the laws the parsers guarantee and downstream consumers rely on:

• every element’s range lies within source and within its parent’s range, and siblings appear in source order (containment/ordering);
• a node’s children plus trivia tokens exactly cover the node’s range (coverage — pinned corpus-wide in tests/trivia.rs);
• token text is a slice of source (no synthesized text, see the source-backed decision on issue #42);
• zero-length elements are missing placeholders and nothing else.

A hand-built tree that violates these laws produces unspecified (but memory-safe) results from the typed views, the visitor, and to_model.

pub fn source(&self) -> &str

The full source text.

Examples found in repository

examples/parse_google.rs (line 35)

fn main() {
    let docstring = r#"
Calculate the area of a rectangle.

This function takes the width and height of a rectangle
and returns its area.

Args:
    width (float): The width of the rectangle.
    height (float): The height of the rectangle.

Returns:
    float: The area of the rectangle.

Raises:
    ValueError: If width or height is negative.
"#;

    let parsed = parse_google(docstring);

    println!("╔══════════════════════════════════════════════════╗");
    println!("║          Google-style Docstring Example          ║");
    println!("╚══════════════════════════════════════════════════╝");

    println!();

    // Display: raw source text
    println!("── raw text ────────────────────────────────────────");
    println!("{}", parsed.source());

    println!();

    // pretty_print: structured AST
    println!("── parsed AST ──────────────────────────────────────");
    print!("{}", parsed.pretty_print());
}

examples/parse_numpy.rs (line 49)

fn main() {
    let docstring = r#"
Calculate the area of a rectangle.

This function takes the width and height of a rectangle
and returns its area.

Parameters
----------
width : float
    The width of the rectangle.
height : float
    The height of the rectangle.

Returns
-------
float
    The area of the rectangle.

Raises
------
ValueError
    If width or height is negative.

Examples
--------
>>> calculate_area(5.0, 3.0)
15.0
"#;

    let parsed = parse_numpy(docstring);
    let doc = Document::new(&parsed);

    println!("╔══════════════════════════════════════════════════╗");
    println!("║          NumPy-style Docstring Example           ║");
    println!("╚══════════════════════════════════════════════════╝");

    println!();

    // Display: raw source text
    println!("── raw text ────────────────────────────────────────");
    println!("{}", doc.syntax().range().source_text(parsed.source()));

    println!();

    // pretty_print: structured AST
    println!("── parsed AST ──────────────────────────────────────");
    print!("{}", parsed.pretty_print());
}

pub fn root(&self) -> &SyntaxNode

The root node of the syntax tree.

pub fn style(&self) -> Style

The style this docstring was parsed as.

Examples found in repository

examples/parse_auto.rs (line 17)

fn show(label: &str, input: &str) {
    let parsed = parse(input);
    let style_label = match parsed.style() {
        Style::Google => "Google",
        Style::NumPy => "NumPy",
        Style::Plain => "Plain",
        // `Style` is #[non_exhaustive]: future styles land here.
        _ => "Unknown",
    };

    println!(
        "── {} → {} ──────────────────────────────────────────",
        label, style_label
    );
    print!("{}", parsed.pretty_print());
    println!();
}

pub fn line_col(&self, offset: TextSize) -> LineColumn

Convert a byte offset to a LineColumn position.

lineno is 1-based; col is the 0-based byte column within the line.

col is a byte column, so it composes with every other offset in this API (offset - col is the start of the line). It is not a display width and not an indent: reconstructing indentation as " ".repeat(col) over-indents a line containing a multi-byte character and turns a tab into a space. Use line_indent for that.

pub fn line_indent(&self, offset: TextSize) -> &str

The leading whitespace of the line that offset falls on.

This is the indent an edit anchored there has to match, handed back as the literal bytes to copy — which is the only form that survives both a tab-indented docstring and a line whose text is not ASCII. A column cannot express either: " ".repeat(col) replaces a tab with a space, and counts a é twice.

use pydocstring::parse::parse;
use pydocstring::text::TextSize;

let parsed = parse("Summary.\n\nArgs:\n\tx (int): The value.\n");
let x = parsed.source().find("x (int)").unwrap();
assert_eq!(parsed.line_indent(TextSize::new(x as u32)), "\t");

pub fn pretty_print(&self) -> String

Produce a Biome-style pretty-printed representation of the tree.

This is a debugging aid: the exact output format is not stable and may change in any release — do not parse or snapshot it in downstream code.

Examples found in repository

examples/parse_auto.rs (line 29)

fn show(label: &str, input: &str) {
    let parsed = parse(input);
    let style_label = match parsed.style() {
        Style::Google => "Google",
        Style::NumPy => "NumPy",
        Style::Plain => "Plain",
        // `Style` is #[non_exhaustive]: future styles land here.
        _ => "Unknown",
    };

    println!(
        "── {} → {} ──────────────────────────────────────────",
        label, style_label
    );
    print!("{}", parsed.pretty_print());
    println!();
}

examples/parse_google.rs (line 41)

fn main() {
    let docstring = r#"
Calculate the area of a rectangle.

This function takes the width and height of a rectangle
and returns its area.

Args:
    width (float): The width of the rectangle.
    height (float): The height of the rectangle.

Returns:
    float: The area of the rectangle.

Raises:
    ValueError: If width or height is negative.
"#;

    let parsed = parse_google(docstring);

    println!("╔══════════════════════════════════════════════════╗");
    println!("║          Google-style Docstring Example          ║");
    println!("╚══════════════════════════════════════════════════╝");

    println!();

    // Display: raw source text
    println!("── raw text ────────────────────────────────────────");
    println!("{}", parsed.source());

    println!();

    // pretty_print: structured AST
    println!("── parsed AST ──────────────────────────────────────");
    print!("{}", parsed.pretty_print());
}

examples/parse_numpy.rs (line 55)

fn main() {
    let docstring = r#"
Calculate the area of a rectangle.

This function takes the width and height of a rectangle
and returns its area.

Parameters
----------
width : float
    The width of the rectangle.
height : float
    The height of the rectangle.

Returns
-------
float
    The area of the rectangle.

Raises
------
ValueError
    If width or height is negative.

Examples
--------
>>> calculate_area(5.0, 3.0)
15.0
"#;

    let parsed = parse_numpy(docstring);
    let doc = Document::new(&parsed);

    println!("╔══════════════════════════════════════════════════╗");
    println!("║          NumPy-style Docstring Example           ║");
    println!("╚══════════════════════════════════════════════════╝");

    println!();

    // Display: raw source text
    println!("── raw text ────────────────────────────────────────");
    println!("{}", doc.syntax().range().source_text(parsed.source()));

    println!();

    // pretty_print: structured AST
    println!("── parsed AST ──────────────────────────────────────");
    print!("{}", parsed.pretty_print());
}

Trait Implementations

impl Clone for Parsed

fn clone(&self) -> Parsed

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Parsed

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Parsed

impl PartialEq for Parsed

fn eq(&self, other: &Parsed) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Parsed