`matplotlib._api`#

Hilfsfunktionen zur Verwaltung der Matplotlib API.

Diese Dokumentation ist nur für Matplotlib-Entwickler relevant, nicht für Benutzer.

Warnung

Dieses Modul und seine Untermodule sind nur für den internen Gebrauch bestimmt. Verwenden Sie sie nicht in Ihrem eigenen Code. Wir können die API jederzeit ohne Vorwarnung ändern.

matplotlib._api.caching_module_getattr(cls)[Quelle]#

Hilfsdekulator zur Implementierung von Modul-Level __getattr__ als Klasse.

Dieser Dekulator muss auf der obersten Ebene des Moduls wie folgt verwendet werden:

@caching_module_getattr
class __getattr__:  # The class *must* be named ``__getattr__``.
    @property  # Only properties are taken into account.
    def name(self): ...

Die __getattr__-Klasse wird durch eine __getattr__-Funktion ersetzt, sodass Zugriffsversuche auf name im Modul die entsprechende Eigenschaft auflösen (die z. B. mit _api.deprecated zur Deprezierung von Modul-Globalen dekoriert sein kann). Die Eigenschaften sind alle implizit zwischengespeichert. Darüber hinaus wird ein geeigneter AttributeError generiert und ausgelöst, wenn keine Eigenschaft mit dem angegebenen Namen existiert.

matplotlib._api.check_getitem(mapping, /, **kwargs)[Quelle]#

kwargs muss aus einem einzelnen Schlüssel, Wert-Paar bestehen. Wenn Schlüssel in mapping enthalten ist, wird mapping[Wert] zurückgegeben; andernfalls wird ein geeigneter ValueError ausgelöst.

Beispiele

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

matplotlib._api.check_in_list(values, /, *, _print_supported_values=True, **kwargs)[Quelle]#

Für jedes Schlüssel, Wert-Paar in kwargs wird geprüft, ob Wert in values enthalten ist; wenn nicht, wird ein geeigneter ValueError ausgelöst.

Parameter:

valuesiterable: Sequenz von zu prüfenden Werten.
_print_supported_valuesbool, Standard: True: Ob values beim Auslösen von ValueError gedruckt werden sollen.
**kwargsdict: Schlüssel, Wert-Paare als Schlüsselwortargumente, die in values gesucht werden sollen.

Löst aus:

ValueError: Wenn ein Wert in kwargs nicht in values gefunden wird.

Beispiele

>>> _api.check_in_list(["foo", "bar"], arg=arg, other_arg=other_arg)

matplotlib._api.check_isinstance(types, /, **kwargs)[Quelle]#

Für jedes Schlüssel, Wert-Paar in kwargs wird geprüft, ob Wert eine Instanz von einem der types ist; wenn nicht, wird ein geeigneter TypeError ausgelöst.

Als Sonderfall wird ein None-Eintrag in types als NoneType behandelt.

Beispiele

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

matplotlib._api.check_shape(shape, /, **kwargs)[Quelle]#

Für jedes Schlüssel, Wert-Paar in kwargs wird geprüft, ob Wert die Form shape hat; wenn nicht, wird ein geeigneter ValueError ausgelöst.

None in der Form wird als "freie" Größe behandelt, die jede Länge haben kann. z. B. (None, 2) -> (N, 2)

Die geprüften Werte müssen numpy-Arrays sein.

Beispiele

Zur Prüfung auf Arrays der Form (N, 2)

>>> _api.check_shape((None, 2), arg=arg, other_arg=other_arg)

class matplotlib._api.classproperty(fget, fset=None, fdel=None, doc=None)[Quelle]#

Bases: object

Wie property, aber löst auch beim Zugriff über die Klasse aus, und es ist die Klasse, die als Argument übergeben wird.

Beispiele

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

assert C.foo == "C"

property fget#

matplotlib._api.define_aliases(alias_d, cls=None)[Quelle]#

Klassendekulator zur Definition von Eigenschafts-Aliassen.

Verwendung wie:

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

Für jede Eigenschaft wird, wenn die entsprechende get_property bisher in der Klasse definiert ist, ein Alias namens get_alias definiert; dasselbe geschieht für Setter. Wenn weder der Getter noch der Setter existiert, wird eine Ausnahme ausgelöst.

Die Alias-Map wird als Attribut _alias_map auf der Klasse gespeichert und kann von normalize_kwargs verwendet werden (die davon ausgeht, dass höher priorisierte Aliase zuletzt kommen).

matplotlib._api.kwarg_error(name, kw)[Quelle]#

Generiert einen TypeError, der bei Funktionsaufrufen mit falschem kwarg ausgelöst werden soll.

Parameter:

namestr: Der Name der aufrufenden Funktion.
kwstr oder Iterable[str]: Entweder der ungültige Schlüsselwortargumentname oder ein Iterable, das ungültige Schlüsselwortargumente liefert (z. B. ein kwargs-Dictionary).

