Python / dir() / Explorar os nomes de atributos de um objeto

dir(object) do Python retorna uma lista de nomes de atributos como strings. Ela não retorna nem executa os métodos ou valores em si. Os nomes são ordenados, mas o objeto pode personalizar a lista; não há garantia de um inventário completo de todo atributo acessível.

O resultado contém nomes, não métodos

Atributos são dados ou comportamentos associados a um objeto; métodos são comportamentos que podem ser chamados. Em uma string, upper é um nome e text.upper() uma chamada real. A referência oficial de dir() descreve seu foco em exploração interativa conveniente.

Os exemplos completos precisam apenas de Python 3. Salve o código em UTF-8 como dir_example.py e execute python dir_example.py, ou python3 conforme o ambiente. Cada exemplo seguinte pode substituir o conteúdo do mesmo arquivo e funcionar de modo independente.

text = "hello"
names = dir(text)
print(type(names).__name__)
print(all(isinstance(name, str) for name in names))
print("upper" in names)
print(names == sorted(names))
print(text.upper())

Saída esperada:

list
True
True
True
HELLO

Todos os elementos são strings. Encontrar upper não converte o texto: a última linha chama o método explicitamente. A lista completa pode variar entre versões do Python, por isso o exemplo verifica um nome relevante em vez de reproduzir uma lista fixa.

Explorar módulos e listas da mesma forma

Um módulo contém nomes de funções, constantes e outros objetos. Após encontrar sqrt em dir(math), chame math.sqrt(). Da mesma forma, localizar append não altera a lista até a chamada real sobre ela.

import math

print("sqrt" in dir(math))
print(math.sqrt(9))
items = []
print("append" in dir(items))
items.append("a")
print(items)

True
3.0
True
['a']

Um nome não informa argumentos nem retornos. Consulte help(math.sqrt) ou a documentação oficial do módulo. Sublinhados iniciais podem indicar convenções, mas não impedem acesso externo como uma barreira de segurança.

dir() e vars() verificam aspectos diferentes

dir(instance) pode incluir nomes da classe e da herança além dos armazenados na instância. vars(object) retorna seu __dict__. Isso ajuda a ver atributos e valores diretamente armazenados, mas nem todo objeto possui esse dicionário.

class User:
    role = "reader"

    def __init__(self, name):
        self.name = name

    def label(self):
        return f"{self.role}:{self.name}"

user = User("Ada")
print([name for name in dir(user) if name in ("name", "role", "label")])
print(vars(user))
print(user.label())

['label', 'name', 'role']
{'name': 'Ada'}
reader:Ada

name fica na instância; role e label vêm da classe. Por isso os resultados diferem. Aqui vars(user) é o dicionário real, não uma cópia: evite alterá-lo ao explorar. Em objetos sem dicionário, como algumas classes com __slots__, vars() pode causar TypeError.

Sem argumento, examinar o espaço de nomes atual

dir() retorna nomes do espaço local atual, não todas as funções embutidas ou todos os pacotes instalados. Em um script novo e independente aparece o nome definido marker, enquanto a função embutida abs não aparece diretamente.

marker = 7
print("marker" in dir())
print("abs" in dir())

True
False

Um console interativo ou notebook pode guardar nomes de execuções anteriores. Confira o local da chamada e variáveis que ficaram no ambiente.

Limites de __dir__() e atributos dinâmicos

O objeto pode personalizar a lista com __dir__() e fornecer atributos dinamicamente com __getattr__(). Um nome ausente pode ser acessível, e um nome mostrado pode falhar na leitura.

class Dynamic:
    def __getattr__(self, name):
        if name == "answer":
            return 42
        raise AttributeError(name)

    def __dir__(self):
        return ["visible"]

item = Dynamic()
print(dir(item))
print("answer" in dir(item))
print(getattr(item, "answer"))
print(hasattr(item, "visible"))

['visible']
False
42
False

O objeto lista apenas visible, mas fornece de fato answer. Use dir() para exploração ou conclusão e confira documentação e comportamento. getattr() e hasattr() podem executar código de busca de atributos, e dir() também pode chamar código personalizado. Não suponha automaticamente ausência de efeitos colaterais.