Merge branch 'feat/auth_decorators'

JNRowe · JNRowe · commit 136bf8043bd3 · 2011-06-11T09:13:09.000+01:00
* feat/auth_decorators:
  Added enhanced_by_auth to users.show.
  Added decorator for calls that change when authenticated.
  Decorated appropriate API calls with @requires_auth.
  Added requires_auth decorator for marking API calls.

Conflicts:
	doc/api/core.rst
	github2/issues.py
	github2/users.py
diff --git a/doc/api/core.rst b/doc/api/core.rst
@@ -18,6 +18,9 @@ Core
 
 .. autofunction:: userdate_to_datetime
 
+.. autofunction:: requires_auth
+.. autofunction:: enhanced_by_auth
+
 .. autofunction:: doc_generator
 
 .. autofunction:: repr_string
diff --git a/github2/core.py b/github2/core.py
@@ -91,6 +91,45 @@ def datetime_to_isodate(datetime_):
     return "%sZ" % datetime_.isoformat()
 
 
+class AuthError(Exception):
+    """Requires authentication"""
+
+
+def requires_auth(f):
+    """Decorate to check a function call for authentication
+
+    Sets a ``requires_auth`` attribute on functions, for use in introspection.
+
+    :param func f: Function to wrap
+    :raises AuthError: If function called without an authenticated session
+    """
+    # When Python 2.4 support is dropped move straight to functools.wraps, don't
+    # pass go and don't collect $200.
+    def wrapper(self, *args, **kwargs):
+        if not self.request.access_token and not self.request.api_token:
+            raise AuthError("%r requires an authenticated session"
+                            % f.__name__)
+        return f(self, *args, **kwargs)
+    wrapped = wrapper
+    wrapped.__name__ = f.__name__
+    wrapped.__doc__ = f.__doc__ + """\n.. warning:: Requires authentication"""
+    wrapped.requires_auth = True
+    return wrapped
+
+
+def enhanced_by_auth(f):
+    """Decorator to mark a function as enhanced by authentication
+
+    Sets a ``enhanced_by_auth`` attribute on functions, for use in
+    introspection.
+
+    :param func f: Function to wrap
+    """
+    f.enhanced_by_auth = True
+    f.__doc__ += """\n.. note:: This call is enhanced with authentication"""
+    return f
+
+
 class GithubCommand(object):
 
     def __init__(self, request):
diff --git a/github2/issues.py b/github2/issues.py
@@ -1,7 +1,7 @@
 import urllib
 
 from github2.core import (GithubCommand, BaseData, Attribute, DateAttribute,
-                          repr_string)
+                          repr_string, requires_auth)
 
 
 class Issue(BaseData):
@@ -89,6 +89,7 @@ def show(self, project, number):
         return self.get_value("show", project, str(number),
                               filter="issue", datatype=Issue)
 
+    @requires_auth
     def open(self, project, title, body):
         """Open up a new issue.
 
@@ -100,6 +101,7 @@ def open(self, project, title, body):
         return self.get_value("open", project, post_data=issue_data,
                               filter="issue", datatype=Issue)
 
+    @requires_auth
     def close(self, project, number):
         """Close an issue
 
@@ -109,6 +111,7 @@ def close(self, project, number):
         return self.get_value("close", project, str(number), filter="issue",
                               datatype=Issue, method="POST")
 
+    @requires_auth
     def reopen(self, project, number):
         """Reopen a closed issue
 
@@ -120,6 +123,7 @@ def reopen(self, project, number):
         return self.get_value("reopen", project, str(number), filter="issue",
                               datatype=Issue, method="POST")
 
+    @requires_auth
     def edit(self, project, number, title, body):
         """Edit an existing issue
 
@@ -135,6 +139,7 @@ def edit(self, project, number, title, body):
                               post_data=issue_data, filter="issue",
                               datatype=Issue)
 
