Add API for token management

Author: pyhedgehog

docs/examples.rst

@@ -46,3 +46,29 @@ Below is an example demonstrating how to update a user (requires admin privilege
         "username_to_update",
         update)
 
+
+Example 3: Creating a token
+---------------------------
+
+Below is an example illustrating how to create a token for you application::
+
+    import gogs_client
+    from getpass import getpass
+    from platform import node
+
+    api = GogsApi("https://try.gogs.io/")
+
+    try: token_str = open("tokenfile.txt","r").read()
+    except OSError: token_str = None
+    if token_str:
+        token = gogs_client.Token(token_str)
+    else:
+        username = input("username> ")
+        password = getpass("password> ")
+        login = gogs_client.UsernamePassword(username, password)
+        token = api.ensure_token(login, "my cool app on "+node(), username)
+        open("tokenfile.txt", "w".write(token.token))
+
+    username = api.authenticated_user(token)
+    print("User {} authenticated by token {}".format(username, token_str))
+

gogs_client/entities.py

@@ -240,3 +240,46 @@ def pull(self):
             :rtype: bool
             """
             return self._pull
+
+
+class TokenInfo(object):
+    """
+    An immutable representation of a Gogs user token information
+    """
+
+    def __init__(self, name, sha1):
+        self._name = name
+        self._sha1 = sha1
+
+    @staticmethod
+    def from_json(cls, parsed_json):
+        name = json_get(parsed_json, "name")
+        sha1 = json_get(parsed_json, "sha1")
+        return TokenInfo(name, sha1)
+
+    @property
+    def name(self):
+        """
+        The name of the token
+
+        :rtype: str
+        """
+        return self._name
+
+    @property
+    def sha1(self):
+        """
+        The hash of the token
+
+        :rtype: str
+        """
+        return self._sha1
+
+    def as_token(self):
+        """
+        Create Token authenticator for this token
+
+        :rtype: gogs_client.auth.Token
+        """
+        from gogs_client.auth import Token
+        return Token(self.sha1)

gogs_client/interface.py

@@ -1,12 +1,12 @@
 import requests
 
 from gogs_client._implementation.http_utils import RelativeHttpRequestor, append_url
-from gogs_client.entities import GogsUser, GogsRepo
+from gogs_client.entities import GogsUser, GogsRepo, TokenInfo
 
 
 class GogsApi(object):
     """
-    A Gogs client, serving as a wrapper around the Gogs HTTP API.
+    A Gogs API entries, serving as a wrapper around the Gogs HTTP API.
     """
 
     def __init__(self, base_url):
@@ -42,6 +42,68 @@ def authenticated_user(self, auth):
         response = self._get("/user", auth=auth)
         return GogsUser.from_json(self._check_ok(response).json())
 
+    def get_tokens(self, auth, username=None):
+        """
+        Returns tokens defined for specified user.
+        If no user specified uses user authenticated by the given authentication.
+        Right now, authentication must be UsernamePassword (not Token).
+
+        :param auth.Authentication auth: authentication for user to retrieve
+        :param str username: username of owner of tokens
+
+        :return: list of token info representation
+        :rtype: List[TokenInfo]
+        :raises NetworkFailure: if there is an error communicating with the server
+        :raises ApiFailure: if the request cannot be serviced
+        """
+        if username is None:
+            username = self.authenticated_user(auth).username
+        response = self._get("/users/{u}/tokens".format(u=username), auth=auth)
+        return [TokenInfo.from_json(o) for o in self._check_ok(response).json()]
+
+    def create_token(self, auth, name, username=None):
+        """
+        Creates new token with specified name for specified user.
+        If no user specified uses user authenticated by the given authentication.
+        Right now, authentication must be UsernamePassword (not Token).
+
+        :param auth.Authentication auth: authentication for user to retrieve
+        :param str name: name of new token
+        :param str username: username of owner of new token
+
+        :return: representation of token info
+        :rtype: TokenInfo
+        :raises NetworkFailure: if there is an error communicating with the server
+        :raises ApiFailure: if the request cannot be serviced
+        """
+        if username is None:
+            username = self.authenticated_user(auth).username
+        data = {"name": name}
+        response = self._post("/users/{u}/tokens".format(u=username), auth=auth, data=data)
+        return TokenInfo.from_json(self._check_ok(response).json())
+
+    def ensure_token(self, auth, name, username=None):
+        """
+        Creates new token if token with specified name for specified user does not exists.
+        If no user specified uses user authenticated by the given authentication.
+        Right now, authentication must be UsernamePassword (not Token).
+
+        :param auth.Authentication auth: authentication for user to retrieve
+        :param str name: name of new token
+        :param str username: username of owner of new token
+
+        :return: token authenticator
+        :rtype: Token
+        :raises NetworkFailure: if there is an error communicating with the server
+        :raises ApiFailure: if the request cannot be serviced
+        """
+        if username is None:
+            username = self.authenticated_user(auth).username
+        tokens = [token for token in self.get_tokens(auth, username) if token.name == name]
+        if tokens:
+            return tokens[0].as_token()
+        return self.create_token(auth, name, username).as_token()
+
     def create_repo(self, auth, name, description=None, private=False, auto_init=False,
                     gitignore_templates=None, license_template=None, readme_template=None):
         """