Misc design discussions

[thorwhalen]

This is a place to discuss miscellaneous design deliberations when we believe the discussion won't be a long one, so don't want to litter the discussion space with a specific subject.

Start discussion in comments, and discuss in comments' replies.

[thorwhalen]

objects_defined_in_module uses vars to get its objects, but there's also inspect.getmembers as a choice for this (cast to a dict).

Which is better to use? Should we switch from vars to inspect.getmembers?

[thorwhalen]

Though there's differences when you apply getmembers to non-module objects, I don't see any for modules (community, prove me wrong!).

If that's the case, I'd stick with vars simply because it doesn't need the inspect import.

To those that may put forth the "but with getmembers you can filter (the predictate argument) I will say: Yes, but we want to also filter by name, not just object. Also, the name filter, if present, will happen BEFORE the object filter, which enables better performance (not that it matters here) and simpler object filters (since some stuff can be filtered away by the names already).

[thorwhalen]

Again, it doesn't apply to our module case, but the difference between vars and getmembers becomes apparent when dealing with classes. vars will only include the members that are directly part of the class, whereas inspect.getmembers will include both the members of the class and the members from its parent classes.

Here's an example to illustrate this:

class A:
    def method_a(self):
        pass

class B(A):
    def method_b(self):
        pass

import inspect

print("vars(B):", vars(B).keys())
# vars(B): dict_keys(['__module__', 'method_b', '__doc__'])
print("inspect.getmembers(B):", [name for name, value in inspect.getmembers(B)])
# inspect.getmembers(B): ['__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', 'method_a', 'method_b']

In this code, vars(B) only includes method_b and some other class-related attributes, but not method_a. On the other hand, inspect.getmembers(B) includes both method_a and method_b, because B inherits from A.

So, for modules, vars and inspect.getmembers (without filtering) should give you the same results. The real difference comes when you deal with classes and you want to see inherited members.