dahlia
diff --git a/‎HISTORY.rst
Lines changed: 9 additions & 1 deletion b/‎HISTORY.rst
Lines changed: 9 additions & 1 deletion
diff --git a/‎docs/examples/iterators.rst
Lines changed: 53 additions & 0 deletions b/‎docs/examples/iterators.rst
Lines changed: 53 additions & 0 deletions
diff --git a/‎docs/examples/logging.rst
Lines changed: 34 additions & 0 deletions b/‎docs/examples/logging.rst
Lines changed: 34 additions & 0 deletions
diff --git a/‎docs/examples/source/logging_ex.py
Lines changed: 29 additions & 0 deletions b/‎docs/examples/source/logging_ex.py
Lines changed: 29 additions & 0 deletions
diff --git a/‎docs/index.rst
Lines changed: 3 additions & 0 deletions b/‎docs/index.rst
Lines changed: 3 additions & 0 deletions
diff --git a/‎docs/structs.rst
Lines changed: 22 additions & 0 deletions b/‎docs/structs.rst
Lines changed: 22 additions & 0 deletions
diff --git a/‎github3/api.py
Lines changed: 46 additions & 22 deletions b/‎github3/api.py
Lines changed: 46 additions & 22 deletions
@@ -10,7 +10,15 @@ History/Changelog
 - Add ``iter_commits`` to ``github3.gists.Gist`` as a means of re-requesting 
   just the history from GitHub and iterating over it.
 
-- Re-organize the library
+- Add minimal logging (e.g., ``logging.getLogger('github3')``)
+
+- Re-organize the library.
+
+- Calling ``refresh(True)`` on a ``github3.structs.GitHubIterator`` actually 
+  works as expected now.
+
+- API ``iter_`` methods now accept the ``etag`` argument as the
+  ``GitHub.iter_`` methods do.
 
 - Remove vendored dependency of PySO8601.
 
 
@@ -0,0 +1,53 @@
+.. _iteratorex:
+
+Taking Advantage of GitHubIterator
+==================================
+
+Let's say that for some reason you're stalking all of GitHub's users and you 
+just so happen to be using github3.py to do this. You might write code that 
+looks like this:
+
+.. code-block:: python
+
+    import github3
+
+    g = github3.login(USERNAME, PASSWORD)
+
+    for u in g.iter_all_users():
+        add_user_to_database(u)
+
+The problem is that you will then have to reiterate over all of the users each 
+time you want to get the new users. You have two approaches you can take to 
+avoid this with :class:`GitHubIterator <github3.structs.GitHubIterator>`.
+
+The First Approach
+------------------
+
+You can not call the method directly in the for-loop and keep the iterator as 
+a separate reference like so:
+
+.. code-block:: python
+
+    i = g.iter_all_users():
+
+    for u in i:
+        add_user_to_database(u)
+
+Then after your first pass through your ``GitHubIterator`` object will have an 
+attribute named ``etag``. After you've added all the currently existing users 
+you could do the following to retrieve the new users in a timely fashion:
+
+.. code-block:: python
+
+    import time
+
+    while True:
+        i.refresh(True)
+        for u in i:
+            add_user_to_database(u)
+
+        time.sleep(120)  # Sleep for 2 minutes
+
+If there are no new users, this won't impact your ratelimit at all. This 
+mimics the ability to conditionally refresh data on almost all other objects 
+in github3.py.
@@ -0,0 +1,34 @@
+.. _loggingex:
+
+Using Logging with github3.py
+=============================
+
+.. versionadded:: 0.6.0
+
+The following example shows how to set up logging for github3.py. It is off by 
+default in the library and will not pollute your logs.
+
+.. include:: source/logging_ex.py
+    :code: python
+
+One thing to note is that if you want more detailed information about what is 
+happening while the requests are sent, you can do the following:
+
+.. code-block:: python
+
+    import logging
+    urllib3 = logging.getLogger('requests.packages.urllib3')
+
+And configure the logger for urllib3. Unfortunately, requests itself doesn't 
+provide any logging, so the best you can actually get is by configuring 
+``urllib3``.
+
+You will see messages about the following in the logs:
+
+* Construction of URLs used in requests, usually in the form: 
+  ``('https://api.github.com', 'repos', 'sigmavirus24', 'github3.py')``
+* What request is being sent, e.g.,
+  ``POST https://api.github.com/user kwargs={}``
+* If JSON is trying to be extracted from the response, what the response's 
+  status code was, what the expected status code was and whether any JSON was 
+  actually returned.
@@ -0,0 +1,29 @@
+import github3
+import logging
+
+# Set up a file to have all the logs written to
+file_handler = logging.FileHandler('github_script.log')
+
+# Send the logs to stderr as well
+stream_handler = logging.StreamHandler()
+
+# Format the log output and include the log level's name and the time it was
+# generated
+formatter = logging.Formatter('%(asctime)s %(levelname)s %(message)s')
+
+# Use that Formatter on both handlers
+file_handler.setFormatter(formatter)
+stream_handler.setFormatter(formatter)
+
+# Get the logger used by github3.py internally by referencing its name
+# directly
+logger = logging.getLogger('github3')
+# Add the handlers to it
+logger.addHandler(file_handler)
+logger.addHandler(stream_handler)
+# Set the level which determines what you see
+logger.setLevel(logging.DEBUG)
+
+# Make a library call and see the information posted
+r = github3.repository('sigmavirus24', 'github3.py')
+print('{0} - {0.html_url}'.format(r))
@@ -49,6 +49,8 @@ More Examples
     examples/git
     examples/github
     examples/issue
