Roadmap for 1.0

[sigmavirus24]

Strictly for 1.0

• Rename iter_* methods to *, e.g., iter_pulls -> pulls.
• Rename to_json to as_json. (thanks @esacteksab)
• Expose the requests.Session object to allow for completion of #79
• Rename _api attribute to url (or api_url) attribute to publicly expose it.
• Expand errors that can be raised
  • Document new exception classes.
• Use NullObject
• Items tagged with milestone 1.0 (or with no fix yet commited)

Can be introduced before 1.0

• Documentation overhaul #191
• Use betamax to get more accurate test data
• #88
• #94
• #118
• #128

Possibly not necessary

• #119

--- Want to back this issue? **[Post a bounty on it!](https://www.bountysource.com/issues/3657821-roadmap-for-1-0?utm_campaign=plugin&utm_content=tracker%2F183477&utm_medium=issues&utm_source=github)** We accept bounties via [Bountysource](https://www.bountysource.com/?utm_campaign=plugin&utm_content=tracker%2F183477&utm_medium=issues&utm_source=github).

[sigmavirus24]

I'd like to entertain the idea of using the "Null Object Pattern" in github3.py following a discussion a while back with @doismellburning on Twitter.

We could either use this quick implementation I whipped up:

class NullObject(object):
    def __init__(self, initializer=None):
        self.__dict__['initializer'] = initializer

    def __repr__(self):
        return '<NullObject({0})>'.format(
            repr(self.__getattribute__('initializer'))
            )

    def __getitem__(self, index):
        return self

    def __setitem__(self, index, value):
        pass

    def __getattr__(self, attr):
        return self

    def __setattr__(self, attr, value):
        pass

    def __call__(self, *args, **kwargs):
        return self

    def __contains__(self, other):
        return False

Or a different library that perhaps provides a more complete implementation since I'm sure I'm missing important magic methods. The above, however, represent only what we will need from a Null object. The instances this would be used are in the methods that currently either return an object (e.g., Repository, User, Team, Organization, etc.) or None.

Returning None is a pain. Why? Let's look at an example usage of github3.py:

import github3

u = github3.user('sigmavirus23')

In this case u is None will return True. This means that in order to be confident in what you're doing you have to then write:

if u:
    # Do something with u

And this becomes a pattern/anti-pattern. What if you could do:

import github3

u = github3.user('sigmavirus23')
for follower in u.iter_followers():
     follower.follow()

You would have no exceptions and no need to check for None. The only issue I see right now is that with my (probably shoddy) implementation, if you were looking to print the list of followers, you would see a solitary: <NullObject(None)> (or possibly something else like <NullObject('User')>. This might be confusing, so I'll probably need to figure out the proper way to handle the __str__/__unicode__ magic methods to get this to work as I would like. (Basically it wouldn't print anything because str(NullObject()) would be ''.)

I'd like feedback from heavy users like @douglarek and @seveas too since they're the first ones that come to mind. Of course feedback here, or via email from other users who I'm not so familiar with is also very sincerely appreciated.

[douglarek]

@sigmavirus24 This is a good idea, and it reduces the need for conditional statements

[sigmavirus24]

I'm impatient so I'm starting work on 1.0 on a branch on here but NO ONE SHOULD USE IT. It will be incredibly unstable for a while.

[sigmavirus24]

The NullObject is happening: 0d10740

[megawac]

Is this up to date? Been watching the recent aactivity --- looking forward to 1.0!

[sigmavirus24]

I'm working on 1.0 right now on the 1.0-alpha branch. It's slow work but if people would like to carve out some chunks for themselves that would be awesome. Right now I'm working on renaming all of the iter_* methods. Renaming to_json to as_json should be a fairly simple PR for anyone interested. There are also some open issues right now for new features in the API that will only be available in 1.0. If you look at recent commits to 1.0-alpha you'll see a pattern to how I'm going about renaming methods.

[esacteksab]

FWIW, I think all the iter_'s have been removed in my barry-1.0 branch, but admittedly I has broken tests. :(

[guyzmo]

I saw you've pushed v1.0.0a4 as --pre version on pypi.

Do you recommend porting applications to it yet, or is it better waiting for you to push the final 1.0.0?

[sigmavirus24]

I think I will push a beta release soon which will be the best thing for applications to use to start porting.