matplotlib._api.nargs_error(name, takes, given)[Quelle]#: Generiert einen TypeError, der bei Funktionsaufrufen mit falscher Arität ausgelöst werden soll.

matplotlib._api.recursive_subclasses(cls)[Quelle]#: Gibt cls sowie direkte und indirekte Unterklassen von cls zurück.

matplotlib._api.select_matching_signature(funcs, *args, **kwargs)[Quelle]#

Wählt und ruft die Funktion auf, die *args, **kwargs akzeptiert.

funcs ist eine Liste von Funktionen, die keine Ausnahmen auslösen dürfen (außer TypeError, wenn die übergebenen Argumente nicht ihrer Signatur entsprechen).

select_matching_signature versucht, jede der Funktionen in funcs mit *args, **kwargs aufzurufen (in der Reihenfolge, in der sie angegeben sind). Aufrufe, die mit einem TypeError fehlschlagen, werden stillschweigend übersprungen. Sobald ein Aufruf erfolgreich ist, gibt select_matching_signature dessen Rückgabewert zurück. Wenn keine Funktion *args, **kwargs akzeptiert, wird der von dem letzten fehlgeschlagenen Aufruf ausgelöste TypeError erneut ausgelöst.

Aufrufer sollten normalerweise sicherstellen, dass *args, **kwargs nur eine einzige func binden kann (um Mehrdeutigkeiten zu vermeiden), obwohl dies von select_matching_signature nicht geprüft wird.

Anmerkungen

select_matching_signature dient zur Implementierung von signaturüberladenen Funktionen. Im Allgemeinen sollten solche Funktionen vermieden werden, außer aus Gründen der Abwärtskompatibilität. Ein typisches Nutzungsmuster ist:

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

was es my_func erlaubt, entweder mit zwei Parametern (old1 und old2) oder einem einzigen (new) aufgerufen zu werden. Beachten Sie, dass die neue Signatur zuletzt angegeben wird, damit Aufrufer einen TypeError erhalten, der der neuen Signatur entspricht, wenn die übergebenen Argumente keiner Signatur entsprechen.

matplotlib._api.warn_external(message, category=None)[Quelle]#

Wrapper für warnings.warn, der stacklevel auf "außerhalb von Matplotlib" setzt.

Der ursprüngliche Emittent der Warnung kann durch Patchen dieser Funktion zurück auf warnings.warn erhalten werden, d.h. _api.warn_external = warnings.warn (oder functools.partial(warnings.warn, stacklevel=2), etc.).

Hilfsfunktionen zur Deprezierung von Teilen der Matplotlib API.

Diese Dokumentation ist nur für Matplotlib-Entwickler relevant, nicht für Benutzer.

Warnung

Dieses Modul ist nur für den internen Gebrauch bestimmt. Verwenden Sie es nicht in Ihrem eigenen Code. Wir können die API jederzeit ohne Vorwarnung ändern.

exception matplotlib._api.deprecation.MatplotlibDeprecationWarning[Quelle]#

Basis: DeprecationWarning

Eine Klasse zur Ausgabe von Deprezierungswarnungen für Matplotlib-Benutzer.

matplotlib._api.deprecation.delete_parameter(since, name, func=None, **kwargs)[Quelle]#

Dekulator, der angibt, dass der Parameter name von func depreziert wird.

Die tatsächliche Implementierung von func sollte den name-Parameter in seiner Signatur beibehalten oder ein **kwargs-Argument akzeptieren (durch das name übergeben würde).

Parameter, die nach dem deprezierten Parameter kommen, werden effektiv nur als Schlüsselwortargumente gültig (da sie nicht positionsgebunden übergeben werden können, ohne die Deprezierungswarnung für den deprezierten Parameter auszulösen) und sollten nach Ablauf der Deprezierungsperiode und Entfernung des deprezierten Parameters als solche markiert werden.

Parameter außer since, name und func sind nur als Schlüsselwortargumente gültig und werden an warn_deprecated weitergeleitet.

Beispiele

@_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)[Quelle]#

Gibt obj.method mit einer Deprezierung zurück, wenn diese überschrieben wurde, andernfalls None.

Parameter:

method: Eine ungebundene Methode, d. h. ein Ausdruck der Form Class.method_name. Denken Sie daran, dass innerhalb des Körpers einer Methode __class__ verwendet werden kann, um auf die gerade definierte Klasse zu verweisen.
obj: Entweder ein Objekt der Klasse, in der method definiert ist, oder eine Unterklasse dieser Klasse.
allow_emptybool, Standard: False: Ob Überschreibungen durch "leere" Methoden ohne Auslösung einer Warnung erlaubt sind.
**kwargs: Zusätzliche Parameter, die an warn_deprecated übergeben werden, um die Deprezierungswarnung zu generieren; muss mindestens den Schlüssel "since" enthalten.

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

Bases: object

Hilfe zur Deprezierung des öffentlichen Zugriffs auf ein Attribut (oder eine Methode).

