warnings

Documentation

Overview

Package warnings is the gopy port of cpython/Python/_warnings.c. v0.7 (1651-warn-A) lands the filter list, the default rule set, and the dispatch entry point _Py_Warn calls into. The per-module __warningregistry__ dedup follows in 1651-warn-B; the user-facing simplefilter / filterwarnings / resetwarnings API lands in 1651-warn-C.

CPython: Python/_warnings.c

Index

• Variables
• func Filterwarnings(action Action, message *regexp.Regexp, category *Category, ...) error
• func Insert(rule Filter)
• func IsWarning(err error) bool
• func Reset()
• func ResetRegistry()
• func Resetwarnings()
• func SetFilters(rules []Filter)
• func SetWriter(w io.Writer)
• func Simplefilter(action Action, category *Category, lineno int, appendRule bool) error
• func Warn(category *Category, message string) error
• func WarnAt(category *Category, message, module string, lineno int) error
• type Action
• type Category
  • func (c *Category) IsSubclass(other *Category) bool
• type ErrWarning
  • func (e *ErrWarning) Error() string
  • func (e *ErrWarning) Is(target error) bool
• type Filter
  • func Filters() []Filter

Variables

var (
	WarningCategory           = &Category{Name: "Warning"}
	UserWarning               = &Category{Name: "UserWarning", Parent: WarningCategory}
	DeprecationWarning        = &Category{Name: "DeprecationWarning", Parent: WarningCategory}
	PendingDeprecationWarning = &Category{Name: "PendingDeprecationWarning", Parent: WarningCategory}
	SyntaxWarning             = &Category{Name: "SyntaxWarning", Parent: WarningCategory}
	RuntimeWarning            = &Category{Name: "RuntimeWarning", Parent: WarningCategory}
	FutureWarning             = &Category{Name: "FutureWarning", Parent: WarningCategory}
	ImportWarning             = &Category{Name: "ImportWarning", Parent: WarningCategory}
	UnicodeWarning            = &Category{Name: "UnicodeWarning", Parent: WarningCategory}
	BytesWarning              = &Category{Name: "BytesWarning", Parent: WarningCategory}
	ResourceWarning           = &Category{Name: "ResourceWarning", Parent: WarningCategory}
	EncodingWarning           = &Category{Name: "EncodingWarning", Parent: WarningCategory}
)

The category singletons mirror Lib/warnings.py: every category inherits from Warning, with Pending and Deprecation being the hot ones for v0.7 because the eval loop emits both.

CPython: Lib/warnings.py module body

Functions

func Filterwarnings

func Filterwarnings(action Action, message *regexp.Regexp, category *Category, module *regexp.Regexp, lineno int, appendRule bool) error

Filterwarnings inserts a filter into the live list. With append false (the default), a duplicate is removed first and the new rule is prepended so it wins dispatch. With append true, the filter only lands at the tail when no equal entry already exists.

CPython: Lib/_py_warnings.py:254 filterwarnings

func Insert

func Insert(rule Filter)

Insert prepends a filter, matching simplefilter's semantics (most-recently-added wins). The registry purge keeps a fresh rule from being shadowed by stale dedup state.

CPython: Python/_warnings.c warnings_simple_filter

func IsWarning

func IsWarning(err error) bool

IsWarning returns true when err is a warning sentinel; the eval loop uses this to decide whether to translate the Go error into the matching Python exception.

CPython: Python/_warnings.c PyErr_WarnEx return-code branch

func Reset

func Reset()

Reset restores the seeded default filter list. Tests use it to undo filter mutations; the user-facing resetwarnings() lives in api.go and clears the list outright instead of restoring defaults.

CPython: Python/_warnings.c _PyWarnings_InitState seeded defaults

func ResetRegistry

func ResetRegistry()

ResetRegistry drops every per-module __warningregistry__ entry, forcing the next emission for any (module, action, category, message, lineno) shape to print again. Used by tests and by the C-level filters_mutated invalidation hook.

CPython: Python/_warnings.c warnings_filters_mutated registry purge

func Resetwarnings

