Add github3.search_users

sigmavirus24 · sigmavirus24 · commit 214c552a03b0 · 2013-12-29T11:18:44.000-06:00
- Also added links for text matching for user search
diff --git a/github3/api.py b/github3/api.py
@@ -463,6 +463,58 @@ def search_repositories(query, sort=None, order=None, per_page=None,
                                   number, etag)
 
 
+def search_users(query, sort=None, order=None, per_page=None,
+                 text_match=False, number=-1, etag=None):
+    """Find users via the Search API.
+
+    .. warning::
+
+        You will only be able to make 5 calls with this or other search
+        functions. To raise the rate-limit on this set of endpoints, create an
+        authenticated :class:`GitHub <github3.github.GitHub>` Session with
+        ``login``.
+
+    The query can contain any combination of the following supported
+    qualifers:
+
+
+    - ``type`` With this qualifier you can restrict the search to just
+      personal accounts or just organization accounts.
+    - ``in`` Qualifies which fields are searched. With this qualifier you
+      can restrict the search to just the username, public email, full
+      name, or any combination of these.
+    - ``repos`` Filters users based on the number of repositories they
+      have.
+    - ``location`` Filter users by the location indicated in their
+      profile.
+    - ``language`` Search for users that have repositories that match a
+      certain language.
+    - ``created`` Filter users based on when they joined.
+    - ``followers`` Filter users based on the number of followers they
+      have.
+
+    For more information about these qualifiers see: http://git.io/wjVYJw
+
+    :param str query: (required), a valid query as described above, e.g.,
+        ``tom repos:>42 followers:>1000``
+    :param str sort: (optional), how the results should be sorted;
+        options: ``followers``, ``repositories``, or ``joined``; default:
+        best match
+    :param str order: (optional), the direction of the sorted results,
+        options: ``asc``, ``desc``; default: ``desc``
+    :param int per_page: (optional)
+    :param bool text_match: (optional), if True, return matching search
+        terms. See http://git.io/_V1zRwa for more information
+    :param int number: (optional), number of search results to return;
+        Default: -1 returns all available
+    :param str etag: (optional), ETag header value of the last request.
+    :return: generator of :class:`UserSearchResult
+        <github3.search.UserSearchResult>`
+    """
+    return gh.search_users(query, sort, order, per_page, text_match, number,
+                           etag)
+
+
 def user(login):
     return gh.user(login)
 user.__doc__ = gh.user.__doc__
diff --git a/github3/github.py b/github3/github.py
@@ -1137,7 +1137,7 @@ def search_users(self, query, sort=None, order=None, per_page=None,
             options: ``asc``, ``desc``; default: ``desc``
         :param int per_page: (optional)
         :param bool text_match: (optional), if True, return matching search
-            terms.
+            terms. See http://git.io/_V1zRwa for more information
         :param int number: (optional), number of search results to return;
             Default: -1 returns all available
         :param str etag: (optional), ETag header value of the last request.
