`matplotlib._api`#

Funções auxiliares para gerenciar a API Matplotlib.

Esta documentação é relevante apenas para desenvolvedores Matplotlib, não para usuários.

Aviso

Este módulo e seus submódulos são apenas para uso interno. Não os use em seu próprio código. Podemos alterar a API a qualquer momento sem aviso prévio.

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

Decorador auxiliar para implementar o nível do módulo __getattr__como uma classe.

Este decorador deve ser utilizado no nível superior do módulo da seguinte forma:

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

A __getattr__classe será substituída por uma __getattr__ função de modo que tentar acessar nameo módulo resolva a propriedade correspondente (que pode ser decorada, por exemplo _api.deprecated, para depreciar globals do módulo). As propriedades são todas armazenadas em cache implicitamente. Além disso, um AttributeError adequado é gerado e levantado se não existir nenhuma propriedade com o nome fornecido.

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

kwargs deve consistir em uma única chave, par de valores. Se a chave estiver em _mapping , retorne _mapping[value]; caso contrário, gere um ValueError apropriado.

Exemplos

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

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

Para cada chave, par de valor em kwargs , verifique se o valor está em _values .

Parâmetros :

_valores iteráveis: Sequência de valores a serem verificados.
_print_supported_values bool, padrão: True: Se deve imprimir _values ao aumentar ValueError.
** ditado dos kwargs: chave, pares de valor como argumentos de palavra-chave para localizar em _values .

Aumentos :

ValueError: Se algum valor em kwargs não for encontrado em _values .

Exemplos

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

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

Para cada chave, par de valor em kwargs , verifique se value é uma instância de um dos _types ; caso contrário, gere um TypeError apropriado.

Como um caso especial, uma Noneentrada em _types é tratada como NoneType.

Exemplos

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

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

Para cada chave, par de valor em kwargs , verifique se o valor tem a forma _shape , caso contrário, gere um ValueError apropriado.

Nenhum na forma é tratado como um tamanho "livre" que pode ter qualquer comprimento. por exemplo (Nenhum, 2) -> (N, 2)

Os valores verificados devem ser matrizes numpy.

Exemplos

Para verificar matrizes em forma de (N, 2)

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

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

Bases:object

Como property, mas também dispara no acesso por meio da classe, e é a classe que é passada como argumento.

Exemplos

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

assert C.foo == "C"

propriedade fget #

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

Decorador de classe para definir aliases de propriedade.

Usar como

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

Para cada propriedade, se a correspondente get_propertyestiver definida na classe até o momento, get_aliasserá definido um alias nomeado; o mesmo será feito para os setters. Se nem o getter nem o setter existirem, uma exceção será gerada.

O mapa de alias é armazenado como o _alias_mapatributo na classe e pode ser usado por normalize_kwargs(o que assume que os aliases de prioridade mais alta vêm por último).

matplotlib._api. recursive_subclasses ( cls ) [fonte] #: Rendimento cls e subclasses diretas e indiretas de cls .

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

Selecione e chame a função que aceita .*args, **kwargs

funcs é uma lista de funções que não devem gerar nenhuma exceção (exceto TypeErrorse os argumentos passados não corresponderem à sua assinatura).

select_matching_signaturetenta chamar cada uma das funções em funcs com (na ordem em que são dadas). As chamadas que falham com um são ignoradas silenciosamente. Assim que uma chamada for bem-sucedida, retorna seu valor de retorno. Se nenhuma função aceitar , então o levantado pela última chamada com falha é levantado novamente.*args, **kwargsTypeErrorselect_matching_signature*args, **kwargsTypeError

Normalmente, os chamadores devem garantir que any possa vincular apenas uma única função (para evitar qualquer ambiguidade), embora isso não seja verificado por .*args, **kwargsselect_matching_signature

Notas

select_matching_signaturedestina-se a ajudar na implementação de funções com sobrecarga de assinatura. Em geral, essas funções devem ser evitadas, exceto por questões de retrocompatibilidade. Um padrão de uso típico é

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

que permite que my_func seja chamado com dois parâmetros ( old1 e old2 ) ou um único ( new ). Observe que a nova assinatura é fornecida por último, para que os chamadores obtenham uma TypeErrorcorrespondência com a nova assinatura se os argumentos que eles transmitiram não corresponderem a nenhuma assinatura.

matplotlib._api. warning_external ( mensagem , categoria = Nenhum ) [fonte] #

warnings.warnwrapper que define stacklevel como "fora do Matplotlib".

O emissor original do aviso pode ser obtido corrigindo esta função de volta para warnings.warn, ou seja, (ou , etc.)._api.warn_external = warnings.warnfunctools.partial(warnings.warn, stacklevel=2)

Funções auxiliares para depreciar partes da API Matplotlib.

Esta documentação é relevante apenas para desenvolvedores Matplotlib, não para usuários.

Aviso

Este módulo é apenas para uso interno. Não o use em seu próprio código. Podemos alterar a API a qualquer momento sem aviso prévio.

exceção matplotlib._api.deprecation. MatplotlibDeprecationWarning [fonte] #

Bases:DeprecationWarning

Uma classe para emitir avisos de descontinuação para usuários do Matplotlib.

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

