matplotlib._api

Вспомогательные функции для управления API Matplotlib.

Данная документация предназначена только для разработчиков Matplotlib, а не для пользователей.

matplotlib._api.caching_module_getattr(cls)[source]

Вспомогательный декоратор для реализации модульных __getattr__ как класса.

Этот декоратор должен использоваться на уровне модуля следующим образом:

@caching_module_getattr
class __getattr__:  # The class *must* be named ``__getattr__``.
    @property  # Only properties are taken into account.
    def name(self): ...

Класс __getattr__ будет заменён функцией __getattr__, так что попытка обратиться к name в модуле вызовет соответствующее свойство (которое может быть дополнительно декорировано, например, _api.deprecated для устаревания глобальных переменных модуля). Свойства неявно кешируются. Кроме того, будет сгенерировано и выброшено соответствующее исключение AttributeError, если свойство с заданным именем не существует.

matplotlib._api.check_getitem(mapping, /, **kwargs)[source]

kwargs должны состоять из единственной пары ключ, значение. Если ключ содержится в mapping, вернуть mapping[value]; в противном случае, выбросить соответствующее исключение ValueError.

Примеры

>>> _api.check_getitem({"foo": "bar"}, arg=arg)

matplotlib._api.check_in_list(values, /, *, _print_supported_values=True, **kwargs)[source]

Для каждой пары ключ, значение в kwargs, проверить, что значение находится в values; если нет, выбросить соответствующее исключение ValueError.

Параметры:

valuesiterable

Последовательность значений для проверки.

_print_supported_valuesbool, по умолчанию: True

Выводить values при вызове ValueError.

**kwargsdict

Пары ключ, значение в виде ключевых аргументов для поиска в values.

Исключения:

ValueError

Если какое-либо значение в kwargs не найдено в values.

Примеры

>>> _api.check_in_list(["foo", "bar"], arg=arg, other_arg=other_arg)

matplotlib._api.check_isinstance(types, /, **kwargs)[source]

Для каждой пары ключ, значение в kwargs, проверить, что значение является экземпляром одного из типов types; если нет, выбросить соответствующее исключение TypeError.

В качестве специального случая запись None в types обрабатывается как NoneType.

Примеры

>>> _api.check_isinstance((SomeClass, None), arg=arg)

matplotlib._api.check_shape(shape, /, **kwargs)[source]

Для каждой пары ключ, значение в kwargs, проверить, что значение имеет форму shape; если нет, выбросить соответствующее исключение ValueError.

None в форме обрабатывается как «свободный» размер, который может иметь любую длину. Например, (None, 2) -> (N, 2)

Проверяемые значения должны быть массивами numpy.

Примеры

Для проверки массивов формы (N, 2)

>>> _api.check_shape((None, 2), arg=arg, other_arg=other_arg)

classmatplotlib._api.classproperty(fget, fset=None, fdel=None, doc=None)[source]

Базы: object

Как property, но также срабатывает при доступе через класс, и в качестве аргумента передаётся класс.

Примеры

class C:
    @classproperty
    def foo(cls):
        return cls.__name__

assert C.foo == "C"

propertyfget

matplotlib._api.define_aliases(alias_d, cls=None)[source]

Декоратор класса для определения псевдонимов свойств.

Используется как

@_api.define_aliases({"property": ["alias", ...], ...})
class C: ...

Для каждого свойства, если соответствующий get_property определён в классе до этого момента, будет определён псевдоним под названием get_alias; то же самое будет сделано для установщиков. Если ни getter, ни setter не существуют, будет выброшено исключение.

Карта псевдонимов сохраняется как атрибут _alias_map в классе и может быть использована методом normalize_kwargs (который предполагает, что псевдонимы с более высоким приоритетом идут последними).

matplotlib._api.kwarg_error(name, kw)[source]

Генерирует TypeError, который будет поднят при вызовах функций с неправильными ключевыми аргументами.

Параметры:

namestr

Имя вызываемой функции.

kwstr или Iterable[str]

Имя недействительного ключевого аргумента или итерируемый объект, возвращающий недействительные ключевые аргументы (например, словарь kwargs)

matplotlib._api.nargs_error(name, takes, given)[source]

