`matplotlib._api`#

Hilfsfunktionen zum Verwalten der Matplotlib-API.

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

Warnung

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

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

Hilfsdekorateur zum Implementieren der Modulebene __getattr__als Klasse.

Dieser Decorator 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, so dass der Versuch, nameauf das Modul zuzugreifen, die entsprechende Eigenschaft auflöst (die z. B. mit dekoriert werden kann, um _api.deprecatedModul-Globals zu verwerfen). Die Eigenschaften werden alle implizit zwischengespeichert. Außerdem wird ein passender AttributeError generiert und ausgelöst, wenn keine Property mit dem angegebenen Namen existiert.

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

kwargs muss aus einem einzigen Schlüssel-Wert -Paar bestehen. Wenn der Schlüssel in _mapping ist, geben Sie zurück _mapping[value]; lösen Sie andernfalls einen entsprechenden ValueError aus.

Beispiele

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

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

Überprüfen Sie für jedes Schlüssel-Wert -Paar in kwargs , ob sich der Wert in _values befindet .

Parameter :

_values iterierbar: Sequenz von Werten, die überprüft werden sollen.
_print_supported_values bool, Standard: True: Ob _values ausgegeben werden , wenn ValueError ausgelöst wird.
**Kwargs Diktat: Schlüssel-Wert - Paare als Schlüsselwortargumente, die in _values zu finden sind .

Erhöhungen :

WertFehler: Wenn irgendein 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] #

Prüfen Sie für jedes Schlüssel-Wert -Paar in kwargs , ob value eine Instanz von einem der _types ist ; Wenn nicht, lösen Sie einen entsprechenden TypeError aus.

Als Sonderfall wird ein NoneEintrag in _types als NoneType behandelt.

Beispiele

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

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

Überprüfen Sie für jedes Schlüssel/Wert -Paar in kwargs , ob der Wert die Form _shape hat, wenn nicht, lösen Sie einen entsprechenden ValueError aus.

Keine in der Form wird als "freie" Größe behandelt, die eine beliebige Länge haben kann. zB (Keine, 2) -> (N, 2)

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

Beispiele

Um nach (N, 2) geformten Arrays zu suchen

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

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

Basen:object

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

Beispiele

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

assert C.foo == "C"

Eigenschaft fget #

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

Klassendekorator zum Definieren von Eigenschaftsaliasen.

Benutzen als

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

Für jede Eigenschaft wird, wenn die entsprechende get_propertybisher in der Klasse definiert ist, ein Alias namens get_aliasdefiniert; das gleiche wird für Setter gemacht. Wenn weder Getter noch Setter vorhanden sind, wird eine Ausnahme ausgelöst.

Die Alias-Map wird als _alias_mapAttribut der Klasse gespeichert und kann von verwendet werden normalize_kwargs(was davon ausgeht, dass Aliase mit höherer Priorität zuletzt kommen).

matplotlib._api. recursive_subclasses ( cls ) [Quelle] #: Ertrag cls und direkte und indirekte Unterklassen von cls .

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

Wählen Sie die Funktion aus, die akzeptiert, und rufen Sie sie auf .*args, **kwargs

funcs ist eine Liste von Funktionen, die keine Ausnahme auslösen sollten (außer TypeErrorwenn die übergebenen Argumente nicht mit ihrer Signatur übereinstimmen).

select_matching_signatureversucht, jede der Funktionen in funcs mit aufzurufen (in der Reihenfolge, in der sie angegeben sind). Anrufe, die mit einem fehlschlagen, werden stillschweigend übersprungen. Sobald ein Aufruf erfolgreich ist, gibt es seinen Rückgabewert zurück. Wenn keine Funktion akzeptiert , wird der vom letzten fehlgeschlagenen Aufruf ausgelöste erneut ausgelöst.*args, **kwargsTypeErrorselect_matching_signature*args, **kwargsTypeError

Aufrufer sollten normalerweise sicherstellen, dass any nur eine einzige Funktion binden kann ( um Mehrdeutigkeiten zu vermeiden), obwohl dies nicht von überprüft wird .*args, **kwargsselect_matching_signature

Anmerkungen

select_matching_signaturesoll helfen, signaturüberladene Funktionen zu implementieren. 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

wodurch my_func entweder mit zwei Parametern ( old1 und old2 ) oder einem einzigen ( new ) aufgerufen werden kann. Beachten Sie, dass die neue Signatur zuletzt angegeben wird, sodass Aufrufer eine TypeErrorEntsprechung zur neuen Signatur erhalten, wenn die übergebenen Argumente mit keiner Signatur übereinstimmen.

matplotlib._api. warn_external ( Nachricht , Kategorie = Keine ) [Quelle] #

warnings.warnWrapper, der Stacklevel auf "außerhalb von Matplotlib" setzt.

Der ursprüngliche Sender der Warnung kann erhalten werden, indem diese Funktion zurück zu gepatcht wird warnings.warn, dh (oder usw.)._api.warn_external = warnings.warnfunctools.partial(warnings.warn, stacklevel=2)

Hilfsfunktionen zum Verwerfen 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 Vorankündigung ändern.

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

Basen:DeprecationWarning

Eine Klasse zum Ausgeben von Verfallswarnungen für Matplotlib-Benutzer.

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

Decorator, der angibt, dass der Parametername von func veraltet ist.

Die eigentliche Implementierung von func sollte den name**kwargs -Parameter in ihrer Signatur behalten oder ein Argument akzeptieren (durch das name übergeben würde).

Parameter, die nach dem veralteten Parameter kommen, werden effektiv zu reinen Schlüsselwörtern (da sie nicht positionsbezogen übergeben werden können, ohne die DeprecationWarning für den veralteten Parameter auszulösen) und sollten als solche gekennzeichnet werden, nachdem die Verfallszeit verstrichen ist und der veraltete Parameter entfernt wurde.

