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.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 для обработки вызовов функций с неправильными аргументами kwarg.

Параметры:

namestr

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

kwstr or 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, генерируется предупреждение 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')