`matplotlib._api`#

Funzioni di supporto per la gestione dell'API Matplotlib.

Questa documentazione è rilevante solo per gli sviluppatori Matplotlib, non per gli utenti.

Avvertimento

Questo modulo e i suoi sottomoduli sono solo per uso interno. Non usarli nel tuo codice. Possiamo modificare l'API in qualsiasi momento senza preavviso.

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

Decoratore helper per l'implementazione a livello di modulo __getattr__come classe.

Questo decoratore deve essere utilizzato al livello superiore del modulo come segue:

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

La __getattr__classe verrà sostituita da una __getattr__ funzione tale che il tentativo di accedere nameal modulo risolverà la proprietà corrispondente (che può essere decorata, ad esempio, con _api.deprecatedper deprecare i moduli globali). Le proprietà sono tutte implicitamente memorizzate nella cache. Inoltre, viene generato e sollevato un AttributeError adatto se non esiste alcuna proprietà con il nome dato.

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

kwargs deve essere costituito da una singola chiave, coppia di valori. Se la chiave è in _mapping , return _mapping[value]; altrimenti, solleva un ValueError appropriato.

Esempi

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

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

Per ogni chiave, coppia di valori in kwargs , controlla che value sia in _values .

Parametri :

_values iterabile: Sequenza di valori da verificare.
_print_supported_values booleano, predefinito: vero: Indica se stampare _values durante la generazione di ValueError.
**kwargs dict: chiave, coppie di valori come argomenti di parole chiave da trovare in _values .

Rialzi :

ValoreErrore: Se non viene trovato alcun valore in kwargs in _values .

Esempi

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

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

Per ogni chiave, coppia di valori in kwargs , controlla che value sia un'istanza di uno di _types ; in caso contrario, solleva un TypeError appropriato.

Come caso speciale, una Nonevoce in _types viene trattata come NoneType.

Esempi

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

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

Per ogni chiave, coppia di valori in kwargs , verifica che value abbia la forma _shape , in caso contrario, solleva un ValueError appropriato.

Nessuno nella forma è trattato come una dimensione "libera" che può avere qualsiasi lunghezza. es. (Nessuno, 2) -> (N, 2)

I valori controllati devono essere array numpy.

Esempi

Per verificare la presenza di matrici a forma di (N, 2).

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

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

Basi:object

Come property, ma si attiva anche all'accesso tramite la classe, ed è la classe che viene passata come argomento.

Esempi

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

assert C.foo == "C"

codice proprietà #

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

Decoratore di classe per la definizione di alias di proprietà.

Usare come

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

Per ogni proprietà, se la corrispondente get_propertyè definita nella classe finora, get_aliasverrà definito un alias denominato; lo stesso sarà fatto per i palleggiatori. Se non esistono né il getter né il setter, verrà sollevata un'eccezione.

La mappa alias viene memorizzata come _alias_mapattributo sulla classe e può essere utilizzata da normalize_kwargs(il che presuppone che gli alias con priorità più alta vengano per ultimi).

matplotlib._api. sottoclassi_ricorsive ( cls ) [fonte] #: Yield cls e sottoclassi dirette e indirette di cls .

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

Selezionare e chiamare la funzione che accetta .*args, **kwargs

funcs è un elenco di funzioni che non dovrebbero sollevare alcuna eccezione (tranne TypeErrorse gli argomenti passati non corrispondono alla loro firma).

