`matplotlib._api`#

Fonctions d'assistance pour la gestion de l'API Matplotlib.

Cette documentation n'est pertinente que pour les développeurs Matplotlib, pas pour les utilisateurs.

Avertissement

Ce module et ses sous-modules sont destinés à un usage interne uniquement. Ne les utilisez pas dans votre propre code. Nous pouvons modifier l'API à tout moment sans avertissement.

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

Décorateur d'assistance pour l'implémentation au niveau du module en __getattr__tant que classe.

Ce décorateur doit être utilisé au niveau supérieur du module comme suit :

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

La __getattr__classe sera remplacée par une __getattr__ fonction telle qu'essayer d'accéder nameau module résoudra la propriété correspondante (qui peut être décorée par exemple avec _api.deprecatedpour déprécier les globales de module). Les propriétés sont toutes implicitement mises en cache. De plus, une AttributeError appropriée est générée et déclenchée si aucune propriété portant le nom donné n'existe.

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

kwargs doit consister en une seule paire clé-valeur . Si la clé est dans _mapping , return _mapping[value]; sinon, déclenchez une ValueError appropriée.

Exemples

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

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

Pour chaque clé, paire de valeurs dans kwargs , vérifiez que la valeur est dans _values .

Paramètres :

_values itérables: Séquence de valeurs à vérifier.
_print_supported_values booléen , par défaut : Vrai: S'il faut imprimer _values lors de la levée de ValueError.
** dict de kwargs: clé, paires de valeurs en tant qu'arguments de mots-clés à rechercher dans _values .

Augmente :

Erreur de valeur: Si une valeur dans kwargs n'est pas trouvée dans _values .

Exemples

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

matplotlib._api. check_isinstance ( _types , ** kwargs ) [source] #

Pour chaque clé, paire de valeurs dans kwargs , vérifiez que value est une instance de l'un des _types ; sinon, déclenchez une TypeError appropriée.

Dans un cas particulier, une Noneentrée dans _types est traitée comme NoneType.

Exemples

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

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

Pour chaque clé, paire de valeurs dans kwargs , vérifiez que value a la forme _shape , sinon, déclenchez une ValueError appropriée.

Aucun dans la forme n'est traité comme une taille "libre" qui peut avoir n'importe quelle longueur. par exemple (Aucun, 2) -> (N, 2)

Les valeurs cochées doivent être des tableaux numpy.

Exemples

Pour vérifier les tableaux en forme de (N, 2)

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

classe matplotlib._api. propriété de classe ( fget , fset = Aucun , fdel = Aucun , doc = Aucun ) [source] #

Socles :object

Comme property, mais se déclenche également lors de l'accès via la classe, et c'est la classe qui est passée en argument.

Exemples

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

assert C.foo == "C"

propriété fget #

matplotlib._api. définir_aliases ( alias_d , cls = Aucun ) [source] #

Décorateur de classe pour définir des alias de propriété.

Utilisé comme

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

Pour chaque propriété, si le correspondant get_propertyest défini dans la classe jusqu'à présent, un alias nommé get_aliassera défini ; il en sera de même pour les setters. Si ni le getter ni le setter n'existent, une exception sera levée.

La carte d'alias est stockée en tant _alias_mapqu'attribut sur la classe et peut être utilisée par normalize_kwargs(ce qui suppose que les alias de priorité supérieure viennent en dernier).

matplotlib._api. recursive_subclasses ( cls ) [source] #: Rendement cls et sous-classes directes et indirectes de cls .

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

Sélectionnez et appelez la fonction qui accepte .*args, **kwargs

funcs est une liste de fonctions qui ne doivent lever aucune exception (sauf TypeErrorsi les arguments passés ne correspondent pas à leur signature).

select_matching_signatureessaie d'appeler chacune des fonctions dans funcs avec (dans l'ordre dans lequel elles sont données). Les appels qui échouent avec un sont silencieusement ignorés. Dès qu'un appel réussit, renvoie sa valeur de retour. Si aucune fonction n'accepte , alors le déclenché par le dernier appel ayant échoué est relancé.*args, **kwargsTypeErrorselect_matching_signature*args, **kwargsTypeError

Les appelants doivent normalement s'assurer que any ne peut lier qu'une seule fonction (pour éviter toute ambiguïté), bien que cela ne soit pas vérifié par .*args, **kwargsselect_matching_signature

Remarques

select_matching_signatureest destiné à aider à implémenter des fonctions surchargées de signature. En général, de telles fonctions doivent être évitées, sauf pour des problèmes de rétrocompatibilité. Un modèle d'utilisation typique est

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

ce qui permet d' appeler my_func soit avec deux paramètres ( old1 et old2 ) soit avec un seul ( new ). Notez que la nouvelle signature est donnée en dernier, de sorte que les appelants obtiennent un TypeErrorcorrespondant à la nouvelle signature si les arguments qu'ils ont passés ne correspondent à aucune signature.

matplotlib._api. warn_external ( message , catégorie = Aucun ) [source] #

warnings.warnwrapper qui définit le niveau de pile sur "en dehors de Matplotlib".

L'émetteur d'origine de l'avertissement peut être obtenu en patchant cette fonction sur warnings.warn, c'est-à-dire (ou , etc.)._api.warn_external = warnings.warnfunctools.partial(warnings.warn, stacklevel=2)

Fonctions d'assistance pour déprécier des parties de l'API Matplotlib.

Cette documentation n'est pertinente que pour les développeurs Matplotlib, pas pour les utilisateurs.

Avertissement

Ce module est à usage interne uniquement. Ne l'utilisez pas dans votre propre code. Nous pouvons modifier l'API à tout moment sans avertissement.

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

