errors

Documentation

Overview

Package errors holds the SyntaxError text panel and the helpers that turn (parser, token, message) into a structured *SyntaxError.

The constants below mirror the message strings emitted from cpython/Parser/pegen_errors.c. CPython freezes parser error text per release, so the goal here is byte-for-byte parity with 3.14: when a Python user feeds gopy a broken program, the SyntaxError they see should be indistinguishable from CPython's.

CPython: Parser/pegen_errors.c

Index

• Constants
• func ArgumentsParsingMsg(call *ast.Call) string
• func FindInvalidTarget(e ast.Expr, kind TargetKind) ast.Expr
• type Errcode
• type Kind
• type Pos
• type SyntaxError
  • func Build(kind Kind, filename string, pos Pos, msg string, args ...any) *SyntaxError
  • func FromTokenizer(code Errcode, filename string, pos Pos) *SyntaxError
  • func Raise(filename string, pos Pos, msg string, args ...any) *SyntaxError
  • func RaiseIndent(filename string, pos Pos, msg string, args ...any) *SyntaxError
  • func RaiseRange(filename string, start, end Pos, msg string, args ...any) *SyntaxError
  • func RaiseTab(filename string, pos Pos, msg string, args ...any) *SyntaxError
  • func UnclosedParen(filename string, pos Pos, opener byte) *SyntaxError
  • func (e *SyntaxError) Error() string
• type TargetKind

Constants

const (
	MsgUnexpectedIndent   = "unexpected indent"
	MsgUnexpectedUnindent = "unexpected unindent"
)

MsgUnexpectedIndent / MsgUnexpectedUnindent surface lexer-level indentation transitions that the grammar cannot accept.

CPython: Parser/pegen_errors.c:441 _Pypegen_set_syntax_error

const (
	MsgDecodeWrap    = "(%s) %s"
	MsgDecodeUnknown = "(%s) unknown error"
)

MsgDecodeError templates. The %s slot carries "unicode error" or "value error"; the trailing %s carries the underlying message.

CPython: Parser/pegen_errors.c:148 _Pypegen_raise_decode_error

const (
	MsgExpectedTok = "expected '%s'"
	MsgExpected    = "expected (%s)"
)

MsgExpected family. The forced-expect machinery in pegen.c uses MsgExpectedTok for single-character expectations and MsgExpected for multi-token alternatives.

CPython: Parser/pegen.c expect_forced_token

const (
	MsgMixedBytesLiterals    = "cannot mix bytes and nonbytes literals"
	MsgImaginaryRequired     = "imaginary number required in complex literal"
	MsgRealRequired          = "real number required in complex literal"
	MsgNumericUnderscore     = "Underscores in numeric literals are only supported in Python 3.6 and greater"
	MsgBarryAsBDFL           = "with Barry as BDFL, use '<>' instead of '!='"
	MsgMultipleStmtsInteract = "multiple statements found while compiling a single statement"
)

Numeric and string literal complaints raised from the post-tokenization pass.

CPython: Parser/string_parser.c and Parser/action_helpers.c

const (
	MsgCannotAssignTo       = "cannot assign to %s"
	MsgCannotDelete         = "cannot delete %s"
	MsgCannotAssignToWalrus = "cannot use assignment expressions with %s"
)

Assignment-target diagnostics. The %s slot carries a phrase like "literal", "function call", or "f-string expression".

CPython: Parser/action_helpers.c _PyPegen_get_invalid_target

const (
	MsgWalrusInComp          = "assignment expression cannot be used in a comprehension iterable expression"
	MsgStarOutsideFunction   = "can't use starred expression here"
	MsgYieldOutsideFunction  = "'yield' outside function"
	MsgReturnOutsideFunction = "'return' outside function"
	MsgAwaitOutsideFunction  = "'await' outside function"
	MsgAwaitOutsideAsync     = "'await' outside async function"
)

Walrus / star / yield placement errors.

CPython: Parser/parser.c invalid_* rules

