API Iterators/generators consistency

[yannayl]

Hello,

Almost in every class there are many iterator/generator properties and methods.
Sometimes it's a method (e.g. CodeBlock.succs() is a generator of succeeding blocks) and sometimes it's a property (e.g. CodeBlock.prev). I failed to understand when a property is used and when a method is used which makes the library less usable. It's quite confusing and forces the user to check the documentation more frequently than necessary (which reduces usability and makes the library 'surprising' in a bad way).

If there is any logic behind these decisions, can you share and document them?
If not, can you align it please?

Thanks

[tmr232]

Honestly, I don't longer remember the reasoning, and will have to go over it.
As for aligning it - I am concerned about backwards compatibility. what do you think?

[yannayl]

Is it possible (though it's horrible) to support both simultaneously somehow (and mark one way as deprecated)?
Any other solution would obv. break compatibility. This is life. Libraries evolve.

P.S. as you know, I have my fair share of scripts to update accordingly, I am not taking it lightly.

[arizvisa]

In case you guys want this, I needed something pretty similar at one point and I wrote some pretty hacky-looking code that combines an iterator with a list. It adds a .reset() method which will reset the iterator, but it forwards all list methods to the backend list, and implements all the methods implemented by the real listiterator. This way it should act just like a regular python2 iterator despite it being stored internally as a list.

class listiterator(object):
    def __init__(self, iterator=()):
        self.__state__ = list(iterator)
        self.reset()

    def reset(self):
        self.__sequence__ = iter(self.__state__)
        return self
        
    def next(self):
        return next(self.__sequence__)

    def __getattr__(self, name):
        return getattr(self.__state__, name)

    def __iter__(self):
        return self.__sequence__

    def __length_hint__(self):
        return len(self.__state__)

# sneak out a method constructor
imcons = type(listiterator.__init__)

# call a method from an object using a closure to fetch it
methodcaller = lambda attribute: lambda self, *args, **kwargs: (lambda method=getattr(list, attribute): method(self.__state__, *args, **kwargs))()

# filter out all the descriptors that we need to copy from the `list` type
descriptors = (name for name in dir(list) if name not in listiterator.__dict__ and name not in object.__dict__)
descriptors = ((name, getattr(list, name)) for name in descriptors if name.startswith('__'))
descriptors = (name for name, value in descriptors if callable(value) and getattr(value, '__objclass__', None) == list)

# use methodcaller to construct an unbound method for the method descriptors we snagged 
for name in descriptors:
    setattr(listiterator, name, imcons(methodcaller(name), None, listiterator))

(edited to add comments)