pydocstring 0.4.0

A zero-dependency Rust parser for Python docstrings (Google and NumPy styles) with a unified syntax tree and byte-precise source locations
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

//! Source-aware token handle returned by the typed views.
//!
//! The raw tree layer keeps token text explicit — [`SyntaxToken::text`]
//! takes the source string, per the source-backed decision on issue #42.
//! The typed views ([`Document`](crate::parse::Document) and friends, the
//! per-style wrappers, [`TextBlock`](crate::parse::TextBlock)) already hold
//! the [`Parsed`] result they came from, so the tokens *they* hand out can
//! bundle it: a [`TokenRef`] is a token plus its parse result, giving
//! `token.text()` without threading `source` through every call.

use crate::syntax::Parsed;
use crate::syntax::SyntaxKind;
use crate::syntax::SyntaxToken;
use crate::text::TextRange;

/// A [`SyntaxToken`] bundled with the [`Parsed`] result it belongs to.
///
/// Returned by every token accessor on the typed views so that token text is
/// available without passing the source around ([`TokenRef::text`]). The raw
/// token stays reachable via [`TokenRef::syntax`] for code that works on the
/// tree layer.
#[derive(Debug, Clone, Copy)]
pub struct TokenRef<'a> {
    parsed: &'a Parsed,
    token: &'a SyntaxToken,
}

impl<'a> TokenRef<'a> {
    /// Bundle `token` with the [`Parsed`] result it belongs to.
    ///
    /// `token` must come from `parsed`'s tree; a foreign token yields
    /// nonsensical (but memory-safe) [`text`](Self::text) results.
    pub fn new(parsed: &'a Parsed, token: &'a SyntaxToken) -> Self {
        Self { parsed, token }
    }

    /// Access the underlying raw [`SyntaxToken`].
    pub fn syntax(&self) -> &'a SyntaxToken {
        self.token
    }

    /// The kind of this token.
    pub fn kind(&self) -> SyntaxKind {
        self.token.kind()
    }

    /// The source range of this token.
    pub fn range(&self) -> TextRange {
        self.token.range()
    }

    /// Whether this token is missing from the source (zero-length
    /// placeholder). See [`SyntaxToken::is_missing`].
    pub fn is_missing(&self) -> bool {
        self.token.is_missing()
    }

    /// The token's text, sliced from the parse result's source.
    pub fn text(&self) -> &'a str {
        self.token.text(self.parsed.source())
    }
}