Last round of doc-changes before 0.6.0

It should be pushed out in the next few moments.

HISTORY.rst

 History/Changelog
 =================
-0.6.0: 2013-xx-xx
+0.6.0: 2013-04-05
 -----------------
 - Add ``sort`` and ``order`` parameters to ``github3.GitHub.search_users`` and 
@@ -12,7 +12,8 @@ History/Changelog
 - Add minimal logging (e.g., ``logging.getLogger('github3')``)
-- Re-organize the library.
+- Re-organize the library a bit. (Split up repos.py, issues.py, gists.py and a 
+  few others into sub-modules for my sanity.)
 - Calling ``refresh(True)`` on a ``github3.structs.GitHubIterator`` actually 
   works as expected now.
@@ -31,6 +32,15 @@ History/Changelog
 - ``IssueComment.update`` was corrected to match GitHub's documentation
+- ``github3.login`` now accepts an optional ``url`` parameter for users of the 
+  ``GitHubEnterprise`` API, courtesy of Kristian Glass (@doismellburning)
+
+- Several classes now allow their instances to be compared with ``==`` and 
+  ``!=``. In most cases this will check the unique id provided by GitHub. In 
+  others, it will check SHAs and any other guaranteed immutable and unique 
+  attribute. The class doc-strings all have information about this and details 
+  about how equivalence is determined.
+
 0.5.3: 2013-03-19
 -----------------

github3/auths.py

@@ -11,7 +11,20 @@ from github3.models import GitHubCore
 class Authorization(GitHubCore):
-    """The :class:`Authorization <Authorization>` object."""
+    """The :class:`Authorization <Authorization>` object.
+
+    Two authorization instances can be checked like so::
+
+        a1 == a2
+        a1 != a2
+
+    And is equivalent to::
+
+        a1.id == a2.id
+        a1.id != a2.id
+
+    See also: http://developer.github.com/v3/oauth/#oauth-authorizations-api
+    """
     def __init__(self, auth, session=None):
         super(Authorization, self).__init__(auth, session)
         #: Details about the application (name, url)

github3/events.py

@@ -13,6 +13,17 @@ class Event(GitHubObject):
     """The :class:`Event <Event>` object. It structures and handles the data
     returned by via the `Events <http://developer.github.com/v3/events>`_
     section of the GitHub API.
+
+    Two events can be compared like so::
+
+        e1 == e2
+        e1 != e2
+
+    And that is equivalent to::
+
+        e1.id == e2.id
+        e1.id != e2.id
+
     """
     def __init__(self, event):
         super(Event, self).__init__(event)

github3/gists/comment.py

@@ -6,6 +6,16 @@ class GistComment(BaseComment):
     """The :class:`GistComment <GistComment>` object. This represents a comment
     on a gist.
+    Two comment instances can be checked like so::
+
+        c1 == c2
+        c1 != c2
+
+    And is equivalent to::
+
+        c1.id == c2.id
+        c1.id != c2.id
+
     See also: http://developer.github.com/v3/gists/comments/
     """
     def __init__(self, comment, session=None):

github3/gists/gist.py

@@ -21,6 +21,16 @@ class Gist(GitHubCore):
     you own it).  You can also "star" or "unstar" the gist (again assuming you
     have authenticated).
+    Two gist instances can be checked like so::
+
+        g1 == g2
+        g1 != g2
+
+    And is equivalent to::
+
+        g1.id == g2.id
+        g1.id != g2.id
+
     See also: http://developer.github.com/v3/gists/
     """
     def __init__(self, data, session=None):

github3/gists/history.py

@@ -4,7 +4,19 @@ from github3.users import User
 class GistHistory(GitHubCore):
     """The :class:`GistHistory <GistHistory>` object represents one version
-    (or revision) of a gist."""
+    (or revision) of a gist.
+
+    Two history instances can be checked like so::
+
+        h1 == h2
+        h1 != h2
+
+    And is equivalent to::
+
+        h1.version == h2.version
+        h1.version != h2.version
+
+    """
     def __init__(self, history, session=None):
         super(GistHistory, self).__init__(history, session)
         self._api = history.get('url', '')

github3/issues/comment.py

@@ -6,6 +6,16 @@ class IssueComment(BaseComment):
     """The :class:`IssueComment <IssueComment>` object. This structures and
     handles the comments on issues specifically.
+    Two comment instances can be checked like so::
+
+        c1 == c2
+        c1 != c2
+
+    And is equivalent to::
+
+        c1.id == c2.id
+        c1.id != c2.id
+
     See also: http://developer.github.com/v3/issues/comments/
     """
     def __init__(self, comment, session=None):

github3/issues/event.py

@@ -6,6 +6,17 @@ class IssueEvent(GitHubCore):
     with events described in the
     `Issues\>Events <http://developer.github.com/v3/issues/events>`_ section of
     the GitHub API.
