miller

Version
Status
Documentation
Tools
Compatibility
Stats

What is miller?

This package is under heavy construction. Use at your own risk

"I'm a tool that finds things." - Detective Josephus Miller

Named after the erstwhile inspector from The Expanse, this package provides convenient, introspection tools using a consistent, intuitive syntax for packages, modules, classes, objects, attributes, and containers.

Why use miller?

Universal

Consider the different and often difficult-to-read syntax that Python uses for introspection of different objects.

"""Returns a list of function names in the module 'item'."""

[
    m[0]
    for m in inspect.getmembers(item, inspect.isfunction)
    if m[1].__module__ == item.__name__
]

"""Returns names of properties of the instance 'item'."""
[a for a in dir(type(item)) if isinstance(getattr(type(item), a), property)]

"""Returns names of fields of the dataclass 'item'."""
[f.name for f in dataclasses.fields(item)]

That code can be difficult to remember, requires importing a range of packages, and is not easy to understand if you are not familiar with the relevant imported packages.

In contrast, miller uses simple, easy-to-read code for each of the above requests:

name_functions(item)
name_properties(item)
name_fields(item)

In addition, each of those miller functions includes a boolean parameter include_privates which indicates whether you want to include any matching items that have str names beginning with an underscore.

Intuitive

Unlike the default Python instrospection functions and methods, miller uses a consistent syntax and structure that is far more intuitive. This allows users to guess what the appropriate syntax should by following a simple, consistent structure.

miller uses five basic prefixes for its introspection functions:

Those prefixes are followed by an underscore and a suffix indicating what information is sought. miller has 28 possible suffixes (not every suffix is available for every prefix):

The following functions are available in miller for the catalog, collect, has, and name prefixes:

The is prefix has functions for the following singular suffixes: attribute, class, class_attribute, field, file_path, folder_path, function, instance, method, module, path, property, and variable. It also includes is_container, is_dict, is_dunder, is_iterable, is_list, is_nested, is_object, is_private, is_sequence, is_set, and is_tuple. is_file and is_folder are short aliases of is_file_path and is_folder_path.

So, for example,

• catalog_methods: returns a dict of the method names and methods of an object.
• collect_methods: returns a list of methods of an object.
• has_methods: returns whether an object has all (or, if match_all = False, any) of the named methods passed to the names parameter.
• is_method: returns whether an item is a method of an object.
• name_methods: returns a list of names of methods of an object.

Getting started

“Go into a room too fast, kid… The room eats you.” - Detective Josephus Miller

Requirements

miller requires Python 3.11 or later and has no other dependencies. It runs on Linux, MacOS, and Windows.

Installation

To install miller, use pip:

pip install miller

Usage

import dataclasses

import miller


@dataclasses.dataclass
class Example:
    one: int = 1
    _two: int = 2

    def add(self, other: int) -> int:
        return self.one + other

    @property
    def double(self) -> int:
        return self.one * 2


item = Example()

miller.name_methods(item)  # ['add']
miller.name_properties(item)  # ['double']
miller.name_fields(item)  # ['one']
miller.name_fields(item, include_privates=True)  # ['one', '_two']
miller.catalog_variables(item)  # {'one': 1}
miller.has_methods(item, "add")  # True
miller.is_property(item, "double")  # True
miller.name_functions(miller.framework)  # functions defined in a module
miller.name_modules("src/miller")  # python modules in a folder

Functions that check whether an item qualifies (has_* and is_*) return False by default. Pass raise_error = True (or call miller.set_raise_errors(True)) to have them raise an error instead. The miller.set_* functions change the global defaults for include_privates, include_str, match_all, raise_errors, recursive, module file suffixes, and the function used to name items.

miller also provides Inspector, which returns an object-oriented inspector appropriate to whatever is passed to it (a module, a folder, a class, or an instance):

inspector = miller.Inspector(item)
inspector.methods  # {'add': <bound method Example.add ...>}
inspector.variables  # {'one': 1}
inspector.fields  # {'one': Field(...)}

Contributing

Contributors are always welcome. Feel free to grab an issue to work on or make a suggested improvement. If you wish to contribute, please read the Contribution Guide and Code of Conduct.

Similar Projects

The standard library's inspect module offers the underlying tools that miller wraps in a more consistent syntax.

License

Use of this repository is authorized under the Apache Software License 2.0.