diff --git a/docs/gl_objects/badges.rst b/docs/gl_objects/badges.rst index 1bda282dd..2a26bb3fe 100644 --- a/docs/gl_objects/badges.rst +++ b/docs/gl_objects/badges.rst @@ -28,7 +28,7 @@ List badges:: badges = group_or_project.badges.list() -Get ad badge:: +Get a badge:: badge = group_or_project.badges.get(badge_id) diff --git a/docs/gl_objects/search.rst b/docs/gl_objects/search.rst index 750bbe0f1..eb8ba80b0 100644 --- a/docs/gl_objects/search.rst +++ b/docs/gl_objects/search.rst @@ -4,7 +4,30 @@ Search API You can search for resources at the top level, in a project or in a group. Searches are based on a scope (issues, merge requests, and so on) and a search -string. +string. The following constants are provided to represent the possible scopes: + + +* Shared scopes (global, group and project): + + + ``gitlab.SEARCH_SCOPE_PROJECTS``: ``projects`` + + ``gitlab.SEARCH_SCOPE_ISSUES``: ``issues`` + + ``gitlab.SEARCH_SCOPE_MERGE_REQUESTS``: ``merge_requests`` + + ``gitlab.SEARCH_SCOPE_MILESTONES``: ``milestones`` + + ``gitlab.SEARCH_SCOPE_WIKI_BLOBS``: ``wiki_blobs`` + + ``gitlab.SEARCH_SCOPE_COMMITS``: ``commits`` + + ``gitlab.SEARCH_SCOPE_BLOBS``: ``blobs`` + + ``gitlab.SEARCH_SCOPE_USERS``: ``users`` + + +* specific global scope: + + + ``gitlab.SEARCH_SCOPE_GLOBAL_SNIPPET_TITLES``: ``snippet_titles`` + + +* specific project scope: + + + ``gitlab.SEARCH_SCOPE_PROJECT_NOTES``: ``notes`` + Reference --------- @@ -23,31 +46,32 @@ Examples Search for issues matching a specific string:: # global search - gl.search('issues', 'regression') + gl.search(gitlab.SEARCH_SCOPE_ISSUES, 'regression') # group search group = gl.groups.get('mygroup') - group.search('issues', 'regression') + group.search(gitlab.SEARCH_SCOPE_ISSUES, 'regression') # project search project = gl.projects.get('myproject') - project.search('issues', 'regression') + project.search(gitlab.SEARCH_SCOPE_ISSUES, 'regression') The ``search()`` methods implement the pagination support:: # get lists of 10 items, and start at page 2 - gl.search('issues', search_str, page=2, per_page=10) + gl.search(gitlab.SEARCH_SCOPE_ISSUES, search_str, page=2, per_page=10) # get a generator that will automatically make required API calls for # pagination - for item in gl.search('issues', search_str, as_list=False): + for item in gl.search(gitlab.SEARCH_SCOPE_ISSUES, search_str, as_list=False): do_something(item) The search API doesn't return objects, but dicts. If you need to act on objects, you need to create them explicitly:: - for item in gl.search('issues', search_str, as_list=False): + for item in gl.search(gitlab.SEARCH_SCOPE_ISSUES, search_str, as_list=False): issue_project = gl.projects.get(item['project_id'], lazy=True) issue = issue_project.issues.get(item['iid']) issue.state = 'closed' issue.save() + diff --git a/gitlab/const.py b/gitlab/const.py index 7791a39b3..0d2f421e8 100644 --- a/gitlab/const.py +++ b/gitlab/const.py @@ -33,3 +33,20 @@ NOTIFICATION_LEVEL_GLOBAL = "global" NOTIFICATION_LEVEL_MENTION = "mention" NOTIFICATION_LEVEL_CUSTOM = "custom" + +# Search scopes +# all scopes (global, group and project) +SEARCH_SCOPE_PROJECTS = "projects" +SEARCH_SCOPE_ISSUES = "issues" +SEARCH_SCOPE_MERGE_REQUESTS = "merge_requests" +SEARCH_SCOPE_MILESTONES = "milestones" +SEARCH_SCOPE_WIKI_BLOBS = "wiki_blobs" +SEARCH_SCOPE_COMMITS = "commits" +SEARCH_SCOPE_BLOBS = "blobs" +SEARCH_SCOPE_USERS = "users" + +# specific global scope +SEARCH_SCOPE_GLOBAL_SNIPPET_TITLES = "snippet_titles" + +# specific project scope +SEARCH_SCOPE_PROJECT_NOTES = "notes"