func Resetwarnings()

Resetwarnings clears the filter list. Without any rules in place, findAction's no-entry fallback governs every emission, so the dedup state seeded under prior rules cannot silence a fresh warning.

CPython: Lib/_py_warnings.py:337 resetwarnings

func SetFilters

func SetFilters(rules []Filter)

SetFilters replaces the filter list atomically. The slice is copied so later mutations by the caller do not race with dispatch. The per-module registry is purged so dedup state cannot outlive the rule that produced it.

CPython: Python/_warnings.c warnings_filters_mutated

func SetWriter

func SetWriter(w io.Writer)

SetWriter installs the io.Writer used for non-ignore, non-error actions. Tests swap in a buffer; Py_Initialize wires sys.stderr.

CPython: Python/_warnings.c get_default_action implicit sys.stderr

func Simplefilter

func Simplefilter(action Action, category *Category, lineno int, appendRule bool) error

Simplefilter inserts a filter that matches every module and message, narrowing only on category and (optionally) line number.

CPython: Lib/_py_warnings.py:294 simplefilter

func Warn

func Warn(category *Category, message string) error

Warn is the primary entry point. Matches PyErr_WarnEx(category, message, stacklevel=1); the source-location lookup falls out of the caller-provided module/lineno pair the eval loop computes.

CPython: Python/_warnings.c:980 PyErr_WarnEx

func WarnAt

func WarnAt(category *Category, message, module string, lineno int) error

WarnAt is _Py_Warn's full surface: emit message under category from (module, lineno). The dedup hook (1651-warn-B) attaches here.

CPython: Python/_warnings.c:551 warn_explicit

Types

type Action

type Action string

Action names a filter outcome. Matches the Python-level action strings _PyWarnings_DefaultAction stamps onto each filter.

CPython: Python/_warnings.c:174 ACTION_*

const (
	// ActionError raises the warning as an exception.
	ActionError Action = "error"
	// ActionIgnore drops the warning silently.
	ActionIgnore Action = "ignore"
	// ActionAlways prints every emission.
	ActionAlways Action = "always"
	// ActionDefault prints once per (category, module, lineno).
	ActionDefault Action = "default"
	// ActionModule prints once per (category, module).
	ActionModule Action = "module"
	// ActionOnce prints once per (category, message).
	ActionOnce Action = "once"
)

type Category

type Category struct {
	Name   string
	Parent *Category
}

Category mirrors the PyWarning class hierarchy. The full Python class port lands with the type machinery; v0.7 uses a string hierarchy so DeprecationWarning subclasses Warning the same way the C source treats it.

CPython: Lib/warnings.py categories

func (*Category) IsSubclass

func (c *Category) IsSubclass(other *Category) bool

IsSubclass mirrors PyType_IsSubtype walking the parent chain.

CPython: Python/_warnings.c get_filter checks "issubclass(category, cat)"

type ErrWarning

type ErrWarning struct {
	Category *Category
	Message  string
	Module   string
	Lineno   int
}

ErrWarning is the sentinel returned when the matched filter is ActionError. Callers turn this into the right Python-level exception once the warning category port lands.

CPython: Python/_warnings.c:551 warn_explicit raises the category

func (*ErrWarning) Error

func (e *ErrWarning) Error() string

Error renders the sentinel into the "Module: Message" form PyErr_WarnEx ultimately formats.

func (*ErrWarning) Is

func (e *ErrWarning) Is(target error) bool

Is implements errors.Is. Two ErrWarning values match when their categories are equal; the message is data, not identity.

type Filter

type Filter struct {
	Action   Action
	Message  *regexp.Regexp
	Category *Category
	Module   *regexp.Regexp
	Lineno   int
}

Filter is one entry in the filter list. nil regexes match any value, and Lineno == 0 matches any line.

CPython: Python/_warnings.c init_filters tuple shape

func Filters

func Filters() []Filter

Filters returns a snapshot of the current filter list. The result shares no state with the live filter list; mutating the returned slice does not affect dispatch.

CPython: Python/_warnings.c get_warnings_filters