New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Roadmap for 1.0 #122

Closed
sigmavirus24 opened this Issue Aug 3, 2013 · 9 comments

Comments

Projects
None yet
5 participants
@sigmavirus24
Owner

sigmavirus24 commented Aug 3, 2013

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

Possibly not necessary

--- 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

This comment has been minimized.

Owner

sigmavirus24 commented Jan 13, 2014

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

This comment has been minimized.

douglarek commented Jan 14, 2014

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

@sigmavirus24

This comment has been minimized.

Owner

sigmavirus24 commented Jan 16, 2014

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

This comment has been minimized.

Owner

sigmavirus24 commented Jan 21, 2014

The NullObject is happening: 0d10740

@megawac

This comment has been minimized.

Contributor

megawac commented Aug 11, 2014

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

@sigmavirus24

This comment has been minimized.

Owner

sigmavirus24 commented Aug 11, 2014

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

This comment has been minimized.

Collaborator

esacteksab commented Aug 21, 2014

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

@guyzmo

This comment has been minimized.

guyzmo commented Jan 31, 2017

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

This comment has been minimized.

Owner

sigmavirus24 commented Jan 31, 2017

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment