Updating all timestamp parameters to accept either a datetime or an ISO-8601 date string

carlio · carlio · commit 44f6af51351a · 2013-06-12T13:08:25.000+02:00
diff --git a/github3/api.py b/github3/api.py
@@ -174,8 +174,10 @@ def iter_repo_issues(owner, repository, milestone=None, state=None,
         api-default: created
     :param str direction: accepted values: ('asc', 'desc')
         api-default: desc
-    :param str since: ISO 8601 formatted timestamp, e.g.,
-        2012-05-20T23:10:27Z
+    :param since: (optional), Only issues after this date will
+        be returned. This can be a `datetime` or an `ISO8601` formatted
+        date string, e.g., 2012-05-20T23:10:27Z
+    :type since: datetime or string
     :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
diff --git a/github3/github.py b/github3/github.py
@@ -19,6 +19,7 @@
 from github3.users import User, Key
 from github3.decorators import requires_auth, requires_basic_auth
 from github3.notifications import Thread
+from github3.utils import timestamp_parameter
 
 
 class GitHub(GitHubCore):
@@ -493,7 +494,7 @@ def iter_notifications(self, all=False, participating=False, number=-1,
 
     @requires_auth
     def iter_org_issues(self, name, filter='', state='', labels='', sort='',
-                        direction='', since='', number=-1, etag=None):
+                        direction='', since=None, number=-1, etag=None):
         """Iterate over the organnization's issues if the authenticated user
         belongs to it.
 
@@ -509,21 +510,24 @@ def iter_org_issues(self, name, filter='', state='', labels='', sort='',
             api-default: created
         :param str direction: accepted values: ('asc', 'desc')
             api-default: desc
-        :param str since: ISO 8601 formatted timestamp, e.g.,
-            2012-05-20T23:10:27Z
+        :param since: (optional), Only issues after this date will
+            be returned. This can be a `datetime` or an `ISO8601` formatted
+            date string, e.g., 2012-05-20T23:10:27Z
+        :type since: datetime or string
         :param int number: (optional), number of issues to return. Default:
             -1, returns all available issues
         :param str etag: (optional), ETag from a previous request to the same
             endpoint
         :returns: generator of :class:`Issue <github3.issues.Issue>`
         """
         url = self._build_url('orgs', name, 'issues')
+        # issue_params will handle the since parameter
         params = issue_params(filter, state, labels, sort, direction, since)
         return self._iter(int(number), url, Issue, params, etag)
 
     @requires_auth
     def iter_issues(self, filter='', state='', labels='', sort='',
-                    direction='', since='', number=-1, etag=None):
+                    direction='', since=None, number=-1, etag=None):
         """List all of the authenticated user's (and organization's) issues.
 
         :param str filter: accepted values:
@@ -537,21 +541,24 @@ def iter_issues(self, filter='', state='', labels='', sort='',
             api-default: created
         :param str direction: accepted values: ('asc', 'desc')
             api-default: desc
-        :param str since: ISO 8601 formatted timestamp, e.g.,
-            2012-05-20T23:10:27Z
+        :param since: (optional), Only issues after this date will
+            be returned. This can be a `datetime` or an `ISO8601` formatted
+            date string, e.g., 2012-05-20T23:10:27Z
+        :type since: datetime or string
         :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>`
         """
         url = self._build_url('issues')
+        # issue_params will handle the since parameter
         params = issue_params(filter, state, labels, sort, direction, since)
         return self._iter(int(number), url, Issue, params, etag)
 
     @requires_auth
     def iter_user_issues(self, filter='', state='', labels='', sort='',
-                         direction='', since='', number=-1, etag=None):
+                         direction='', since=None, number=-1, etag=None):
         """List only the authenticated user's issues. Will not list
         organization's issues
 
@@ -566,15 +573,18 @@ def iter_user_issues(self, filter='', state='', labels='', sort='',
             api-default: created
         :param str direction: accepted values: ('asc', 'desc')
             api-default: desc
-        :param str since: ISO 8601 formatted timestamp, e.g.,
-            2012-05-20T23:10:27Z
+        :param since: (optional), Only issues after this date will
+            be returned. This can be a `datetime` or an `ISO8601` formatted
+            date string, e.g., 2012-05-20T23:10:27Z
+        :type since: datetime or string
         :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>`
         """
         url = self._build_url('user', 'issues')
+        # issue_params will handle the since parameter
         params = issue_params(filter, state, labels, sort, direction, since)
         return self._iter(int(number), url, Issue, params, etag)
 