Генерирует TypeError, который будет поднят при вызовах функций с неправильным количеством аргументов.

matplotlib._api.recursive_subclasses(cls)[source]

Возвращает cls и прямых и косвенных подклассы cls.

matplotlib._api.select_matching_signature(funcs, *args, **kwargs)[source]

Выберите и вызовите функцию, которая принимает *args, **kwargs.

funcs — список функций, которые не должны вызывать никаких исключений (кроме TypeError, если переданные аргументы не соответствуют их сигнатуре).

select_matching_signature пытается вызвать каждую из функций в funcs с *args, **kwargs (в порядке, в котором они даны). Вызовы, которые завершаются ошибкой TypeError, пропускаются без сообщений об ошибке. Как только вызов завершится успешно, select_matching_signature возвращает его возвращаемое значение. Если ни одна функция не принимает *args, **kwargs, то TypeError, сгенерированная последним неудачным вызовом, перевызывается.

Как правило, вызывающие стороны должны убедиться, что любой *args, **kwargs может связывать только одну func (чтобы избежать неоднозначности), хотя select_matching_signature это не проверяет.

Примечания

select_matching_signature предназначена для реализации функций с перегрузкой сигнатуры. В общем случае такие функции следует избегать, за исключением случаев обратной совместимости. Типичный шаблон использования:

def my_func(*args, **kwargs):
    params = select_matching_signature(
        [lambda old1, old2: locals(), lambda new: locals()],
        *args, **kwargs)
    if "old1" in params:
        warn_deprecated(...)
        old1, old2 = params.values()  # note that locals() is ordered.
    else:
        new, = params.values()
    # do things with params

что позволяет my_func вызываться либо с двумя параметрами (old1 и old2), либо с одним (new). Обратите внимание, что новая сигнатура указывается последней, так что вызывающие стороны получают TypeError, соответствующую новой сигнатуре, если переданные ими аргументы не соответствуют ни одной сигнатуре.

matplotlib._api.warn_external(message, category=None)[source]

Обёртка warnings.warn, которая устанавливает stacklevel во «вне Matplotlib».

Исходный источник предупреждения можно получить, заменив эту функцию обратно на warnings.warn, то есть _api.warn_external = warnings.warn (или functools.partial(warnings.warn, stacklevel=2), и т.д.).

Вспомогательные функции для устаревания частей API Matplotlib.

Это описание актуально только для разработчиков Matplotlib, а не для пользователей.

исключениеmatplotlib._api.deprecation.MatplotlibDeprecationWarning[source]

Основан на DeprecationWarning

Класс для выдачи предупреждений об устаревании для пользователей Matplotlib.

matplotlib._api.deprecation.delete_parameter(since, name, func=None, **kwargs)[source]

Декоратор, указывающий на устаревание параметра name функции func.

Фактическая реализация func должна сохранять параметр name в своей сигнатуре или принимать аргумент **kwargs (через который name будет передан).

Параметры, которые следуют за устаревающим параметром, фактически становятся только именованными (поскольку их нельзя передать позиционно без срабатывания предупреждения об устаревании для устаревшего параметра) и должны быть помечены как таковые после того, как период устаревания прошёл, и устаревший параметр удалён.

Параметры, отличные от since, name и func, являются только именованными и передаются в warn_deprecated.

Примеры

@_api.delete_parameter("3.1", "unused")
def func(used_arg, other_arg, unused, more_args): ...

matplotlib._api.deprecation.deprecate_method_override(method, obj, *, allow_empty=False, **kwargs)[source]

Возвращает obj.method с предупреждением об устаревании, если оно переопределено, иначе None.

Параметры:

method

Несвязанный метод, т.е. выражение вида Class.method_name. Помните, что внутри тела метода всегда можно использовать __class__ для обращения к классу, который в данный момент определён.

obj

Объект класса, в котором определён method, или подкласс этого класса.

allow_emptybool, по умолчанию: False

Разрешить переопределения пустым методами без вывода предупреждения.

**kwargs

Дополнительные параметры, передаваемые в warn_deprecated для генерации предупреждения об устаревании; обязательно должен содержать ключ "since".

классmatplotlib._api.deprecation.deprecate_privatize_attribute(*args, **kwargs)[source]