select_matching_signaturecerca di chiamare ognuna delle funzioni in funcs with (nell'ordine in cui sono date). Le chiamate che falliscono con a vengono saltate silenziosamente. Non appena una chiamata ha successo, restituisce il suo valore di ritorno. Se nessuna funzione accetta , viene rilanciata la chiamata generata dall'ultima chiamata fallita.*args, **kwargsTypeErrorselect_matching_signature*args, **kwargsTypeError

I chiamanti dovrebbero normalmente assicurarsi che any possa associare solo una singola funzione (per evitare qualsiasi ambiguità), sebbene ciò non sia controllato da .*args, **kwargsselect_matching_signature

Appunti

select_matching_signatureha lo scopo di aiutare a implementare funzioni con sovraccarico di firme. In generale, tali funzioni dovrebbero essere evitate, ad eccezione dei problemi di retrocompatibilità. Un modello di utilizzo tipico è

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

che consente di chiamare my_func con due parametri ( old1 e old2 ) o con uno solo ( new ). Si noti che la nuova firma viene data per ultima, in modo che i chiamanti ottengano un TypeErrorcorrispondente alla nuova firma se gli argomenti che hanno passato non corrispondono ad alcuna firma.

matplotlib._api. warn_external ( messaggio , categoria = Nessuno ) [fonte] #

warnings.warnwrapper che imposta stacklevel su "outside Matplotlib".

L'emettitore originale dell'avviso può essere ottenuto applicando nuovamente questa funzione a warnings.warn, ie (o , ecc.)._api.warn_external = warnings.warnfunctools.partial(warnings.warn, stacklevel=2)

Funzioni di supporto per deprecare parti dell'API Matplotlib.

Questa documentazione è rilevante solo per gli sviluppatori Matplotlib, non per gli utenti.

Avvertimento

Questo modulo è solo per uso interno. Non usarlo nel tuo codice. Possiamo modificare l'API in qualsiasi momento senza preavviso.

eccezione matplotlib._api.deprecation. MatplotlibDeprecationWarning [fonte] #

Basi:DeprecationWarning

Una classe per l'emissione di avvisi di deprecazione per gli utenti di Matplotlib.

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

Decoratore che indica che il nome del parametro di func è stato deprecato.

L'effettiva implementazione di func dovrebbe mantenere il parametro name**kwargs nella sua firma o accettare un argomento (attraverso il quale name verrebbe passato).

I parametri che vengono dopo il parametro obsoleto diventano effettivamente solo parola chiave (poiché non possono essere passati in posizione senza attivare il DeprecationWarning sul parametro obsoleto) e dovrebbero essere contrassegnati come tali dopo che il periodo di deprecazione è trascorso e il parametro obsoleto è stato rimosso.

I parametri diversi da since , name e func sono solo parole chiave e inoltrati a warn_deprecated.

Esempi

@_api.delete_parameter("3.1", "unused")
def func(used_arg, other_arg, unused, more_args): ...

matplotlib._api.deprecazione. deprecate_method_override ( metodo , obj , * , allow_empty = False , ** kwargs ) [fonte] #

Ritorna obj.methodcon una deprecazione se è stata sovrascritta, altrimenti Nessuna.

Parametri :

metodo: Un metodo non associato, ovvero un'espressione della forma Class.method_name. Ricorda che all'interno del corpo di un metodo, puoi sempre usare __class__per fare riferimento alla classe che è attualmente in fase di definizione.
ogg: O un oggetto della classe in cui è definito il metodo o una sottoclasse di quella classe.
allow_empty bool, predefinito: falso: Se consentire le sostituzioni con metodi "vuoti" senza emettere un avviso.
**kwargs: Parametri aggiuntivi passati a warn_deprecatedper generare l'avviso di deprecazione; deve includere almeno la chiave "since".

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

Basi:object

Helper per deprecare l'accesso pubblico a un attributo (o metodo).

Questo helper deve essere utilizzato solo nell'ambito della classe, come segue:

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

dove tutti i parametri vengono inoltrati a deprecated. Questo modulo crea attruna proprietà che inoltra l'accesso in lettura e scrittura a self._attr (stesso nome ma con un carattere di sottolineatura iniziale), con un avviso di deprecazione. Si noti che il nome dell'attributo deriva dal nome a cui è assegnato questo helper . Questo helper funziona anche per deprecare i metodi.

matplotlib._api.deprecazione. deprecato ( poiché , * , message = '' , name = '' , alternative = '' , pending = False , obj_type = None , addendum = '' , removal = '' ) [fonte] #

Decorator per contrassegnare una funzione, una classe o una proprietà come deprecata.

Quando si depreca un metodo di classe, un metodo statico o una proprietà, il @deprecateddecoratore dovrebbe andare sotto @classmethod e @staticmethod(ovvero, deprecateddovrebbe decorare direttamente il chiamabile sottostante), ma sopra @property .

Quando si depreca una classe Cdestinata a essere utilizzata come classe base in una gerarchia di ereditarietà multipla, è C necessario definire un __init__metodo (se Cinvece si ereditasse __init__dalla propria classe base, @deprecatedsi rovinerebbe l' __init__ereditarietà durante l'installazione della propria (deprecation-emitting) C.__init__).

I parametri sono gli stessi di warn_deprecated, tranne per il fatto che obj_type ha come impostazione predefinita 'class' se decora una classe, 'attribute' se decora una proprietà e 'function' altrimenti.

Esempi

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

matplotlib._api.deprecazione. make_keyword_only ( poiché , name , func = None ) [fonte] #

Decoratore che indica che il passaggio del nome del parametro (o uno qualsiasi dei seguenti) in posizione a func è deprecato.

Quando viene utilizzato su un metodo che ha un wrapper pyplot, questo dovrebbe essere il decoratore più esterno, in modo che boilerplate.pypossa accedere alla firma originale.

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

Decoratore che indica che il parametro old di func viene rinominato in new .

L'effettiva implementazione di func dovrebbe usare new , non old . Se old viene passato a func , viene emesso un DeprecationWarning e viene utilizzato il suo valore, anche se new viene passato anche per parola chiave (questo serve a semplificare le funzioni wrapper pyplot, che passano sempre new esplicitamente al metodo Axes). Se viene passato anche new ma in modo posizionale, verrà generato un TypeError dalla funzione sottostante durante l'associazione dell'argomento.

Esempi

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

matplotlib._api.deprecazione. suppress_matplotlib_deprecation_warning ( ) [fonte] #

matplotlib._api.deprecazione. warn_deprecated ( poiché , * , message = '' , name = '' , alternative = '' , pending = False , obj_type = '' , addendum = '' , removal = '' ) [fonte] #

Mostra una deprecazione standardizzata.

Parametri :

poiché str: La versione in cui questa API è diventata obsoleta.
messaggio str, facoltativo: Sostituisci il messaggio di deprecazione predefinito. Gli identificatori di formato %(since)s, %(name)s, %(alternative)s, %(obj_type)s, %(addendum)se %(removal)sverranno sostituiti dai valori dei rispettivi argomenti passati a questa funzione.
nome str, facoltativo: Il nome dell'oggetto obsoleto.
alternativa str, opzionale: Un'API alternativa che l'utente può utilizzare al posto dell'API obsoleta. L'avviso di deprecazione informerà l'utente di questa alternativa, se fornita.
bool in sospeso , facoltativo: Se True, usa un PendingDeprecationWarning invece di un DeprecationWarning. Non può essere utilizzato insieme alla rimozione .
obj_type str, facoltativo: Il tipo di oggetto obsoleto.
addendum str, facoltativo: Testo aggiuntivo aggiunto direttamente al messaggio finale.
rimozione str, facoltativo: La versione di rimozione prevista. Con l'impostazione predefinita (una stringa vuota), viene calcolata automaticamente una versione di rimozione da since . Impostare su altri valori Falsy per non pianificare una data di rimozione. Non può essere utilizzato insieme a pending .

Esempi

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