Skip to content
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
15 tasks done
sigmavirus24 opened this issue Aug 3, 2013 · 9 comments
Closed
15 tasks done

Roadmap for 1.0 #122

sigmavirus24 opened this issue Aug 3, 2013 · 9 comments
Milestone

Comments

@sigmavirus24
Copy link
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 Caching support! #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
Copy link
Owner Author

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

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

@sigmavirus24
Copy link
Owner Author

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
Copy link
Owner Author

The NullObject is happening: 0d10740

@megawac
Copy link
Contributor

megawac commented Aug 11, 2014

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

@sigmavirus24
Copy link
Owner Author

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
Copy link
Collaborator

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

@guyzmo
Copy link

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
Copy link
Owner Author

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
Labels
None yet
Projects
None yet
Development

No branches or pull requests

5 participants