/// Load the database, or report the interpreter's Unicode name import failure.

fn prepare(&self) -> Result<(), UnicodeNameProviderUnavailable>;

/// Resolve one character name after preparation, excluding named sequences.

fn lookup(&self, name: &[u8]) -> Option<u32>;

/// Called after a literal (or f/t-string literal fragment) has decoded successfully.

/// `source` is the undecoded content of that literal, without its quote delimiters.

/// An error aborts interpreter effects and survives grammar backtracking.

fn literal_decoded(

&self,

_source: &str,

_flags: ruff_python_ast::AnyStringFlags,

_range: ruff_text_size::TextRange,

) -> Result<(), ParseError> {

Ok(())

}

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

f.write_str("\\N escapes not supported (can't load unicodedata module)")

}

Parser::new(source, ParseOptions::from(Mode::Module))

.parse()

.try_into_module()

.unwrap()

.into_result()

Parser::new(source, ParseOptions::from(Mode::Expression))

.parse()

.try_into_expression()

.unwrap()

.into_result()

source: &str,

range: TextRange,

) -> Result<Parsed<ModExpression>, ParseError> {

let source = &source[..range.end().to_usize()];

Parser::new_starts_at(source, range.start(), ParseOptions::from(Mode::Expression))

.parse()

.try_into_expression()

.unwrap()

.into_result()

source: &str,

range: TextRange,

) -> Result<Parsed<ModExpression>, ParseError> {

let source = &source[..range.end().to_usize()];

let parsed = Parser::new_starts_at(

source,

range.start(),

ParseOptions::from(Mode::ParenthesizedExpression),

)

.parse();

parsed.try_into_expression().unwrap().into_result()

source: &str,

string: &StringLiteral,

) -> Result<Parsed<ModExpression>, ParseError> {

let range = string

.range()

.add_start(string.flags.opener_len())

.sub_end(string.flags.closer_len());

let source = &source[..range.end().to_usize()];

if string.flags.is_triple_quoted() {

parse_parenthesized_expression_range(source, range)

} else {

parse_expression_range(source, range)

}

source: &str,

options: ParseOptions,

provider: &dyn ParseRuntime,

) -> Parsed<Mod> {

Parser::new(source, options).with_runtime(provider).parse()

// SAFETY: Safe because `PySourceType` always parses to a `ModModule`

Parser::new(source, ParseOptions::from(source_type))

.parse()

.try_into_module()

.unwrap()

source: &str,

ranges: impl IntoIterator<Item = TextRange>,

options: &ParseOptions,

) -> Parsed<ModModule> {

let mut ranges = ranges.into_iter().peekable();

let first_range = ranges.peek();

debug_assert!(

first_range.is_none_or(|range| range.start() == TextSize::new(0)),

"the first cell range must start at offset zero",

);

let mut body = Suite::new();

let mut tokens = Vec::new();

let mut errors = Vec::new();

let mut unsupported_syntax_errors = Vec::new();

let mut previous_end: Option<TextSize> = None;

while let Some(range) = ranges.next() {

if let Some(previous_end) = previous_end {

assert!(previous_end <= range.start());

}

// The cell is lexed from `range.start()`, so the slice must keep the leading text to

// preserve absolute offsets into the concatenated source.

let cell_source = &source[TextRange::up_to(range.end())];

let Parsed {

syntax,

tokens: cell_tokens,

errors: cell_errors,

unsupported_syntax_errors: cell_unsupported_syntax_errors,

} = Parser::new_starts_at(cell_source, range.start(), options.clone())

.parse()

.try_into_module()

.expect("module options should parse into a module");

body.extend(syntax.body);

tokens.extend(cell_tokens);

errors.extend(cell_errors);

unsupported_syntax_errors.extend(cell_unsupported_syntax_errors);

// Each range excludes its trailing `\n` separator (see the doc comment above), leaving a

// one-byte gap in the token stream. Cover it with a `NonLogicalNewline` so token-based

// checks don't treat the separator as another logical line terminator. The final cell's

// separator is the file-final newline and is deliberately left uncovered.

if let Some(next) = ranges.peek() {

let separator = TextRange::new(range.end(), next.start());

assert_eq!(&source[separator], "\n");

tokens.push(Token::new(

TokenKind::NonLogicalNewline,

separator,

TokenFlags::empty(),

));

}

previous_end = Some(range.end());

}

body.shrink_to_fit();

tokens.shrink_to_fit();

errors.shrink_to_fit();

unsupported_syntax_errors.shrink_to_fit();

Parsed {

syntax: ModModule {

node_index: AtomicNodeIndex::NONE,

range: TextRange::up_to(source.text_len()),

body,

runtime_body: None,

},

tokens: Tokens::new(tokens),

errors,

unsupported_syntax_errors,

}

syntax: T,

tokens: Tokens,

errors: Vec<ParseError>,

unsupported_syntax_errors: Vec<UnsupportedSyntaxError>,

/// Returns the syntax node represented by this parsed output.

pub fn syntax(&self) -> &T {

&self.syntax

}

/// Returns all the tokens for the parsed output.

pub fn tokens(&self) -> &Tokens {

&self.tokens

}

/// Returns a list of syntax errors found during parsing.

pub fn errors(&self) -> &[ParseError] {

&self.errors

}

/// Returns a list of version-related syntax errors found during parsing.

pub fn unsupported_syntax_errors(&self) -> &[UnsupportedSyntaxError] {

&self.unsupported_syntax_errors

}

/// Consumes the [`Parsed`] output and returns the contained syntax node.

pub fn into_syntax(self) -> T {

self.syntax

}

/// Consumes the [`Parsed`] output and returns a list of syntax errors found during parsing.

fn into_errors(self) -> Vec<ParseError> {

self.errors

}

/// Returns `true` if the parsed source code is valid i.e., it has no [`ParseError`]s.

///

/// Note that this does not include version-related [`UnsupportedSyntaxError`]s.

///

/// See [`Parsed::has_no_syntax_errors`] for a version that takes these into account.

pub fn has_valid_syntax(&self) -> bool {

self.errors.is_empty()

}

/// Returns `true` if the parsed source code is invalid i.e., it has [`ParseError`]s.

///

/// Note that this does not include version-related [`UnsupportedSyntaxError`]s.

///

/// See [`Parsed::has_no_syntax_errors`] for a version that takes these into account.

pub fn has_invalid_syntax(&self) -> bool {

!self.has_valid_syntax()

}

/// Returns `true` if the parsed source code does not contain any [`ParseError`]s *or*

/// [`UnsupportedSyntaxError`]s.

///

/// See [`Parsed::has_valid_syntax`] for a version specific to [`ParseError`]s.

pub fn has_no_syntax_errors(&self) -> bool {

self.has_valid_syntax() && self.unsupported_syntax_errors.is_empty()

}

/// Returns `true` if the parsed source code contains any [`ParseError`]s *or*

/// [`UnsupportedSyntaxError`]s.

///

/// See [`Parsed::has_invalid_syntax`] for a version specific to [`ParseError`]s.

pub fn has_syntax_errors(&self) -> bool {

!self.has_no_syntax_errors()

}

/// Returns the [`Parsed`] output as a [`Result`], returning [`Ok`] if it has no syntax errors,

/// or [`Err`] containing the first [`ParseError`] encountered.

///

/// Note that any [`unsupported_syntax_errors`](Parsed::unsupported_syntax_errors) will not

/// cause [`Err`] to be returned.

pub fn as_result(&self) -> Result<&Parsed<T>, &[ParseError]> {

if self.has_valid_syntax() {

Ok(self)

} else {

Err(&self.errors)

}

}

/// Consumes the [`Parsed`] output and returns a [`Result`] which is [`Ok`] if it has no syntax

/// errors, or [`Err`] containing the first [`ParseError`] encountered.

///

/// Note that any [`unsupported_syntax_errors`](Parsed::unsupported_syntax_errors) will not

/// cause [`Err`] to be returned.

fn into_result(self) -> Result<Parsed<T>, ParseError> {

if self.has_valid_syntax() {

Ok(self)

} else {

Err(self.into_errors().into_iter().next().unwrap())

}

}

/// Attempts to convert the [`Parsed<Mod>`] into a [`Parsed<ModModule>`].

///

/// This method checks if the `syntax` field of the output is a [`Mod::Module`]. If it is, the

/// method returns [`Some(Parsed<ModModule>)`] with the contained module. Otherwise, it

/// returns [`None`].

///

/// [`Some(Parsed<ModModule>)`]: Some

pub fn try_into_module(self) -> Option<Parsed<ModModule>> {

match self.syntax {

Mod::Module(module) => Some(Parsed {

syntax: module,

tokens: self.tokens,

errors: self.errors,

unsupported_syntax_errors: self.unsupported_syntax_errors,

}),

Mod::Expression(_) => None,

}

}

/// Attempts to convert the [`Parsed<Mod>`] into a [`Parsed<ModExpression>`].

///

/// This method checks if the `syntax` field of the output is a [`Mod::Expression`]. If it is,

/// the method returns [`Some(Parsed<ModExpression>)`] with the contained expression.

/// Otherwise, it returns [`None`].

///

/// [`Some(Parsed<ModExpression>)`]: Some

fn try_into_expression(self) -> Option<Parsed<ModExpression>> {

match self.syntax {

Mod::Module(_) => None,

Mod::Expression(expression) => Some(Parsed {

syntax: expression,

tokens: self.tokens,

errors: self.errors,

unsupported_syntax_errors: self.unsupported_syntax_errors,

}),

}

}

/// Returns the module body contained in this parsed output as a [`Suite`].

pub fn suite(&self) -> &Suite {

&self.syntax.body

}

/// Consumes the [`Parsed`] output and returns the module body as a [`Suite`].

pub fn into_suite(self) -> Suite {

self.syntax.body

}

/// Returns the expression contained in this parsed output.

pub fn expr(&self) -> &Expr {

&self.syntax.body

}

/// Returns a mutable reference to the expression contained in this parsed output.

fn expr_mut(&mut self) -> &mut Expr {

&mut self.syntax.body

}

/// Consumes the [`Parsed`] output and returns the contained [`Expr`].

pub fn into_expr(self) -> Expr {

*self.syntax.body

}

/// The code consists of a sequence of statements.

Module,

/// The code consists of a single expression.

Expression,

/// The code consists of a single expression and is parsed as if it is parenthesized. The parentheses themselves aren't required.

/// This allows for having valid multiline expression without the need of parentheses

/// and is specifically useful for parsing string annotations.

ParenthesizedExpression,

/// The code consists of a sequence of statements which can include the

/// escape commands that are part of IPython syntax.

///

/// ## Supported escape commands:

///

/// - [Magic command system] which is limited to [line magics] and can start

/// with `?` or `??`.

/// - [Dynamic object information] which can start with `?` or `??`.

/// - [System shell access] which can start with `!` or `!!`.

/// - [Automatic parentheses and quotes] which can start with `/`, `;`, or `,`.

///

/// [Magic command system]: https://ipython.readthedocs.io/en/stable/interactive/reference.html#magic-command-system

/// [line magics]: https://ipython.readthedocs.io/en/stable/interactive/magics.html#line-magics

/// [Dynamic object information]: https://ipython.readthedocs.io/en/stable/interactive/reference.html#dynamic-object-information

/// [System shell access]: https://ipython.readthedocs.io/en/stable/interactive/reference.html#system-shell-access

/// [Automatic parentheses and quotes]: https://ipython.readthedocs.io/en/stable/interactive/reference.html#automatic-parentheses-and-quotes

Ipython,

type Err = ModeParseError;

fn from_str(s: &str) -> Result<Self, ModeParseError> {

match s {

"exec" | "single" => Ok(Mode::Module),

"eval" => Ok(Mode::Expression),

"ipython" => Ok(Mode::Ipython),

_ => Err(ModeParseError),

}

}

fn as_mode(&self) -> Mode {

match self {

PySourceType::Python | PySourceType::Stub => Mode::Module,

PySourceType::Ipynb => Mode::Ipython,

}

}

fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {

write!(f, r#"mode must be "exec", "eval", "ipython", or "single""#)

}