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.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 методу оси). Если 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')