+    examples/iterators.rst
+    examples/logging
 
 
 .. links
@@ -74,6 +76,7 @@ Modules
     orgs
     pulls
     repos
+    structs
     users
 
 Internals
 
@@ -0,0 +1,22 @@
+.. module:: github3
+.. module:: github3.structs
+
+Structures developed for github3.py
+===================================
+
+As of right now, there exists only one class in this file, and it is of only
+limited importance to users of github3.py. The :class:`GitHubIterator` class 
+is used to return the results of calls to almost all of the calls to ``iter_`` 
+methods on objects. When conditional refreshing was added to objects, there 
+was a noticable gap in having conditional calls to those ``iter_`` methods.  
+GitHub provides the proper headers on those calls, but there was no easy way 
+to add that to what github3.py returned so it could be used properly. This was 
+the best compromise - an object the behaves like an iterator regardless but 
+can also be ``refresh``\ ed to get results since the last request 
+conditionally.
+
+Objects
+-------
+
+.. autoclass:: GitHubIterator
+    :inherited-members:
@@ -74,74 +74,86 @@ def gitignore_templates():
     return gh.gitignore_templates()
 
 
-def iter_all_repos(number=-1):
+def iter_all_repos(number=-1, etag=None):
     """Iterate over every repository in the order they were created.
 
     :param int number: (optional), number of repositories to return.
         Default: -1, returns all of them
+    :param str etag: (optional), ETag from a previous request to the same
+        endpoint
     :returns: generator of :class:`Repository <github3.repos.Repository>`
     """
-    return gh.iter_all_repos(number)
+    return gh.iter_all_repos(number, etag)
 
 
-def iter_all_users(number=-1):
+def iter_all_users(number=-1, etag=None):
     """Iterate over every user in the order they signed up for GitHub.
 
     :param int number: (optional), number of users to return. Default: -1,
         returns all of them
+    :param str etag: (optional), ETag from a previous request to the same
+        endpoint
     :returns: generator of :class:`User <github3.users.User>`
     """
-    return gh.iter_all_users(number)
+    return gh.iter_all_users(number, etag)
 
 
-def iter_events(number=-1):
+def iter_events(number=-1, etag=None):
     """Iterate over public events.
 
     :param int number: (optional), number of events to return. Default: -1
         returns all available events
+    :param str etag: (optional), ETag from a previous request to the same
+        endpoint
     :returns: generator of :class:`Event <github3.events.Event>`\ s
     """
-    return gh.iter_events(number)
+    return gh.iter_events(number, etag)
 
 
-def iter_followers(username, number=-1):
+def iter_followers(username, number=-1, etag=None):
     """List the followers of ``username``.
 
     :param str username: (required), login of the person to list the followers
         of
     :param int number: (optional), number of followers to return, Default: -1,
         return all of them
+    :param str etag: (optional), ETag from a previous request to the same
+        endpoint
     :returns: generator of :class:`User <github3.users.User>`
     """
-    return gh.iter_followers(username, number) if username else []
+    return gh.iter_followers(username, number, etag) if username else []
 
 
-def iter_following(username, number=-1):
+def iter_following(username, number=-1, etag=None):
     """List the people ``username`` follows.
 
     :param str username: (required), login of the user
     :param int number: (optional), number of users being followed by username
         to return. Default: -1, return all of them
+    :param str etag: (optional), ETag from a previous request to the same
+        endpoint
     :returns: generator of :class:`User <github3.users.User>`
     """