Diese Hilfe sollte nur auf Klassenebene verwendet werden, wie folgt:

class Foo:
    attr = _deprecate_privatize_attribute(*args, **kwargs)

wobei alle Parameter an deprecated weitergeleitet werden. Diese Form macht attr zu einer Eigenschaft, die Lese- und Schreibzugriffe an self._attr (gleicher Name, aber mit führendem Unterstrich) weiterleitet, mit einer Deprezierungswarnung. Beachten Sie, dass der Attributname von dem Namen abgeleitet wird, dem diese Hilfe zugewiesen wird. Diese Hilfe funktioniert auch zur Deprezierung von Methoden.

matplotlib._api.deprecation.deprecated(since, *, message='', name='', alternative='', pending=False, obj_type=None, addendum='', removal='')[Quelle]#

Dekulator zur Kennzeichnung einer Funktion, einer Klasse oder einer Eigenschaft als depreziert.

Beim Deprezieren einer Klassenmethode, einer statischen Methode oder einer Eigenschaft sollte der @deprecated-Dekulator unter @classmethod und @staticmethod platziert werden (d. h., deprecated sollte direkt den zugrunde liegenden aufrufbaren deklarieren), aber über @property.

Beim Deprezieren einer Klasse C, die als Basisklasse in einer Mehrfachvererbungshierarchie verwendet werden soll, muss C eine __init__-Methode definieren (wenn C stattdessen seine __init__ von seiner eigenen Basisklasse geerbt hat, dann würde @deprecated die __init__-Vererbung stören, wenn es seine eigene (Deprezierungswarnung ausgebende) C.__init__ installiert).

Die Parameter sind dieselben wie für warn_deprecated, außer dass obj_type standardmäßig auf 'class' gesetzt wird, wenn eine Klasse dekoriert wird, auf 'attribute', wenn eine Eigenschaft dekoriert wird, und andernfalls auf 'function'.

Beispiele

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

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

Dekulator, der angibt, dass die positionsgebundene Übergabe des Parameters name (oder eines der folgenden) an func depreziert wird.

Wenn dieser Dekulator auf eine Methode mit einem Pyplot-Wrapper angewendet wird, sollte er der äußerste Dekulator sein, damit boilerplate.py auf die ursprüngliche Signatur zugreifen kann.

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

Dekulator, der angibt, dass der Parameter old von func in new umbenannt wird.

Die tatsächliche Implementierung von func sollte new verwenden, nicht old. Wenn old an func übergeben wird, wird eine Deprezierungswarnung ausgegeben und dessen Wert verwendet, auch wenn new ebenfalls per Schlüsselwort übergeben wird (dies vereinfacht Pyplot-Wrapper-Funktionen, die new immer explizit an die Axes-Methode übergeben). Wenn new ebenfalls übergeben wird, aber positionsgebunden, wird durch die zugrunde liegende Funktion während der Argumentbindung ein TypeError ausgelöst.

Beispiele

@_api.rename_parameter("3.1", "bad_name", "good_name")
def func(good_name): ...

matplotlib._api.deprecation.suppress_matplotlib_deprecation_warning()[Quelle]#

matplotlib._api.deprecation.warn_deprecated(since, *, message='', name='', alternative='', pending=False, obj_type='', addendum='', removal='')[Quelle]#

Zeigt eine standardisierte Deprezierung an.

Parameter:

sincestr: Die Version, ab der diese API depreziert wurde.
messagestr, optional: Überschreibt die Standard-Deprezierungsnachricht. Die Formatierungsoptionen %(since)s, %(name)s, %(alternative)s, %(obj_type)s, %(addendum)s und %(removal)s werden durch die Werte der jeweiligen an diese Funktion übergebenen Argumente ersetzt.
namestr, optional: Der Name des deprezierten Objekts.
alternativestr, optional: Eine alternative API, die der Benutzer anstelle der deprezierten API verwenden kann. Die Deprezierungswarnung informiert den Benutzer über diese Alternative, falls sie angegeben ist.
pendingbool, optional: Wenn True, wird eine PendingDeprecationWarning anstelle einer DeprecationWarning verwendet. Kann nicht zusammen mit removal verwendet werden.
obj_typestr, optional: Der Typ des deprezierten Objekts.
addendumstr, optional: Zusätzlicher Text, der direkt an die endgültige Nachricht angehängt wird.
removalstr, optional: Die erwartete Entfernungsversion. Mit dem Standardwert (leerer String) wird eine Entfernungsversion automatisch aus since berechnet. Auf andere Falsy-Werte setzen, um kein Entfernungsdatum zu planen. Kann nicht zusammen mit pending verwendet werden.

Beispiele

# To warn of the deprecation of "matplotlib.name_of_module"
warn_deprecated('1.4.0', name='matplotlib.name_of_module',
                obj_type='module')

matplotlib._api#

`matplotlib._api`#