+
+    Two event instances can be checked like so::
+
+        e1 == e2
+        e1 != e2
+
+    And is equivalent to::
+
+        e1.commit_id == e2.commit_id
+        e1.commit_id != e2.commit_id
+
     """
     def __init__(self, event, issue=None):
         super(IssueEvent, self).__init__(event, None)

github3/issues/issue.py

@@ -13,6 +13,17 @@ class Issue(GitHubCore):
     """The :class:`Issue <Issue>` object. It structures and handles the data
     returned via the `Issues <http://developer.github.com/v3/issues>`_ section
     of the GitHub API.
+
+    Two issue instances can be checked like so::
+
+        i1 == i2
+        i1 != i2
+
+    And is equivalent to::
+
+        i1.id == i2.id
+        i1.id != i2.id
+
     """
     def __init__(self, issue, session=None):
         super(Issue, self).__init__(issue, session)

github3/notifications.py

@@ -16,6 +16,16 @@ class Thread(GitHubCore):
     contains information about the repository generating the notification, the
     subject, and the reason.
+    Two thread instances can be checked like so::
+
+        t1 == t2
+        t1 != t2
+
+    And is equivalent to::
+
+        t1.id == t2.id
+        t1.id != t2.id
+
     See also:
     http://developer.github.com/v3/activity/notifications/#view-a-single-thread
     """

github3/orgs.py

@@ -17,6 +17,16 @@ from github3.decorators import requires_auth
 class Team(GitHubCore):
     """The :class:`Team <Team>` object.
+    Two team instances can be checked like so::
+
+        t1 == t2
+        t1 != t2
+
+    And is equivalent to::
+
+        t1.id == t2.id
+        t1.id != t2.id
+
     See also: http://developer.github.com/v3/orgs/teams/
     """
     def __init__(self, team, session=None):
@@ -155,6 +165,16 @@ class Team(GitHubCore):
 class Organization(BaseAccount):
     """The :class:`Organization <Organization>` object.
+    Two organization instances can be checked like so::
+
+        o1 == o2
+        o1 != o2
+
+    And is equivalent to::
+
+        o1.id == o2.id
+        o1.id != o2.id
+
     See also: http://developer.github.com/v3/orgs/
     """
     def __init__(self, org, session=None):

github3/pulls.py

@@ -77,6 +77,16 @@ class PullFile(GitHubObject):
 class PullRequest(GitHubCore):
     """The :class:`PullRequest <PullRequest>` object.
+    Two pull request instances can be checked like so::
+
+        p1 == p2
+        p1 != p2
+
+    And is equivalent to::
+
+        p1.id == p2.id
+        p1.id != p2.id
+
     See also: http://developer.github.com/v3/pulls/
     """
     def __init__(self, pull, session=None):
@@ -300,6 +310,16 @@ class ReviewComment(BaseComment):
     """The :class:`ReviewComment <ReviewComment>` object. This is used to
     represent comments on pull requests.
+    Two comment instances can be checked like so::
+
+        c1 == c2
+        c1 != c2
+
+    And is equivalent to::
+
+        c1.id == c2.id
+        c1.id != c2.id
+
     See also: http://developer.github.com/v3/pulls/comments/
     """
     def __init__(self, comment, session=None):

github3/repos/comment.py

@@ -13,6 +13,17 @@ from github3.users import User
 class RepoComment(BaseComment):
     """The :class:`RepoComment <RepoComment>` object. This stores the
     information about a comment on a file in a repository.
+
+    Two comment instances can be checked like so::
+
+        c1 == c2
+        c1 != c2
+
+    And is equivalent to::
+
+        c1.id == c2.id
+        c1.id != c2.id
+
     """
     def __init__(self, comment, session=None):
         super(RepoComment, self).__init__(comment, session)

github3/repos/commit.py

@@ -15,8 +15,18 @@ class RepoCommit(BaseCommit):
     """The :class:`RepoCommit <RepoCommit>` object. This represents a commit as
     viewed by a :class:`Repository`. This is different from a Commit object
     returned from the git data section.
-    """
+    Two commit instances can be checked like so::
+
+        c1 == c2
+        c1 != c2
+
+    And is equivalent to::
+
+        c1.sha == c2.sha
+        c1.sha != c2.sha
+
+    """
     def __init__(self, commit, session=None):
         super(RepoCommit, self).__init__(commit, session)
         #: :class:`User <github3.users.User>` who authored the commit.
@@ -50,6 +60,12 @@ class RepoCommit(BaseCommit):
     def __repr__(self):
         return '<Repository Commit [{0}]>'.format(self.sha[:7])
+    def __eq__(self, other):
+        return self.sha == other.sha
+
+    def __ne__(self, other):
+        return self.sha != other.sha
+
     def diff(self):
         """Return the diff"""
         resp = self._get(self._api,

github3/repos/comparison.py

@@ -16,6 +16,16 @@ class Comparison(GitHubCore):
     information returned by GitHub comparing two commit objects in a
     repository.
+    Two comparison instances can be checked like so::
+
+        c1 == c2
+        c1 != c2
+
+    And is equivalent to::
+
+        c1.commits == c2.commits
+        c1.commits != c2.commits
+
     See also:
     http://developer.github.com/v3/repos/commits/#compare-two-commits
     """