+    @requires_auth
     def add_label(self, project, number, label):
         """Add a label to an issue
 
@@ -145,6 +150,7 @@ def add_label(self, project, number, label):
         return self.make_request("label/add", project, label, str(number),
                                  filter="labels", method="POST")
 
+    @requires_auth
     def remove_label(self, project, number, label):
         """Remove an existing label from an issue
 
@@ -155,6 +161,7 @@ def remove_label(self, project, number, label):
         return self.make_request("label/remove", project, label, str(number),
                                  filter="labels", method="POST")
 
+    @requires_auth
     def comment(self, project, number, comment):
         """Comment on an issue.
 
diff --git a/github2/repositories.py b/github2/repositories.py
@@ -1,4 +1,5 @@
-from github2.core import BaseData, GithubCommand, Attribute, DateAttribute
+from github2.core import (BaseData, GithubCommand, Attribute, DateAttribute,
+                          requires_auth)
 
 from github2.users import User
 
@@ -50,6 +51,7 @@ def show(self, project):
         return self.get_value("show", project, filter="repository",
                               datatype=Repository)
 
+    @requires_auth
     def pushable(self):
         """Return a list of repos you can push to that are not your own.
 
@@ -72,20 +74,23 @@ def list(self, user=None):
         return self.get_values("show", user, filter="repositories",
                                datatype=Repository)
 
+    @requires_auth
     def watch(self, project):
         """Watch a project
 
         :param str project: GitHub project
         """
         return self.make_request("watch", project)
 
+    @requires_auth
     def unwatch(self, project):
         """Unwatch a project
 
         :param str project: GitHub project
         """
         return self.make_request("unwatch", project)
 
+    @requires_auth
     def fork(self, project):
         """Fork a project
 
@@ -94,6 +99,7 @@ def fork(self, project):
         return self.get_value("fork", project, filter="repository",
                               datatype=Repository)
 
+    @requires_auth
     def create(self, project, description=None, homepage=None, public=True):
         """Create a repository
 
@@ -107,6 +113,7 @@ def create(self, project, description=None, homepage=None, public=True):
         return self.get_value("create", post_data=repo_data,
                               filter="repository", datatype=Repository)
 
+    @requires_auth
     def delete(self, project):
         """Delete a repository
 
@@ -117,13 +124,15 @@ def delete(self, project):
         result = self.make_request("delete", project, method="POST")
         self.make_request("delete", project, post_data=result)
 
+    @requires_auth
     def set_private(self, project):
         """Mark repository as private
 
         :param str project: project name to set as private
         """
         return self.make_request("set/private", project)
 
+    @requires_auth
     def set_public(self, project):
         """Mark repository as public
 
@@ -139,6 +148,7 @@ def list_collaborators(self, project):
         return self.make_request("show", project, "collaborators",
                                  filter="collaborators")
 
+    @requires_auth
     def add_collaborator(self, project, username):
         """Adds an add_collaborator to a repo
 
@@ -147,6 +157,7 @@ def add_collaborator(self, project, username):
         """
         return self.make_request("collaborators", project, "add", username)
 
+    @requires_auth
     def remove_collaborator(self, project, username):
         """Removes an add_collaborator from a repo
 
diff --git a/github2/users.py b/github2/users.py
@@ -1,4 +1,5 @@
-from github2.core import BaseData, GithubCommand, DateAttribute, Attribute
+from github2.core import (BaseData, GithubCommand, DateAttribute, Attribute,
+                          enhanced_by_auth, requires_auth)
 import urllib
 
 
@@ -54,6 +55,7 @@ def search_by_email(self, query):
         """
         return self.get_value("email", query, filter="user", datatype=User)
 
+    @enhanced_by_auth
     def show(self, username):
         """Get information on Github user
 
@@ -78,13 +80,15 @@ def following(self, username):
         """
         return self.make_request("show", username, "following", filter="users")
 
+    @requires_auth
     def follow(self, other_user):
         """Follow a Github user
 
         :param str other_user: Github user name
         """
         return self.make_request("follow", other_user)
 
+    @requires_auth
     def unfollow(self, other_user):
         """Unfollow a Github user
 