Основан на object

Вспомогательная функция для устаревания публичного доступа к атрибуту (или методу).

Эта вспомогательная функция должна использоваться только на уровне класса, как показано ниже:

class Foo:
    attr = _deprecate_privatize_attribute(*args, **kwargs)

где все параметры передаются в deprecated. Эта форма делает attr свойством, которое перенаправляет чтение и запись на self._attr (то же имя, но с ведущей подчёркивающей чертой), с предупреждением об устаревании. Обратите внимание, что имя атрибута выводится из имени, присвоенному этому вспомогательному средству. Эта вспомогательная функция также работает для устаревания методов.

matplotlib._api.deprecation.deprecated(since, *, message='', name='', alternative='', pending=False, obj_type=None, addendum='', removal='')[source]

Декоратор для маркировки функции, класса или свойства как устаревшего.

При устаревании метода класса, статического метода или свойства, декоратор @deprecated должен располагаться под @classmethod и @staticmethod (т.е., deprecated должен напрямую декорировать базовую вызываемую функцию), но над @property.

При устаревании класса C предназначенного для использования в качестве базового класса в иерархии множественного наследования, C обязательно должен определять метод __init__ (если C вместо этого унаследовал свой __init__ от собственного базового класса, то @deprecated нарушит наследование __init__ при установке собственного (генерирующего предупреждения об устаревании) C.__init__).

Параметры такие же, как и для warn_deprecated, за исключением того, что obj_type по умолчанию устанавливается в 'class', если декорируется класс, 'attribute', если декорируется свойство, и 'function' в противном случае.

Примеры

@deprecated('1.4.0')
def the_function_to_deprecate():
    pass

matplotlib._api.deprecation.make_keyword_only(since, name, func=None)[source]

Декоратор, указывающий, что передача параметра name (или любого из следующих) позиционно в func устаревает.

При использовании на методе, который имеет обертку pyplot, этот декоратор должен быть самым внешним, чтобы boilerplate.py мог получить доступ к исходной сигнатуре.

matplotlib._api.deprecation.rename_parameter(since, old, new, func=None)[source]

Декоратор, указывающий, что параметр old функции func переименовывается в new.

Фактическая реализация func должна использовать new, а не old. Если old передаётся в func, генерируется предупреждение о устаревании, и его значение используется, даже если new также передан по ключевому слову (это упрощает функции обёрток pyplot, которые всегда явно передают new методу оси). Если new также передаётся, но позиционно, подлежащая функция вызовет TypeError при связывании аргументов.

Примеры

@_api.rename_parameter("3.1", "bad_name", "good_name")
def func(good_name): ...

matplotlib._api.deprecation.suppress_matplotlib_deprecation_warning()[source]

matplotlib._api.deprecation.warn_deprecated(since, *, message='', name='', alternative='', pending=False, obj_type='', addendum='', removal='')[source]

Отображение стандартизированного предупреждения об устаревании.

Параметры:

sincestr

Версия, в которой этот API стал устаревшим.

messagestr, optional

Замена стандартного сообщения об устаревании. Значения форматов %(since)s, %(name)s, %(alternative)s, %(obj_type)s, %(addendum)s, и %(removal)s будут заменены соответствующими аргументами, переданными в эту функцию.

namestr, optional

Имя устаревшего объекта.

alternativestr, optional

Альтернативный API, который пользователь может использовать вместо устаревшего. Предупреждение об устаревании сообщит пользователю об этой альтернативе, если она указана.

pendingbool, optional

Если True, используется PendingDeprecationWarning вместо DeprecationWarning. Не может быть использовано вместе с removal.

obj_typestr, optional

Тип объекта, который устарел.

addendumstr, optional

Дополнительный текст, добавленный непосредственно к окончательному сообщению.

removalstr, optional

Ожидаемая версия удаления. По умолчанию (пустая строка), версия удаления автоматически вычисляется из since. Установите в другое ложное значение, чтобы не устанавливать дату удаления. Не может быть использовано вместе с pending.

Примеры

# To warn of the deprecation of "matplotlib.name_of_module"
warn_deprecated('1.4.0', name='matplotlib.name_of_module',
                obj_type='module')