@@ -49,6 +59,12 @@ class Comparison(GitHubCore):
     def __repr__(self):
         return '<Comparison of {0} commits>'.format(self.total_commits)
+    def __eq__(self, other):
+        return self.commits == other.commits
+
+    def __ne__(self, other):
+        return self.commits != other.commits
+
     def diff(self):
         """Return the diff"""
         resp = self._get(self._api,

github3/repos/contents.py

@@ -15,6 +15,16 @@ class Contents(GitHubObject):
     """The :class:`Contents <Contents>` object. It holds the information
     concerning any content in a repository requested via the API.
+    Two content instances can be checked like so::
+
+        c1 == c2
+        c1 != c2
+
+    And is equivalent to::
+
+        c1.sha == c2.sha
+        c1.sha != c2.sha
+
     See also: http://developer.github.com/v3/repos/contents/
     """
     def __init__(self, content):
@@ -52,7 +62,6 @@ class Contents(GitHubObject):
         self.size = content.get('size', 0)
         #: SHA string.
         self.sha = content.get('sha', '')
-
         # should always be 'file'
         #: Type of content.
         self.type = content.get('type', '')
@@ -63,6 +72,12 @@ class Contents(GitHubObject):
     def __str__(self):
         return self.decoded
+    def __eq__(self, other):
+        return self.sha == other.sha
+
+    def __ne__(self, other):
+        return self.sha != other.sha
+
     @property
     def git_url(self):
         """API URL for this blob"""

github3/repos/download.py

@@ -9,8 +9,11 @@ class Download(GitHubCore):
     .. warning::
-        On 2013-03-11, this API will be deprecated by GitHub. There will also
-        be a new version of github3.py to accompany this at that date.
+        On 2013-03-11, this API was suppoed to be deprecated by GitHub. This
+        means that at any time, GitHub could deprecate this part of the API at
+        any time without further notice. Until I find out it has been
+        deprecated, this will remain part of the API, although it will be
+        unsupported.
     """
     def __init__(self, download, session=None):

github3/repos/hook.py

@@ -15,6 +15,16 @@ class Hook(GitHubCore):
     """The :class:`Hook <Hook>` object. This handles the information returned
     by GitHub about hooks set on a repository.
+    Two hook instances can be checked like so::
+
+        h1 == h2
+        h1 != h2
+
+    And is equivalent to::
+
+        h1.id == h2.id
+        h1.id != h2.id
+
     See also: http://developer.github.com/v3/repos/hooks/
     """
     def __init__(self, hook, session=None):

github3/repos/repo.py

@@ -35,6 +35,16 @@ class Repository(GitHubCore):
     """The :class:`Repository <Repository>` object. It represents how GitHub
     sends information about repositories.
+    Two repository instances can be checked like so::
+
+        r1 == r2
+        r1 != r2
+
+    And is equivalent to::
+
+        r1.id == r2.id
+        r1.id != r2.id
+
     See also: http://developer.github.com/v3/repos/
     """
     def __init__(self, repo, session=None):

github3/users.py

@@ -14,7 +14,18 @@ from github3.decorators import requires_auth
 class Key(GitHubCore):
     """The :class:`Key <Key>` object. Please see GitHub's `Key Documentation
-    <http://developer.github.com/v3/users/keys/>`_ for more information."""
+    <http://developer.github.com/v3/users/keys/>`_ for more information.
+
+    Two key instances can be checked like so::
+
+        k1 == k2
+        k1 != k2
+
+    And is equivalent to::
+
+        k1.id == k2.id
+        k1.id != k2.id
+    """
     def __init__(self, key, session=None):
         super(Key, self).__init__(key, session)
         self._api = key.get('url', '')
@@ -97,6 +108,16 @@ class Plan(GitHubObject):
 class User(BaseAccount):
     """The :class:`User <User>` object. This handles and structures information
     in the `User section <http://developer.github.com/v3/users/>`_.
+
+    Two user instances can be checked like so::
+
+        u1 == u2
+        u1 != u2
+
+    And is equivalent to::
+
+        u1.id == u2.id
+        u1.id != u2.id
     """
     def __init__(self, user, session=None):
         super(User, self).__init__(user, session)