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.

Параметры

_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.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]

Bases: 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]

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

Параметры такие же, как для 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.mplDeprecation[source]

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

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

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

Фактическая реализация func должна использовать new, а не old. Если old передается в func, выдается предупреждение о устаревании, и его значение используется, даже если 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()

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