Webhook entity representation.

Author: Costin Bleotu

docs/entities.rst

@@ -17,3 +17,6 @@ This pages documents classes provided by ``gogs_client`` module that represent e
 
 .. autoclass:: gogs_client.entities::GogsRepo.Permissions()
     :members:
+
+.. autoclass:: gogs_client.entities::GogsRepo.Hook()
+    :members:

docs/updates.rst

@@ -8,3 +8,9 @@ Updates
 
 .. autoclass:: gogs_client.updates::GogsUserUpdate.Builder()
     :members:
+
+.. autoclass:: GogsHookUpdate()
+    :members:
+
+.. autoclass:: gogs_client.updates::GogsHookUpdate.Builder()
+    :members:

gogs_client/entities.py

@@ -240,3 +240,70 @@ def pull(self):
             :rtype: bool
             """
             return self._pull
+
+    class Hook(object):
+        def __init__(self, hook_id, hook_type, events, active, config):
+            self._id = hook_id
+            self._type = hook_type
+            self._events = events
+            self._active = active
+            self._config = config
+
+        @staticmethod
+        def from_json(parsed_json):
+            hook_id = json_get(parsed_json, "id")
+            hook_type = json_get(parsed_json, "type")
+            events = json_get(parsed_json, "events")
+            active = json_get(parsed_json, "active")
+            config = json_get(parsed_json, "config")
+
+            return GogsRepo.Hook(hook_id=hook_id, hook_type=hook_type, events=events, active=active, 
+                            config=config)
+
+        @property  # named hook_id to avoid conflict with built-in id
+        def hook_id(self):
+            """
+            The hook's id number
+
+            :rtype: int
+            """
+            return self._id
+
+        @property  # named hook_type to avoid conflict with built-in type
+        def hook_type(self):
+            """
+            The hook's type (gogs, slack, etc.)
+
+            :rtype: str
+            """
+            return self._type
+
+        @property
+        def events(self):
+            """
+            The events that fires the hook
+
+            :rtype: list of strs
+            """
+            return self._events
+
+        @property
+        def active(self):
+            """
+            State of the hook
+
+            :rtype: bool
+            """
+            return self._active
+
+        @property
+        def config(self):
+            """
+            Config of the hook. Contains max. 3 keys:
+                - content_type
+                - url
+                - secret
+
+            :rtype: dict
+            """
+            return self._config

gogs_client/interface.py

@@ -290,6 +290,69 @@ def delete_user(self, auth, username):
         path = "/admin/users/{}".format(username)
         self._check_ok(self._delete(path, auth=auth))
 
+    def get_repo_hooks(self, auth, username, repo_name):
+        """
+        Returns all hooks of repository with name ``repo_name`` owned by
+        the user with username ``username``.
+
+        :param auth.Authentication auth: authentication object
+        :param str username: username of owner of repository
+        :param str repo_name: name of repository
+        :return: a list of hooks for the specified repository
+        :rtype: List[GogsRepo.Hooks]
+        :raises NetworkFailure: if there is an error communicating with the server
+        :raises ApiFailure: if the request cannot be serviced
+        """
+        path = "/repos/{u}/{r}/hooks".format(u=username, r=repo_name)
+        response = self._check_ok(self._get(path, auth=auth))
+        hooks = [GogsRepo.Hook.from_json(hook) for hook in response.json()]
+        return hooks
+
+    def create_hook(self, auth, repo_name, hook_type, config, events=["push"], organization=None, active=False):
+        """
+        Creates a new hook, and returns the created hook.
+
+        :param auth.Authentication auth: authentication object, must be admin-level
+        :param str repo_name: the name of the repo for which we create the hook
+        :param str hook_type: The type of webhook, either "gogs" or "slack"
+        :param dict config: Key/value pairs to provide settings for this hook ("url", "content_type", "secret")
+        :param list events: Determines what events the hook is triggered for. Default: ["push"]
+        :param str organization: (Optional) Organization of the repo
+        :param bool active: Determines whether the hook is actually triggered on pushes. Default is false
+        :return: a representation of the created hook
+        :rtype: GogsRepo.Hook
+        :raises NetworkFailure: if there is an error communicating with the server
+        :raises ApiFailure: if the request cannot be serviced
+        """
+
+        data = {
+            "type": hook_type,
+            "config": config,
+            "events": events,
+            "active": active
+        }
+
+        url = "/repos/{o}/{r}/hooks".format(o=organization, r=repo_name) if organization else "/repos/{r}/hooks".format(r=repo_name)
+        response = self._post(url, auth=auth, data=data)
+        print response.text
+        self._check_ok(response)
+        return GogsRepo.Hook.from_json(response.json())
+
+    def delete_hook(self, auth, username, repo_name, hook_id):
+        """
+        Deletes the hook with id ``hook_id`` for repo with name ``repo_name``
+        owned by the user with username ``username``.
+
+        :param auth.Authentication auth: authentication object
+        :param str username: username of owner of repository
+        :param str repo_name: name of repository of hook to delete
+        :param int hook_id: id of hook to delete
+        :raises NetworkFailure: if there is an error communicating with the server
+        :raises ApiFailure: if the request cannot be serviced
+        """
+        path = "/repos/{u}/{r}/hooks/{i}".format(u=username, r=repo_name, i=hook_id)
+        self._check_ok(self._delete(path, auth=auth))
+
     # Helper methods
 
     def _delete(self, path, auth=None, **kwargs):

gogs_client/updates.py

@@ -182,3 +182,82 @@ def build(self):
                 admin=self._admin,
                 allow_git_hook=self._allow_git_hook,
                 allow_import_local=self._allow_import_local)
+
+
+class GogsHookUpdate(object):
+    """
+    An immutable represention of a collection of Gogs hook attributes to update.
+
+    Instances should be created using the :class:`~GogsHookUpdate.Builder` class.
+    """
+    def __init__(self, hook_type, events, config, active):
+        """
+        :param hook_type:
+        :param events:
+        :param config:
+        :param active:
+        """
+
+        self._type = hook_type
+        self._events = events
+        self._config = config
+        self._active = active
+
+    def as_dict(self):
+        fields = {
+            "type": self._type,
+            "events": self._events,
+            "config": self._config,
+            "active": self._active,
+        }
+        return {k: v for (k, v) in fields.items() if v is not None}
+
+    class Builder(object):
+        def __init__(self):
+            """
+            :param str login_name: login name for authentication source
+            :param str email: email address of user to update
+            """
+            self._type = None
+            self._events = None
+            self._config = None
+            self._active = None
+
+
+        def set_events(self, events):
+            """
+            :param list events:
+            :return: the updated builder
+            :rtype: GogsHookUpdate.Builder
+            """
+            self._events = events
+            return self
+
+        def set_config(self, config):
+            """
+            :param dict config:
+            :return: the updated builder
+            :rtype: GogsHookUpdate.Builder
+            """
+            self._config = config
+            return self
+
+        def set_active(self, active):
+            """
+            :param bool active:
+            :return: the updated builder
+            :rtype: GogsHookUpdate.Builder
+            """
+            self._active = active
+            return self
+
+        def build(self):
+            """
+            :return: A :class:`~GogsHookUpdate` instance reflecting the changes added to the builder.
+            :rtype: GogsHookUpdate
+            """
+            return GogsHookUpdate(
+                hook_type=self._type,
+                events=self._events,
+                config=self._config,
+                active=self._active)