@@ -598,8 +608,10 @@ def iter_repo_issues(self, owner, repository, milestone=None,
             api-default: created
         :param str direction: accepted values: ('asc', 'desc')
             api-default: desc
-        :param str since: ISO 8601 formatted timestamp, e.g.,
-            2012-05-20T23:10:27Z
+        :param since: (optional), Only issues after this date will
+            be returned. This can be a `datetime` or an `ISO8601` formatted
+            date string, e.g., 2012-05-20T23:10:27Z
+        :type since: datetime or string
         :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
diff --git a/github3/issues/__init__.py b/github3/issues/__init__.py
@@ -8,6 +8,7 @@
 """
 
 from re import match
+from github3.utils import timestamp_parameter
 from .issue import Issue
 
 __all__ = [Issue]
@@ -30,7 +31,7 @@ def issue_params(filter, state, labels, sort, direction, since):
     if direction in ('asc', 'desc'):
         params['direction'] = direction
 
-    if since and match('\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$', since):
-        params['since'] = since
+    if since:
+        params['since'] = timestamp_parameter(since)
 
     return params
diff --git a/github3/repos/repo.py b/github3/repos/repo.py
@@ -32,6 +32,7 @@
 from github3.repos.stats import ContributorStats
 from github3.repos.tag import RepoTag
 from github3.users import User, Key
+from github3.utils import timestamp_parameter
 
 
 class Repository(GitHubCore):
@@ -992,16 +993,9 @@ def iter_commits(self, sha=None, path=None, author=None, number=-1,
 
         :returns: generator of :class:`RepoCommit <RepoCommit>`\ s
         """
-        params = {'sha': sha, 'path': path, 'author': author}
-
-        if since is not None:
-            if isinstance(since, datetime):
-                since = since.isoformat()
-            params['since'] = since
-        if until is not None:
-            if isinstance(until, datetime):
-                until = until.isoformat()
-            params['until'] = until
+        params = {'sha': sha, 'path': path, 'author': author,
+                  'since': timestamp_parameter(since),
+                  'until': timestamp_parameter(until)}
 
         self._remove_none(params)
         url = self._build_url('commits', base_url=self._api)
@@ -1127,7 +1121,10 @@ def iter_issues(self,
             'bug,ui,@high' :param sort: accepted values:
             ('created', 'updated', 'comments', 'created')
         :param str direction: (optional), accepted values: ('asc', 'desc')
-        :param str since: (optional), ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
+        :param since: (optional), Only issues after this date will
+            be returned. This can be a `datetime` or an `ISO8601` formatted
+            date string, e.g., 2012-05-20T23:10:27Z
+        :type since: datetime or string
         :param int number: (optional), Number of issues to return.
             By default all issues are returned
         :param str etag: (optional), ETag from a previous request to the same
@@ -1240,24 +1237,24 @@ def iter_network_events(self, number=-1, etag=None):
         return self._iter(int(number), url, Event, etag)
 
     @requires_auth
-    def iter_notifications(self, all=False, participating=False, since='',
+    def iter_notifications(self, all=False, participating=False, since=None,
                            number=-1, etag=None):
         """Iterates over the notifications for this repository.
 
         :param bool all: (optional), show all notifications, including ones
             marked as read
         :param bool participating: (optional), show only the notifications the
             user is participating in directly
-        :param str since: (optional), filters out any notifications updated
-            before the given time. The time should be passed in as UTC in the
-            ISO 8601 format: ``YYYY-MM-DDTHH:MM:SSZ``. Example:
-            "2012-10-09T23:39:01Z".
+        :param since: (optional), filters out any notifications updated
+            before the given time. This can be a `datetime` or an `ISO8601` formatted
+            date string, e.g., 2012-05-20T23:10:27Z
+        :type since: datetime or string
         :param str etag: (optional), ETag from a previous request to the same
             endpoint
         :returns: generator of :class:`Thread <github3.notifications.Thread>`
         """
         url = self._build_url('notifications', base_url=self._api)
-        params = {'all': all, 'participating': participating, 'since': since}
+        params = {'all': all, 'participating': participating, 'since': timestamp_parameter(since)}
         for (k, v) in list(params.items()):
             if not v:
                 del params[k]
diff --git a/github3/utils.py b/github3/utils.py
@@ -0,0 +1,25 @@
+from datetime import datetime
+import re
+
+# with thanks to https://code.google.com/p/jquery-localtime/issues/detail?id=4
+ISO_8601 = re.compile("^(-?(?:[1-9][0-9]*)?[0-9]{4})-(1[0-2]|0[1-9])-(3[0-1]|0[1-9]|[1-2][0-9])"
+                      "T(2[0-3]|[0-1][0-9]):([0-5][0-9]):([0-5][0-9])(\.[0-9]+)?"
+                      "(Z|[+-](?:2[0-3]|[0-1][0-9]):[0-5][0-9])?$")
+
+
+def timestamp_parameter(timestamp, allow_none=True):
+
+    if timestamp is None:
+        if allow_none:
+            return None
+        raise ValueError("Timestamp value cannot be None")
+
+    if isinstance(timestamp, datetime):
+        return timestamp.isoformat()
+
+    if isinstance(timestamp, basestring):
+        if not ISO_8601.match(timestamp):
+            raise ValueError("Invalid timestamp: %s is not a valid ISO-8601 formatted date" % timestamp)
+        return timestamp
+
+    raise ValueError("Cannot accept type %s for timestamp" % type(timestamp))
