matplotlib._api

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

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

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.

Параметры:	_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)

class matplotlib._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"

property fget

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, а не для пользователей.

exception matplotlib._api.deprecation.MatplotlibDeprecationWarning[source]

Наследуется от UserWarning

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

Ввиду того, что встроенные предупреждения о устаревании Python по умолчанию игнорируются начиная с Python 2.7 (см. ссылку ниже), этот класс был создан для сигнализации об устаревании, но через UserWarning, которые по умолчанию не игнорируются.

https://docs.python.org/dev/whatsnew/2.7.html#the-future-for-python-2-x

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".

class matplotlib._api.deprecation.deprecate_privatize_attribute(*args, **kwargs)[source]

Bases: 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__).

Параметры:

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.

Примеры

Базовый пример:

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

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

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

matplotlib._api.deprecation.mplDeprecation

Псевдоним matplotlib._api.deprecation.MatplotlibDeprecationWarning

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')