A smarter replacement for Python's built-in dir() — built for exploring objects interactively.

When working in a Python REPL, IPython session, Jupyter Notebook, or a pdb debugging session, you often need to explore unfamiliar objects. Python's built-in dir() gives you a flat list of attribute names — but it doesn't search, it doesn't recurse, and it tells you nothing about types or sizes.

ls fixes that. Given an object and a search term, it walks the object's attribute tree recursively, finds anything whose name contains your term, and prints the results with their types and sizes.

pip install python-ls

After installation, ls is automatically injected into Python's builtins, so it's available in any interactive session without any import.

>>> ls(my_obj)

>>> ls(my_obj, "price", depth=3)
order.items[0].price                                           float
order.items[1].price                                           float
order.discount.price_threshold                                 float

>>> ls(my_obj, depth=2)   # explore 2 levels deep
>>> ls(my_obj, "name")    # search unlimited depth (depth defaults to None when attr is given)

>>> ls(my_obj, under=False)    # include _single_underscore attributes
>>> ls(my_obj, dunder=True)    # include __dunder__ attributes

>>> xdir(my_obj, "price", depth=3)
['order.items[0].price', 'order.items[1].price', 'order.discount.price_threshold']

>>> for path, value in iter_ls(my_obj, "price", depth=3):
...     print(path, value)

If you prefer to import explicitly rather than rely on the builtin injection:

from python_ls import ls, xdir, iter_ls

ls handles pandas.DataFrame objects specially — it searches column names rather than object attributes.

>>> ls(df, "revenue", depth=2)

ls uses getattr() to retrieve attribute values, which will execute any property or lazy attribute code. If you're exploring objects with side-effectful properties, be aware that those will run. A future unsafe=False flag to skip properties is planned.

Issues, bug reports, and pull requests are welcome at https://github.com/gabrielcnr/python-ls.