Andere Parameter als since , name und func sind nur Schlüsselworte und werden an weitergeleitet warn_deprecated.

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] #

Rückgabe obj.methodmit einer Verwerfung, wenn sie überschrieben wurde, sonst Keine.

Parameter :

Methode: Eine ungebundene Methode, dh ein Ausdruck der Form Class.method_name. Denken Sie daran, dass man innerhalb des Hauptteils einer Methode immer verwenden kann __class__, um auf die Klasse zu verweisen, die gerade definiert wird.
obj: Entweder ein Objekt der Klasse, in der die Methode definiert ist, oder eine Unterklasse dieser Klasse.
allow_empty bool, Standard: False: Ob Überschreibungen durch „leere“ Methoden zugelassen werden sollen, ohne dass eine Warnung ausgegeben wird.
**Kwarg: Zusätzliche Parameter, die an übergeben werden warn_deprecated, um die Verfallswarnung zu generieren; muss mindestens den „sind“-Schlüssel enthalten.

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

Basen:object

Helfer, um den öffentlichen Zugriff auf ein Attribut (oder eine Methode) zu verwerfen.

Dieser Helfer sollte nur im Klassenbereich wie folgt verwendet werden:

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

wo alle Parameter weitergeleitet werden deprecated. Dieses Formular erstellt attreine Eigenschaft, die den Lese- und Schreibzugriff auf self._attr (denselben Namen, aber mit einem vorangestellten Unterstrich) mit einer Verfallswarnung weiterleitet. Beachten Sie, dass der Attributname von dem Namen abgeleitet wird, dem dieser Helfer zugewiesen ist . Dieser Helfer funktioniert auch für veraltete Methoden.

matplotlib._api.deprecation. veraltet ( seit , * , Nachricht = '' , Name = '' , Alternative = '' , ausstehend = False , obj_type = None , Nachtrag = '' , Entfernung = '' ) [Quelle] #

Decorator, um eine Funktion, eine Klasse oder eine Eigenschaft als veraltet zu markieren.

Wenn eine Klassenmethode, eine statische Methode oder eine Eigenschaft veraltet ist, @deprecatedsollte der Dekorator unter @classmethod und gehen @staticmethod(dh deprecatedsollte direkt das zugrunde liegende Callable dekorieren), aber über @property .

Beim Verwerfen einer Klasse C, die als Basisklasse in einer Mehrfachvererbungshierarchie verwendet werden soll, C muss eine __init__Methode definiert werden (wenn sie Cstattdessen __init__von ihrer eigenen Basisklasse geerbt wird, dann würde die Vererbung beim Installieren ihrer eigenen (veraltendes Ausgeben) @deprecateddurcheinander gebracht ).__init__C.__init__

Die Parameter sind dieselben wie für warn_deprecated, außer dass obj_type standardmäßig „class“ ist, wenn eine Klasse dekoriert wird, „attribute“, wenn eine Eigenschaft dekoriert wird, und ansonsten „function“.

Beispiele

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

matplotlib._api.deprecation. make_keyword_only ( seit , name , func = None ) [source] #

Decorator, der angibt, dass die Übergabe des Parameternamens (oder eines der folgenden) positionell an func veraltet ist.

Bei Verwendung in einer Methode mit einem Pyplot-Wrapper sollte dies der äußerste Decorator sein, damit boilerplate.pyauf die Originalsignatur zugegriffen werden kann.

matplotlib._api.deprecation. rename_parameter ( seit , alt , neu , func = None ) [source] #

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

Die eigentliche Implementierung von func sollte new und nicht old verwenden . Wenn old an func übergeben wird, wird eine DeprecationWarning ausgegeben und ihr Wert verwendet, selbst wenn new auch per Schlüsselwort übergeben wird (dies dient der Vereinfachung von Pyplot-Wrapper-Funktionen, die new immer explizit an die Axes-Methode übergeben). Wenn new ebenfalls übergeben wird, aber positionsbezogen, wird während der Argumentbindung ein TypeError von der zugrunde liegenden Funktion 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 ( seit , * , Nachricht = '' , Name = '' , Alternative = '' , ausstehend = False , obj_type = '' , Nachtrag = '' , Entfernung = '' ) [Quelle] #

Zeigen Sie eine standardisierte Abwertung an.

Parameter :

seit Str: Die Version, ab der diese API veraltet ist.
Nachrichtenzeichenfolge , optional: Überschreiben Sie die standardmäßige Verwerfungsmeldung. Die Formatbezeichner , , , , und werden durch die Werte der entsprechenden Argumente ersetzt, die an %(since)sdiese %(name)sFunktion %(alternative)sübergeben %(obj_type)swerden %(addendum)s.%(removal)s
Namensstr , optional: Der Name des veralteten Objekts.
alternative str, optional: Eine alternative API, die der Benutzer anstelle der veralteten API verwenden kann. Die Verfallswarnung informiert den Benutzer über diese Alternative, falls vorhanden.
ausstehender boolescher Wert, optional: Wenn True, wird eine PendingDeprecationWarning anstelle einer DeprecationWarning verwendet. Kann nicht zusammen mit Entfernung verwendet werden .
obj_type str, optional: Der veraltete Objekttyp.
Nachtrag str, optional: Zusätzlicher Text, der direkt an die letzte Nachricht angehängt wird.
Entfernungsstr , optional: Die erwartete Entfernungsversion. Mit dem Standardwert (einer leeren Zeichenfolge) wird eine Entfernungsversion automatisch von seit berechnet . Legen Sie andere falsche Werte fest, um kein Entfernungsdatum zu planen. Kann nicht zusammen mit ausstehend 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`#