matplotlib._api

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

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

matplotlib._api.caching_module_getattr(cls)[исходный код]

Вспомогательный декоратор для реализации __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)[исходный код]

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

Примеры

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

matplotlib._api.check_in_list(values, /, *, _print_supported_values=True, **kwargs)[исходный код]

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

Параметры:

valuesитерируемый объект

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

Примечание: все значения должны поддерживать сравнение с помощью ==. В частности, это означает, что элементы не должны быть массивами numpy.

_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)[исходный код]

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

В особом случае элемент None в types рассматривается как NoneType.

Примеры

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

matplotlib._api.check_shape(shape, /, **kwargs)[исходный код]

Для каждой пары ключ, значение в 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)[исходный код]

Базовые классы: object

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

Примеры

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

assert C.foo == "C"

propertyfget

matplotlib._api.define_aliases(alias_d, cls=None)[исходный код]

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

Используется следующим образом:

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

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

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

matplotlib._api.kwarg_error(name, kw)[исходный код]

Создаёт исключение TypeError для возбуждения при вызове функции с неверным именованным аргументом.

Параметры:

namestr

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

kwstr или Iterable[str]

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

matplotlib._api.nargs_error(name, takes, given)[исходный код]

Создаёт исключение TypeError для возбуждения при вызове функции с неверным количеством аргументов.

matplotlib._api.recursive_subclasses(cls)[исходный код]

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

matplotlib._api.select_matching_signature(funcs, *args, **kwargs)[исходный код]

Выбирает и вызывает функцию, принимающую *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)[исходный код]

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

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

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

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

exceptionmatplotlib._api.deprecation.MatplotlibDeprecationWarning[исходный код]

Базовые классы: DeprecationWarning

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

matplotlib._api.deprecation.delete_parameter(since, name, func=None, **kwargs)[исходный код]

Декоратор, указывающий, что параметр 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)[исходный код]

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

Параметры:

method

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

obj

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

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

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

**kwargs

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

classmatplotlib._api.deprecation.deprecate_privatize_attribute(*args, **kwargs)[исходный код]

Базовые классы: 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='')[исходный код]

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

При пометке classmethod, staticmethod или свойства как устаревшего декоратор @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)[исходный код]

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

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

matplotlib._api.deprecation.rename_parameter(since, old, new, func=None)[исходный код]

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

В фактической реализации func следует использовать new, а не old. Если в func передан old, выдаётся 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()[исходный код]

matplotlib._api.deprecation.warn_deprecated(since, *, message='', name='', alternative='', pending=False, obj_type='', addendum='', removal='')[исходный код]

Вывести стандартизированное предупреждение об устаревании.

Параметры:

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, вместо DeprecationWarning используется PendingDeprecationWarning. Нельзя использовать вместе с 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')