Socles :DeprecationWarning

Une classe pour émettre des avertissements de dépréciation pour les utilisateurs de Matplotlib.

matplotlib._api.deprecation. delete_parameter ( puisque , nom , func = None , ** kwargs ) [source] #

Décorateur indiquant que le nom de paramètre de func est obsolète.

L'implémentation réelle de func devrait conserver le paramètre name dans sa signature, ou accepter un **kwargsargument (par lequel name serait passé).

Les paramètres qui viennent après le paramètre obsolète deviennent effectivement des mots-clés uniquement (car ils ne peuvent pas être passés de manière positionnelle sans déclencher l'avertissement DeprecationWarning sur le paramètre obsolète) et doivent être marqués comme tels après la fin de la période d'obsolescence et la suppression du paramètre obsolète.

Les paramètres autres que since , name et func sont des mots-clés uniquement et transmis à warn_deprecated.

Exemples

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

Retourne obj.methodavec une obsolescence si elle a été remplacée, sinon Aucune.

Paramètres :

méthode: Une méthode non liée, c'est-à-dire une expression de la forme Class.method_name. N'oubliez pas que dans le corps d'une méthode, on peut toujours utiliser __class__pour faire référence à la classe en cours de définition.
obj: Soit un objet de la classe où la méthode est définie, soit une sous-classe de cette classe.
allow_empty booléen , par défaut : False: S'il faut autoriser les remplacements par des méthodes "vides" sans émettre d'avertissement.
**kwargs: Paramètres supplémentaires transmis à warn_deprecatedpour générer l'avertissement d'obsolescence ; doit au moins inclure la clé "depuis".

classe matplotlib._api.deprecation. deprecate_privatize_attribute ( * args , ** kwargs ) [source] #

Socles :object

Aide pour déprécier l'accès public à un attribut (ou une méthode).

Cet assistant ne doit être utilisé qu'au niveau de la classe, comme suit :

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

où tous les paramètres sont transmis à deprecated. Ce formulaire crée attrune propriété qui transmet l'accès en lecture et en écriture à self._attr (même nom mais avec un trait de soulignement au début), avec un avertissement d'obsolescence. Notez que le nom de l'attribut est dérivé du nom auquel cet assistant est affecté . Cet assistant fonctionne également pour les méthodes obsolètes.

matplotlib._api.deprecation. obsolète ( puisque , * , message = '' , nom = '' , alternative = '' , pending = False , obj_type = None , addendum = '' , removal = '' ) [source] #

Décorateur pour marquer une fonction, une classe ou une propriété comme obsolète.

Lors de la dépréciation d'une méthode de classe, d'une méthode statique ou d'une propriété, le @deprecateddécorateur doit passer sous @classmethod et @staticmethod(c'est-à-dire deprecateddoit décorer directement l'appelable sous-jacent), mais au- dessus de @property .

Lors de l'obsolescence d'une classe Cdestinée à être utilisée comme classe de base dans une hiérarchie d'héritage multiple, C doit définir une __init__méthode (si elle Chéritait plutôt __init__de sa propre classe de base, @deprecatedcela gâcherait l' __init__héritage lors de l'installation de la sienne (dépréciation-émission) C.__init__).

Les paramètres sont les mêmes que pour warn_deprecated, sauf que obj_type prend par défaut 'class' si vous décorez une classe, 'attribut' si vous décorez une propriété et 'function' sinon.

Exemples

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

matplotlib._api.deprecation. make_keyword_only ( puisque , nom , func = Aucun ) [source] #

Décorateur indiquant que le passage du nom du paramètre (ou de l'un des suivants) de manière positionnelle à func est obsolète.

Lorsqu'il est utilisé sur une méthode qui a un wrapper pyplot, cela devrait être le décorateur le plus externe, afin qu'il boilerplate.pypuisse accéder à la signature d'origine.

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

Décorateur indiquant que le paramètre old de func est renommé en new .

L'implémentation réelle de func devrait utiliser new , pas old . Si old est passé à func , un DeprecationWarning est émis et sa valeur est utilisée, même si new est également passé par mot-clé (cela simplifie les fonctions wrapper pyplot, qui passent toujours new explicitement à la méthode Axes). Si new est également passé mais en position, une TypeError sera déclenchée par la fonction sous-jacente lors de la liaison d'argument.

Exemples

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

Afficher une dépréciation standardisée.

Paramètres :

depuis str: La version à laquelle cette API est devenue obsolète.
message str, facultatif: Remplacez le message d'obsolescence par défaut. Les spécificateurs de format %(since)s, %(name)s, %(alternative)s, %(obj_type)s, %(addendum)set %(removal)sseront remplacés par les valeurs des arguments respectifs passés à cette fonction.
chaîne de nom , facultatif: Nom de l'objet obsolète.
alternative str, facultatif: Une API alternative que l'utilisateur peut utiliser à la place de l'API obsolète. L'avertissement d'obsolescence informera l'utilisateur de cette alternative si elle est fournie.
booléen en attente , facultatif: Si True, utilise un PendingDeprecationWarning au lieu d'un DeprecationWarning. Ne peut pas être utilisé avec le retrait .
obj_type chaîne , facultatif: Type d'objet obsolète.
addendum str, facultatif: Texte supplémentaire ajouté directement au message final.
suppression str, facultatif: La version de suppression attendue. Avec la valeur par défaut (une chaîne vide), une version de suppression est automatiquement calculée à partir de depuis . Définissez d'autres valeurs Falsy pour ne pas programmer de date de suppression. Ne peut pas être utilisé avec pending .

Exemples

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