Add Gitlab and User events support

Gauvain Pocentek · Gauvain Pocentek · commit 1ca30807566c · 2018-01-21T18:30:38.000+01:00
Closes python-gitlab#412
diff --git a/docs/api-objects.rst b/docs/api-objects.rst
@@ -15,6 +15,7 @@ API examples
    gl_objects/deploy_keys
    gl_objects/deployments
    gl_objects/environments
+   gl_objects/events
    gl_objects/features
    gl_objects/groups
    gl_objects/issues
diff --git a/docs/gl_objects/events.rst b/docs/gl_objects/events.rst
@@ -0,0 +1,48 @@
+######
+Events
+######
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.Event`
+  + :class:`gitlab.v4.objects.EventManager`
+  + :attr:`gitlab.Gitlab.events`
+  + :class:`gitlab.v4.objects.ProjectEvent`
+  + :class:`gitlab.v4.objects.ProjectEventManager`
+  + :attr:`gitlab.v4.objects.Project.events`
+  + :class:`gitlab.v4.objects.UserEvent`
+  + :class:`gitlab.v4.objects.UserEventManager`
+  + :attr:`gitlab.v4.objects.User.events`
+
+* v3 API (projects events only):
+
+  + :class:`gitlab.v3.objects.ProjectEvent`
+  + :class:`gitlab.v3.objects.ProjectEventManager`
+  + :attr:`gitlab.v3.objects.Project.events`
+  + :attr:`gitlab.Gitlab.project_events`
+
+* GitLab API: https://docs.gitlab.com/ce/api/events.html
+
+Examples
+--------
+
+You can list events for an entire Gitlab instance (admin), users and projects.
+You can filter you events you want to retrieve using the ``action`` and
+``target_type`` attributes. The possibole values for these attributes are
+available on `the gitlab documentation
+<https://docs.gitlab.com/ce/api/events.html>`_.
+
+List all the events (paginated)::
+
+    events = gl.events.list()
+
+List the issue events on a project::
+
+    events = project.events.list(target_type='issue')
+
+List the user events::
+
+    events = project.events.list()
diff --git a/docs/gl_objects/projects.py b/docs/gl_objects/projects.py
@@ -69,12 +69,6 @@
 project.unarchive()
 # end archive
 
-# events list
-gl.project_events.list(project_id=1)
-# or
-project.events.list()
-# end events list
-
 # members list
 members = project.members.list()
 # end members list
diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst
@@ -484,36 +484,6 @@ Delete a note for a resource:
    :start-after: # notes delete
    :end-before: # end notes delete
 
-Project events
-==============
-
-Reference
----------
-
-* v4 API:
-
-  + :class:`gitlab.v4.objects.ProjectEvent`
-  + :class:`gitlab.v4.objects.ProjectEventManager`
-  + :attr:`gitlab.v4.objects.Project.events`
-
-* v3 API:
-
-  + :class:`gitlab.v3.objects.ProjectEvent`
-  + :class:`gitlab.v3.objects.ProjectEventManager`
-  + :attr:`gitlab.v3.objects.Project.events`
-  + :attr:`gitlab.Gitlab.project_events`
-
-* GitLab API: https://docs.gitlab.com/ce/api/repository_files.html
-
-Examples
---------
-
-List the project events:
-
-.. literalinclude:: projects.py
-   :start-after: # events list
-   :end-before: # end events list
-
 Project members
 ===============
 
diff --git a/gitlab/__init__.py b/gitlab/__init__.py
@@ -125,6 +125,7 @@ def __init__(self, url, private_token=None, oauth_token=None, email=None,
             self.teams = objects.TeamManager(self)
         else:
             self.dockerfiles = objects.DockerfileManager(self)
+            self.events = objects.EventManager(self)
             self.features = objects.FeatureManager(self)
             self.pagesdomains = objects.PagesDomainManager(self)
             self.user_activities = objects.UserActivitiesManager(self)
diff --git a/gitlab/v4/objects.py b/gitlab/v4/objects.py
@@ -112,6 +112,17 @@ def compound_metrics(self, **kwargs):
         return self.gitlab.http_get('/sidekiq/compound_metrics', **kwargs)
 
 
+class Event(RESTObject):
+    _id_attr = None
+    _short_print_attr = 'target_title'
+
+
+class EventManager(ListMixin, RESTManager):
+    _path = '/events'
+    _obj_cls = Event
+    _list_filters = ('action', 'target_type', 'before', 'after', 'sort')
+
+
 class UserActivities(RESTObject):
     _id_attr = 'username'
 
@@ -143,6 +154,16 @@ class UserEmailManager(RetrieveMixin, CreateMixin, DeleteMixin, RESTManager):
     _create_attrs = (('email', ), tuple())
 
 
+class UserEvent(Event):
+    pass
+
+
+class UserEventManager(EventManager):
+    _path = '/users/%(user_id)s/events'
+    _obj_cls = UserEvent
+    _from_parent_attrs = {'user_id': 'id'}
+
+
 class UserGPGKey(ObjectDeleteMixin, RESTObject):
     pass
 
@@ -224,6 +245,7 @@ class User(SaveMixin, ObjectDeleteMixin, RESTObject):
     _managers = (
         ('customattributes', 'UserCustomAttributeManager'),
         ('emails', 'UserEmailManager'),
+        ('events', 'UserEventManager'),
         ('gpgkeys', 'UserGPGKeyManager'),
         ('impersonationtokens', 'UserImpersonationTokenManager'),
         ('keys', 'UserKeyManager'),
@@ -1161,12 +1183,11 @@ def enable(self, key_id, **kwargs):
         self.gitlab.http_post(path, **kwargs)
 
 
-class ProjectEvent(RESTObject):
-    _id_attr = None
-    _short_print_attr = 'target_title'
+class ProjectEvent(Event):
+    pass
 
 
-class ProjectEventManager(ListMixin, RESTManager):
+class ProjectEventManager(EventManager):
     _path = '/projects/%(project_id)s/events'
     _obj_cls = ProjectEvent
     _from_parent_attrs = {'project_id': 'id'}
diff --git a/tools/python_test_v4.py b/tools/python_test_v4.py
@@ -95,6 +95,9 @@
 # user projects list
 assert(len(new_user.projects.list()) == 0)
 
+# events list
+new_user.events.list()
+
 foobar_user = gl.users.create(
     {'email': 'foobar@example.com', 'username': 'foobar',
      'name': 'Foo Bar', 'password': 'foobar_password'})
@@ -408,7 +411,7 @@
 env.delete()
 assert(len(admin_project.environments.list()) == 0)
 
-# events
+# project events
 admin_project.events.list()
 
 # forks
@@ -640,3 +643,6 @@
 
 # user activities
 gl.user_activities.list()
+
+# events
+gl.events.list()
