Manage optional parameters for list() and get()

* List these elements in the API doc
* Implement for License objects

4 files changed, 47 insertions, 12 deletions

diff --git a/docs/ext/docstrings.py b/docs/ext/docstrings.py
index 4724fc5..4520e43 100644
--- a/docs/ext/docstrings.py
+++ b/docs/ext/docstrings.py
@@ -30,17 +30,26 @@ def _process_docstring(app, what, name, obj, options, lines):
 class GitlabDocstring(GoogleDocstring):
     def _build_doc(self):
         cls = self._obj.obj_cls
+        opt_get_list = cls.optionalGetAttrs
+        opt_list_list = cls.optionalListAttrs
         md_create_list = list(itertools.chain(cls.requiredUrlAttrs,
                                               cls.requiredCreateAttrs))
         opt_create_list = cls.optionalCreateAttrs
 
+        opt_get_keys = "None"
+        if opt_get_list:
+            opt_get_keys = ", ".join(['``%s``' % i for i in opt_get_list])
+
+        opt_list_keys = "None"
+        if opt_list_list:
+            opt_list_keys = ", ".join(['``%s``' % i for i in opt_list_list])
+
         md_create_keys = opt_create_keys = "None"
         if md_create_list:
-            md_create_keys = "%s" % ", ".join(['``%s``' % i for i in
-                                               md_create_list])
+            md_create_keys = ", ".join(['``%s``' % i for i in md_create_list])
         if opt_create_list:
-            opt_create_keys = "%s" % ", ".join(['``%s``' % i for i in
-                                                opt_create_list])
+            opt_create_keys = ", ".join(['``%s``' % i for i in
+                                         opt_create_list])
 
         md_update_list = list(itertools.chain(cls.requiredUrlAttrs,
                                               cls.requiredUpdateAttrs))
@@ -48,11 +57,10 @@ class GitlabDocstring(GoogleDocstring):
 
         md_update_keys = opt_update_keys = "None"
         if md_update_list:
-            md_update_keys = "%s" % ", ".join(['``%s``' % i for i in
-                                               md_update_list])
+            md_update_keys = ", ".join(['``%s``' % i for i in md_update_list])
         if opt_update_list:
-            opt_update_keys = "%s" % ", ".join(['``%s``' % i for i in
-                                                opt_update_list])
+            opt_update_keys = ", ".join(['``%s``' % i for i in
+                                         opt_update_list])
 
         tmpl_file = os.path.join(os.path.dirname(__file__), 'template.j2')
         with open(tmpl_file) as fd:
@@ -62,7 +70,9 @@ class GitlabDocstring(GoogleDocstring):
                                      md_create_keys=md_create_keys,
                                      opt_create_keys=opt_create_keys,
                                      md_update_keys=md_update_keys,
-                                     opt_update_keys=opt_update_keys)
+                                     opt_update_keys=opt_update_keys,
+                                     opt_get_keys=opt_get_keys,
+                                     opt_list_keys=opt_list_keys)
 
         return output.split('\n')
 
diff --git a/docs/ext/template.j2 b/docs/ext/template.j2
index 980a7ed..29f4a00 100644
--- a/docs/ext/template.j2
+++ b/docs/ext/template.j2
@@ -19,3 +19,11 @@ Mandatory arguments for object update: {{ md_create_keys }}
 
 Optional arguments for object update: {{ opt_create_keys }}
 {% endif %}
+
+{% if cls.canList %}
+Optional arguments for object listing: {{ opt_list_keys }}
+{% endif %}
+
+{% if cls.canGet %}
+Optional arguments for object listing: {{ opt_get_keys }}
+{% endif %}
diff --git a/gitlab/cli.py b/gitlab/cli.py
index 02dac8e..c7daceb 100644
--- a/gitlab/cli.py
+++ b/gitlab/cli.py
@@ -313,7 +313,7 @@ def _populate_sub_parser_by_class(cls, sub_parser):
             sub_parser_action.add_argument("--page", required=False)
             sub_parser_action.add_argument("--per-page", required=False)
 
-        elif action_name in ["get", "delete"]:
+        if action_name in ["get", "delete"]:
             if cls not in [gitlab.CurrentUser]:
                 if cls.getRequiresId:
                     id_attr = cls.idAttr.replace('_', '-')
@@ -323,7 +323,17 @@ def _populate_sub_parser_by_class(cls, sub_parser):
                                                 required=True)
                  for x in cls.requiredGetAttrs if x != cls.idAttr]
 
-        elif action_name == "create":
+        if action_name == "get":
+            [sub_parser_action.add_argument("--%s" % x.replace('_', '-'),
+                                            required=False)
+             for x in cls.optionalGetAttrs]
+
+        if action_name == "list":
+            [sub_parser_action.add_argument("--%s" % x.replace('_', '-'),
+                                            required=False)
+             for x in cls.optionalListAttrs]
+
+        if action_name == "create":
             [sub_parser_action.add_argument("--%s" % x.replace('_', '-'),
                                             required=True)
              for x in cls.requiredCreateAttrs]
@@ -331,7 +341,7 @@ def _populate_sub_parser_by_class(cls, sub_parser):
                                             required=False)
              for x in cls.optionalCreateAttrs]
 
-        elif action_name == "update":
+        if action_name == "update":
             id_attr = cls.idAttr.replace('_', '-')
             sub_parser_action.add_argument("--%s" % id_attr,
                                            required=True)
diff --git a/gitlab/objects.py b/gitlab/objects.py
index ebfba8b..9c6197c 100644
--- a/gitlab/objects.py
+++ b/gitlab/objects.py
@@ -183,6 +183,10 @@ class GitlabObject(object):
     requiredUrlAttrs = []
     #: Attributes that are required when retrieving list of objects.
     requiredListAttrs = []
+    #: Attributes that are optional when retrieving list of objects.
+    optionalListAttrs = []
+    #: Attributes that are optional when retrieving single object.
+    optionalGetAttrs = []
     #: Attributes that are required when retrieving single object.
     requiredGetAttrs = []
     #: Attributes that are required when deleting object.
@@ -754,6 +758,9 @@ class License(GitlabObject):
     canCreate = False
     idAttr = 'key'
 
+    optionalListAttrs = ['popular']
+    optionalGetAttrs = ['project', 'fullname']
+
 
 class LicenseManager(BaseManager):
     obj_cls = License