Decorador indicando que o nome do parâmetro de func está sendo obsoleto.

A implementação real de func deve manter o parâmetro name em sua assinatura ou aceitar um **kwargsargumento (através do qual name seria passado).

Os parâmetros que vêm após o parâmetro obsoleto tornam-se efetivamente apenas palavras-chave (já que não podem ser transmitidos posicionalmente sem acionar o DeprecationWarning no parâmetro obsoleto) e devem ser marcados como tal após o período de obsolescência ter passado e o parâmetro obsoleto ser removido.

Parâmetros diferentes de since , name e func são apenas palavras-chave e encaminhados para warn_deprecated.

Exemplos

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

Retorne obj.methodcom uma depreciação se tiver sido substituído, caso contrário, None.

Parâmetros :

método: Um método não vinculado, ou seja, uma expressão da forma Class.method_name. Lembre-se que dentro do corpo de um método, pode-se sempre usar __class__para se referir à classe que está sendo definida no momento.
obj: Um objeto da classe onde o método é definido ou uma subclasse dessa classe.
allow_empty bool, padrão: False: Se deve permitir substituições por métodos "vazios" sem emitir um aviso.
** kwargs: Parâmetros adicionais passados para warn_deprecatedgerar o aviso de descontinuação; deve incluir pelo menos a chave "desde".

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

Bases:object

Auxiliar para depreciar o acesso público a um atributo (ou método).

Este helper deve ser utilizado apenas no escopo da classe, conforme abaixo:

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

onde todos os parâmetros são encaminhados para deprecated. Este formulário cria attruma propriedade que encaminha o acesso de leitura e gravação para self._attr (mesmo nome, mas com um sublinhado à esquerda), com um aviso de descontinuação. Observe que o nome do atributo é derivado do nome atribuído a este auxiliar . Este auxiliar também funciona para métodos obsoletos.

matplotlib._api.deprecation. obsoleto ( desde , * , mensagem = '' , nome = '' , alternativa = '' , pendente = False , obj_type = Nenhum , adendo = '' , remoção = '' ) [source] #

Decorator para marcar uma função, uma classe ou uma propriedade como obsoleta.

Ao depreciar um método de classe, um método estático ou uma propriedade, o @deprecateddecorador deve ir para baixo @classmethod e @staticmethod(ou seja, deprecateddeve decorar diretamente o callable subjacente), mas para cima @property .

Ao depreciar uma classe Cdestinada a ser usada como uma classe base em uma hierarquia de herança múltipla, C deve -se definir um __init__método (se C, em vez disso, for herdado __init__de sua própria classe base, @deprecatedisso atrapalharia a __init__herança ao instalar seu próprio (emissão de depreciação) C.__init__).

Os parâmetros são os mesmos de warn_deprecated, exceto que o padrão obj_type é 'class' se estiver decorando uma classe, 'attribute' se decorando uma propriedade e 'function' caso contrário.

Exemplos

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

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

Decorador indicando que passar o nome do parâmetro (ou qualquer um dos seguintes) posicionalmente para func está sendo obsoleto.

Quando usado em um método que possui um wrapper pyplot, este deve ser o decorador mais externo, para que boilerplate.pypossa acessar a assinatura original.

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

Decorador indicando que o parâmetro old de func foi renomeado para new .

A implementação real de func deve usar new , não old . Se old for passado para func , um DeprecationWarning é emitido e seu valor é usado, mesmo que new também seja passado por palavra-chave (isso é para simplificar as funções wrapper pyplot, que sempre passam new explicitamente para o método Axes). Se new também for passado, mas posicionalmente, um TypeError será levantado pela função subjacente durante a ligação do argumento.

Exemplos

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

matplotlib._api.deprecation. suprime_matplotlib_deprecation_warning ( ) [fonte] #

matplotlib._api.deprecation. warning_deprecated ( desde , * , mensagem = '' , nome = '' , alternativa = '' , pendente = False , obj_type = '' , adendo = '' , remoção = '' ) [fonte] #

Exibir uma depreciação padronizada.

Parâmetros :

desde str: A versão na qual esta API foi preterida.
mensagem str, opcional: Substitua a mensagem de descontinuação padrão. Os especificadores de formato %(since)s, %(name)s, %(alternative)s, %(obj_type)s, %(addendum)se %(removal)sserão substituídos pelos valores dos respectivos argumentos passados para esta função.
nome str, opcional: O nome do objeto obsoleto.
str alternativo , opcional: Uma API alternativa que o usuário pode usar no lugar da API obsoleta. O aviso de descontinuação informará o usuário sobre essa alternativa, se fornecida.
bool pendente , opcional: Se for True, usa um PendingDeprecationWarning em vez de um DeprecationWarning. Não pode ser usado em conjunto com a remoção .
obj_type str, opcional: O tipo de objeto sendo obsoleto.
adendo str, opcional: Texto adicional anexado diretamente à mensagem final.
linha de remoção , opcional: A versão de remoção esperada. Com o padrão (uma string vazia), uma versão de remoção é calculada automaticamente desde . Defina outros valores Falsy para não agendar uma data de remoção. Não pode ser usado junto com pendentes .

Exemplos

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