-    return gh.iter_following(username, number) if username<
10000
/span> else []
+    return gh.iter_following(username, number, etag) if username else []
 
 
-def iter_gists(username=None, number=-1):
+def iter_gists(username=None, number=-1, etag=None):
     """Get public gists or gists for the provided username.
 
     :param str username: (optional), if provided, get the gists for this user
         instead of the authenticated user.
     :param int number: (optional), number of gists to return. Default: -1,
         return all of them
+    :param str etag: (optional), ETag from a previous request to the same
+        endpoint
     :returns: generator of :class:`Gist <github3.gists.Gist>`\ s
     """
-    return gh.iter_gists(username, number)
+    return gh.iter_gists(username, number, etag)
 
 
 def iter_repo_issues(owner, repository, milestone=None, state=None,
                      assignee=None, mentioned=None, labels=None, sort=None,
-                     direction=None, since=None, number=-1):
+                     direction=None, since=None, number=-1, etag=None):
     """List issues on owner/repository. Only owner and repository are
     required.
 
@@ -162,26 +174,32 @@ def iter_repo_issues(owner, repository, milestone=None, state=None,
         2012-05-20T23:10:27Z
     :param int number: (optional), number of issues to return.
         Default: -1 returns all issues
+    :param str etag: (optional), ETag from a previous request to the same
+        endpoint
     :returns: generator of :class:`Issue <github3.issues.Issue>`\ s
     """
     if owner and repository:
         return gh.iter_repo_issues(owner, repository, milestone, state,
                                    assignee, mentioned, labels, sort,
-                                   direction, since, number)
+                                   direction, since, number, etag)
     return iter([])
 
 
-def iter_orgs(username, number=-1):
+def iter_orgs(username, number=-1, etag=None):
     """List the organizations associated with ``username``.
 
     :param str username: (required), login of the user
     :param int number: (optional), number of orgs to return. Default: -1,
         return all of the issues
+    :param str etag: (optional), ETag from a previous request to the same
+        endpoint
+    :returns: generator of
+        :class:`Organization <github3.orgs.Organization>`\ s
     """
-    return gh.iter_orgs(username, number) if username else []
+    return gh.iter_orgs(username, number, etag) if username else []
 
 
-def iter_repos(login, type='', sort='', direction='', number=-1):
+def iter_repos(login, type='', sort='', direction='', number=-1, etag=None):
     """List public repositories for the specified ``login`` or all
     repositories for the authenticated user if ``login`` is not
     provided.
@@ -198,35 +216,41 @@ def iter_repos(login, type='', sort='', direction='', number=-1):
         'desc' otherwise
     :param int number: (optional), number of repositories to return.
         Default: -1 returns all repositories
+    :param str etag: (optional), ETag from a previous request to the same
+        endpoint
     :returns: generator of :class:`Repository <github3.repos.Repository>`
         objects
     """
     if login:
-        return gh.iter_repos(login, type, sort, direction, number)
+        return gh.iter_repos(login, type, sort, direction, number, etag)
     return iter([])
 
 
-def iter_starred(username, number=-1):
+def iter_starred(username, number=-1, etag=None):
     """Iterate over repositories starred by ``username``.
 
     :param str username: (optional), name of user whose stars you want to see
     :param int number: (optional), number of repositories to return.
         Default: -1 returns all repositories
+    :param str etag: (optional), ETag from a previous request to the same
+        endpoint
     :returns: generator of :class:`Repository <github3.repos.Repository>`
     """
-    return gh.iter_starred(username, number)
+    return gh.iter_starred(username, number, etag)
 
 
-def iter_subscriptions(username, number=-1):
+def iter_subscriptions(username, number=-1, etag=None):
     """Iterate over repositories subscribed to by ``username``.
 
     :param str username: (optional), name of user whose subscriptions you want
         to see
     :param int number: (optional), number of repositories to return.
         Default: -1 returns all repositories
+    :param str etag: (optional), ETag from a previous request to the same
+        endpoint
     :returns: generator of :class:`Repository <github3.repos.Repository>`
     """
-    return gh.iter_subscriptions(username, number)
+    return gh.iter_subscriptions(username, number, etag)
 
 
 def create_gist(description, files):