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; то же самое будет сделано для сетеров. Если ни геттер, ни сетер не существует, будет выброшено исключение.

Карта псевдонимов хранится как атрибут _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.

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

Параметры, отличные от 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, выдаётся предупреждение DeprecationWarning, и его значение используется, даже если new также передан по ключевому слову (это сделано для упрощения функций обёртки pyplot, которые всегда явно передают new методу Axes). Если 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, который пользователь может использовать вместо устаревшего 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')