const (
	MsgFStringExprEmpty     = "f-string: empty expression not allowed"
	MsgFStringExprBackslash = "f-string expression part cannot include a backslash"
	MsgFStringExprComment   = "f-string expression part cannot include '#'"
	MsgFStringSingleBrace   = "f-string: single '}' is not allowed"
	MsgFStringUnterminated  = "f-string: unterminated string"
	MsgFStringExprNesting   = "f-string: expressions nested too deeply"
	MsgFStringInvalidConv   = "f-string: invalid conversion character %c: expected 's', 'r', or 'a'"
	MsgFStringMissingRBrace = "f-string: expecting '}'"
	MsgTStringExprEmpty     = "t-string: empty expression not allowed"
	MsgTStringExprBackslash = "t-string expression part cannot include a backslash"
	MsgTStringExprComment   = "t-string expression part cannot include '#'"
	MsgTStringSingleBrace   = "t-string: single '}' is not allowed"
	MsgTStringUnterminated  = "t-string: unterminated string"
)

f-string and t-string structural errors. CPython's tokenizer surfaces most of these via lexer_error; the parser side wraps them.

CPython: Parser/lexer/lexer.c tok_get_fstring_mode

const (
	MsgDidYouMeanWalrus = "did you mean ':='?"
	MsgPrintParens      = "Missing parentheses in call to 'print'. Did you mean print(...)?"
	MsgExecParens       = "Missing parentheses in call to 'exec'. Did you mean exec(...)?"
)

Suggestion-style hints that pegen emits inline. The richer "did you mean ...?" surface lives in errors/suggest (1611).

CPython: Parser/pegen.c suggestion arms

const (
	MsgPositionalAfterStar     = "positional argument follows keyword argument"
	MsgPositionalAfterUnpack   = "positional argument follows keyword argument unpacking"
	MsgIterableUnpackInComp    = "iterable unpacking cannot be used in comprehension"
	MsgGeneratorInCallNoParens = "Generator expression must be parenthesized"
	MsgArgsAfterStarStar       = "argument cannot follow '**' expansion"
	MsgKeywordExpression       = "expression cannot contain assignment, perhaps you meant \"==\"?"
	MsgDuplicateArgument       = "duplicate argument '%s' in function definition"
	MsgNonDefaultAfterDefault  = "non-default argument follows default argument"
	MsgStarAfterStar           = "* argument may appear only once"
	MsgNamedExprWithoutTarget  = "named expression must be parenthesized in this context"
)

Function/class signature errors raised from the invalid_ rules.

CPython: Parser/parser.c invalid_arguments / invalid_parameters

const (
	MsgMatchSubjectMustEnd        = "expected ':'"
	MsgPatternCaptureClassPattern = "patterns may only match attributes (got %s)"
	MsgMatchClassDoubleKeyword    = "attribute name repeated in class pattern: %s"
	MsgMatchMappingDoubleKey      = "mapping pattern checks duplicate key (%s)"
	MsgMatchStarPlacement         = "starred pattern must end the sequence"
	MsgMatchStarMultiple          = "multiple starred names in sequence pattern"
)

match-statement errors. PEP 634 added the structural-pattern matching diagnostics surfaced from the invalid_pattern rules.

CPython: Parser/parser.c invalid_match_stmt

const (
	MsgImportFromStarLevel = "from __future__ imports must occur at the beginning of the file"
	MsgImportTrailingComma = "trailing comma not allowed without surrounding parentheses"
)

import / from-import diagnostics.

CPython: Parser/parser.c invalid_import_from

const (
	MsgUnterminatedString       = "unterminated string literal (detected at line %d)"
	MsgUnterminatedTripleString = "unterminated triple-quoted string literal (detected at line %d)"
	MsgUnterminatedFString      = "unterminated %c-string literal (detected at line %d)"
	MsgUnterminatedTripleFStr   = "unterminated triple-quoted %c-string literal (detected at line %d)"
)

Unterminated string literal diagnostics. The single %d slot is the line on which the literal opened. The %c slot in the f / t variants is 'f' or 't'.

CPython: Parser/lexer/lexer.c:1196 / :1207 / :1213 / :1502 / :1512

const (
	MsgTypeParamsEmpty       = "Type parameter list cannot be empty"
	MsgTypeVarTupleConstrain = "cannot use constraints with TypeVarTuple"
	MsgTypeVarTupleBound     = "cannot use bound with TypeVarTuple"
)

PEP 695 type-parameter diagnostics. Surfaced from the invalid_type_params / type_param_bound second-pass rules.

