feat: add support for group and project invitations API

1 files changed, 73 insertions, 0 deletions

diff --git a/docs/gl_objects/invitations.rst b/docs/gl_objects/invitations.rst
new file mode 100644
index 0000000..625d58f
--- /dev/null
+++ b/docs/gl_objects/invitations.rst
@@ -0,0 +1,73 @@
+###########
+Invitations
+###########
+
+Invitations let you invite or add users to a group or project.
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.GroupInvitation`
+  + :class:`gitlab.v4.objects.GroupInvitationManager`
+  + :attr:`gitlab.v4.objects.Group.invitations`
+  + :class:`gitlab.v4.objects.ProjectInvitation`
+  + :class:`gitlab.v4.objects.ProjectInvitationManager`
+  + :attr:`gitlab.v4.objects.Project.invitations`
+
+* GitLab API: https://docs.gitlab.com/ce/api/invitations.html
+
+Examples
+--------
+
+.. danger::
+
+    Creating an invitation with ``create()`` returns a status response,
+    rather than invitation details, because it allows sending multiple
+    invitations at the same time.
+    
+    Thus when using several emails, you do not create a real invitation
+    object you can manipulate, because python-gitlab cannot know which email
+    to track as the ID.
+    
+    In that case, use a **lazy** ``get()`` method shown below using a specific
+    email address to create an invitation object you can manipulate.
+
+Create an invitation::
+
+    invitation = group_or_project.invitations.create(
+        {
+            "email": "email@example.com",
+            "access_level": gitlab.const.AccessLevel.DEVELOPER,
+        }
+    )
+
+List invitations for a group or project::
+
+    invitations = group_or_project.invitations.list()
+
+.. warning::
+
+    As mentioned above, GitLab does not provide a real GET endpoint for a single
+    invitation. We can create a lazy object to later manipulate it.
+
+Update an invitation::
+
+    invitation = group_or_project.invitations.get("email@example.com", lazy=True)
+    invitation.access_level = gitlab.const.AccessLevel.DEVELOPER
+    invitation.save()
+
+    # or
+    group_or_project.invitations.update(
+        "email@example.com",
+        {"access_level": gitlab.const.AccessLevel.DEVELOPER}
+    )
+
+Delete an invitation::
+
+    invitation = group_or_project.invitations.get("email@example.com", lazy=True)
+    invitation.delete()
+
+    # or
+    group_or_project.invitations.delete("email@example.com")