CPython: Parser/parser.c:21222 invalid_type_param, Parser/parser.c:27250 invalid_type_params

const MsgColumnOverflow = "Parser column offset overflow - source line is too big"

MsgColumnOverflow is the OverflowError raised when a source line exceeds the column-offset range the parser tracks.

CPython: Parser/pegen_errors.c:117 E_COLUMNOVERFLOW case

const MsgErrorAtStart = "error at start before reading any input"

MsgErrorAtStart is raised when fill is zero and we already need to surface a SyntaxError. The location is (0, 0).

CPython: Parser/pegen_errors.c:428 _Pypegen_set_syntax_error

const MsgInconsistentDedent = "unindent does not match any outer indentation level"

MsgInconsistentDedent is raised when a DEDENT does not line up with any prior INDENT level.

CPython: Parser/pegen_errors.c:92 E_DEDENT case

const MsgInvalidSyntax = "invalid syntax"

MsgInvalidSyntax is the generic fallback raised when no rule in the second-pass invalid grammar matches.

CPython: Parser/pegen_errors.c:450 RAISE_SYNTAX_ERROR_KNOWN_LOCATION

const MsgInvalidToken = "invalid token"

MsgInvalidToken is the catch-all for E_TOKEN.

CPython: Parser/pegen_errors.c:82 E_TOKEN case

const MsgLineCont = "unexpected character after line continuation character"

MsgLineCont fires when a backslash-newline is followed by something other than the next physical line.

CPython: Parser/pegen_errors.c:112 E_LINECONT case

const MsgStackOverflow = "Parser stack overflowed - Python source too complex to parse"

MsgStackOverflow is the MemoryError raised when the recursion limit guard trips inside the generated parser.

CPython: Parser/pegen_errors.c:460 _Pypegen_stack_overflow

const MsgTabSpace = "inconsistent use of tabs and spaces in indentation"

MsgTabSpace is the TabError message for mixed tabs and spaces.

CPython: Parser/pegen_errors.c:104 E_TABSPACE case

const MsgTooDeep = "too many levels of indentation"

MsgTooDeep is the IndentationError raised at maxIndent.

CPython: Parser/pegen_errors.c:108 E_TOODEEP case

const MsgUnclosedParen = "'%c' was never closed"

MsgUnclosedParen is the "'%c' was never closed" template. The single byte is the offending opener (one of '(', '[', '{').

CPython: Parser/pegen_errors.c:65 raise_unclosed_parentheses_error

const MsgUnexpectedEOF = "unexpected EOF while parsing"

MsgUnexpectedEOF fires when the parser hits EOF mid-statement and the lexer is not inside an unmatched paren.

CPython: Parser/pegen_errors.c:88 _Pypegen_tokenizer_error E_EOF case

const MsgUnknownParseError = "unknown parsing error"

MsgUnknownParseError is the default-arm fallback in _Pypegen_tokenizer_error when no E_* code matches.

CPython: Parser/pegen_errors.c:120 default case

const NonparenGenexpInCallMsg = "Generator expression must be parenthesized"

NonparenGenexpInCallMsg is the diagnostic the parser raises when a generator expression is used as the only positional argument in a call without surrounding parentheses, e.g. `f(x for x in y, 1)`.

CPython: Parser/action_helpers.c:1243 _PyPegen_nonparen_genexp_in_call

Functions

func ArgumentsParsingMsg

func ArgumentsParsingMsg(call *ast.Call) string

ArgumentsParsingMsg returns the message the second-pass invalid rule emits when arguments are mis-ordered. The choice between the two phrasings is driven by whether any kwarg in the call is `**kwargs` (kwarg unpacking) versus a plain `name=value`.

CPython: Parser/action_helpers.c:1224 _PyPegen_arguments_parsing_error

func FindInvalidTarget

func FindInvalidTarget(e ast.Expr, kind TargetKind) ast.Expr

FindInvalidTarget walks an expression that was used as an assignment target and returns the first sub-expression that is not a legal target. Returns nil when the whole tree is valid.

CPython: Parser/action_helpers.c:1167 _PyPegen_get_invalid_target

Types

type Errcode

type Errcode int

Errcode is the lexer-side done state. Values match Parser/lexer/state.h's E_* family in order. The lexer package keeps its own typed alias; this one lets the errors package stay independent of the lexer import graph.

const (
	ErrOK Errcode = iota
	ErrEOF
	ErrIntr
	ErrToken
	ErrSyntax
	ErrIndent
	ErrDedent
	ErrTabSpace
	ErrOverflow
	ErrDecode
	ErrEOFS
	ErrEOLS
	ErrErrLine
	ErrBadVisibility
	ErrEncoding
	ErrColumnOverflow
)

Errcode values. The order matches lexer.errCode so a numeric cast is safe both ways.

type Kind

type Kind int

Kind names the SyntaxError subclass the parser would have raised in CPython. The compile pipeline lifts this onto the matching Go error type.

CPython: Parser/pegen_errors.c errtype argument family

const (
	KindSyntax Kind = iota
	KindIndentation
	KindTab
	KindMemory
	KindOverflow
	KindUnicode
	KindValue
)

Kind values. Default is plain SyntaxError; the indent / tab variants line up with IndentationError and TabError.

type Pos

type Pos struct {
	Lineno  int
	ColOff  int
	EndLine int
	EndCol  int
}

Pos pairs a 1-based line with a 0-based byte column. Negative EndCol means "end of line", matching CPython's -1 sentinel.

CPython: Parser/pegen.h Token col_offset / end_col_offset

type SyntaxError

type SyntaxError struct {
	Kind     Kind
	Pos      Pos
	Filename string
	Message  string
	Text     string
}

SyntaxError is the structured record the parser hands back. The pegen runtime promotes the first one set on a Parser into the caller's *SyntaxError.

CPython: Include/cpython/pyerrors.h PySyntaxErrorObject

func Build

func Build(kind Kind, filename string, pos Pos, msg string, args ...any) *SyntaxError

Build is the worker behind every raise_*. It formats msg with args, stamps the location and filename, and returns the record.

CPython: Parser/pegen_errors.c:317 _PyPegen_raise_error_known_location

func FromTokenizer

func FromTokenizer(code Errcode, filename string, pos Pos) *SyntaxError

FromTokenizer maps a lexer errcode into the matching SyntaxError record. The (lineno, col) pair comes from the tokenizer; the filename is forwarded from the Parser. Returns nil for codes that do not raise a SyntaxError on their own (E_OK, E_EOF when level is zero is handled by the caller, etc.).

CPython: Parser/pegen_errors.c:69 _Pypegen_tokenizer_error switch

func Raise

func Raise(filename string, pos Pos, msg string, args ...any) *SyntaxError

Raise builds a plain SyntaxError at pos.

CPython: Parser/pegen_errors.c:228 _PyPegen_raise_error

func RaiseIndent

func RaiseIndent(filename string, pos Pos, msg string, args ...any) *SyntaxError

RaiseIndent builds an IndentationError.

CPython: Parser/pegen.h RAISE_INDENTATION_ERROR

func RaiseRange

func RaiseRange(filename string, start, end Pos, msg string, args ...any) *SyntaxError

RaiseRange is the explicit-span builder used when the second-pass invalid grammar pinpoints a token range.

CPython: Parser/pegen.h RAISE_SYNTAX_ERROR_KNOWN_RANGE

func RaiseTab

func RaiseTab(filename string, pos Pos, msg string, args ...any) *SyntaxError

RaiseTab builds a TabError.

CPython: Parser/pegen_errors.c:103 E_TABSPACE arm

func UnclosedParen

func UnclosedParen(filename string, pos Pos, opener byte) *SyntaxError

UnclosedParen is the dedicated builder for the lexer's level>0 EOF arm. The caller already knows which paren character was open.

CPython: Parser/pegen_errors.c:60 raise_unclosed_parentheses_error

func (*SyntaxError) Error

func (e *SyntaxError) Error() string

Error renders the bare message. The "File ..., line N" envelope is added by the caller because gopy keeps filename and line out of the message body.

type TargetKind

type TargetKind int

TargetKind tags the assignment-target context so the diagnostic helper knows which sub-expressions are legal.

CPython: Parser/pegen.h TARGETS_TYPE

const (
	StarTargets TargetKind = iota
	DelTargets
	ForTargets
)

Target kinds. Star targets are LHS of `=`; del targets are after `del`; for targets sit between `for ... in`.