Polish docs and add tests into package

Author: gonchik

.github/bump_version

@@ -2,7 +2,7 @@
 
 if [[ ( -z ${1+x} ) || ( -z ${2+x} ) ]]; then
     cat << EOF
-        usage: $(basename ${0}) repo increment
+        usage: $(basename "${0}") repo increment
 
         Quick and dirty version bump script
         If a variable "BUILD_VERSION" is set, returns that variable as is
@@ -30,7 +30,7 @@ function autoversion(){
         BUILD_NUMBER="0"  # In the developer machine, this will build x.y.z.dev0
     fi
 
-    cd ${REPO_PATH} || exit 1
+    cd "${REPO_PATH}" || exit 1
 
     git fetch --tags 2>/dev/null
     last_tag=$(git tag | sort -Vr | head -1)

atlassian/VERSION

@@ -1 +1 @@
-3.40.0
+3.40.1

atlassian/bamboo.py

@@ -127,8 +127,8 @@ def project(self, project_key, expand=None, favourite=False, clover_enabled=Fals
 
     def project_plans(self, project_key, start_index=0, max_results=25):
         """
-        Returns a generator with the plans in a given project
-        :param project_key: Project key
+        Returns a generator with the plans in a given project.
+        :param project_key: project key
         :param start_index:
         :param max_results:
         :return: Generator with plans
@@ -295,7 +295,7 @@ def create_branch(
         :param branch_name: str new-shiny-branch
         :param vcs_branch: str feature/new-shiny-branch, /refs/heads/new-shiny-branch
         :param enabled: bool
-        :param cleanup_enabled: bool
+        :param cleanup_enabled: bool - enable/disable automatic cleanup of branch
         :return: PUT request
         """
         resource = "plan/{plan_key}/branch/{branch_name}".format(plan_key=plan_key, branch_name=branch_name)
@@ -398,7 +398,7 @@ def latest_results(
         include_all_states=False,
     ):
         """
-        Get latest Results
+        Get the latest Results
         :param expand:
         :param favourite:
         :param clover_enabled:
@@ -433,7 +433,7 @@ def project_latest_results(
         include_all_states=False,
     ):
         """
-        Get latest Project Results
+        Get the latest Project Results
         :param project_key:
         :param expand:
         :param favourite:
@@ -533,7 +533,7 @@ def build_result(
 
     def build_latest_result(self, plan_key, expand=None, include_all_states=False):
         """
-        Returns details of a latest build result
+        Returns details of the latest build result
         :param expand: expands build result details on request. Possible values are: artifacts, comments, labels,
         Jira Issues, stages. stages expand is available only for top level plans. It allows to drill down to job results
         using stages.stage.results.result. All expand parameters should contain results. Result prefix.

atlassian/bitbucket/base.py

@@ -50,7 +50,7 @@ def _get_paged(
         Used to get the paged data
 
         :param url: string:                        The url to retrieve
-        :param params: dict (default is None):     The parameters
+        :param params: dict (default is None):     The parameter's
         :param data: dict (default is None):       The data
         :param flags: string[] (default is None):  The flags
         :param trailing: bool (default is None):   If True, a trailing slash is added to the url

atlassian/bitbucket/cloud/base.py

@@ -51,7 +51,7 @@ def _get_paged(
         Used to get the paged data
 
         :param url: string:                        The url to retrieve
-        :param params: dict (default is None):     The parameters
+        :param params: dict (default is None):     The parameter's
         :param data: dict (default is None):       The data
         :param flags: string[] (default is None):  The flags
         :param trailing: bool (default is None):   If True, a trailing slash is added to the url

atlassian/bitbucket/cloud/repositories/commits.py

@@ -144,7 +144,7 @@ def get_build(self, key):
 
     def comments(self):
         """
-        Return generator object of the comments endpoint.
+        Return generator object endpoint of the comment.
         API docs: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-commits/#api-repositories-workspace-repo-slug-commit-commit-comments-get
         """
         for comment in self._get_paged("comments"):

atlassian/bitbucket/cloud/repositories/defaultReviewers.py

@@ -19,7 +19,7 @@ def __get_object(self, data):
 
     def add(self, user):
         """
-        Adds the specified user to the repository"s list of default reviewers.
+        Adds the specified user to the repository's list of default reviewers.
 
         This method is idempotent. Adding a user a second time has no effect.
 
@@ -34,7 +34,7 @@ def add(self, user):
 
     def each(self, q=None, sort=None):
         """
-        Returns the repository"s default reviewers.
+        Returns the repository's default reviewers.
         These are the users that are automatically added as reviewers on every new pull request
         that is created.
 

atlassian/bitbucket/server/base.py

@@ -30,7 +30,7 @@ def _get_paged(
         Used to get the paged data
 
         :param url: string:                        The url to retrieve
-        :param params: dict (default is None):     The parameters
+        :param params: dict (default is None):     The parameter's
         :param data: dict (default is None):       The data
         :param flags: string[] (default is None):  The flags
         :param trailing: bool (default is None):   If True, a trailing slash is added to the url

atlassian/confluence.py

@@ -59,7 +59,7 @@ def _get_paged(
         Used to get the paged data
 
         :param url: string:                        The url to retrieve
-        :param params: dict (default is None):     The parameters
+        :param params: dict (default is None):     The parameter's
         :param data: dict (default is None):       The data
         :param flags: string[] (default is None):  The flags
         :param trailing: bool (default is None):   If True, a trailing slash is added to the url
@@ -210,7 +210,7 @@ def get_child_pages(self, page_id):
 
     def get_page_id(self, space, title, type="page"):
         """
-        Provide content id from search result by title and space
+        Provide content id from search result by title and space.
         :param space: SPACE key
         :param title: title
         :param type: type of content: Page or Blogpost. Defaults to page
@@ -250,7 +250,7 @@ def get_parent_content_title(self, page_id):
 
     def get_page_space(self, page_id):
         """
-        Provide space key from content id
+        Provide space key from content id.
         :param page_id: content ID
         :return:
         """
@@ -1138,8 +1138,8 @@ def attach_content(
         comment=None,
     ):
         """
-        Attach (upload) a file to a page, if it exists it will update the
-        automatically version the new file and keep the old one.
+        Attach (upload) a file to a page, if it exists it will update automatically the
+        version the new file and keep the old one.
         :param title: The page name
         :type  title: ``str``
         :param space: The space name
@@ -1218,8 +1218,8 @@ def attach_file(
         comment=None,
     ):
         """
-        Attach (upload) a file to a page, if it exists it will update the
-        automatically version the new file and keep the old one.
+        Attach (upload) a file to a page, if it exists it will update automatically the
+        version the new file and keep the old one.
         :param title: The page name
         :type  title: ``str``
         :param space: The space name
@@ -2899,8 +2899,8 @@ def add_user_to_group(self, username, group_name):
         """
         Add given user to a group
 
-        :param username: str
-        :param group_name: str
+        :param username: str - username of user to add to group
+        :param group_name: str - name of group to add user to
         :return: Current state of the group
         """
         url = "rest/api/2/group/user"
@@ -2919,11 +2919,11 @@ def add_space_permissions(
         """
         Add permissions to a space
 
-        :param space_key: str
-        :param subject_type: str
-        :param subject_id: str
-        :param operation_key: str
-        :param operation_target: str
+        :param space_key: str - key of space to add permissions to
+        :param subject_type: str - type of subject to add permissions for
+        :param subject_id: str - id of subject to add permissions for
+        :param operation_key: str - key of operation to add permissions for
+        :param operation_target: str - target of operation to add permissions for
         :return: Current permissions of space
         """
         url = "rest/api/space/{}/permission".format(space_key)

atlassian/crowd.py

@@ -32,10 +32,9 @@ def _crowd_api_url(self, api, resource):
 
     def _user_change_status(self, username, active):
         """
-        Change user status
-
-        :params active bool
-
+        Change user status.
+        :param username: str - username
+        :param active: bool - True/False
         :return:
         """
 
@@ -59,12 +58,18 @@ def _user_change_status(self, username, active):
         )
 
     def user(self, username):
+        """
+        Get user information
+        :param username:
+        :return:
+        """
         params = {"username": username}
         return self.get(self._crowd_api_url("usermanagement", "user"), params=params)
 
     def user_activate(self, username):
         """
         Activate user
+        :param username: str - username
         """
 
         return self._user_change_status(username, True)
@@ -116,7 +121,7 @@ def user_deactivate(self, username):
     def user_delete(self, username):
         """
         Delete user
-
+        :param username: str - username
         :return:
         """
 
@@ -141,6 +146,11 @@ def group_add_user(self, username, groupname):
         )
 
     def group_nested_members(self, group):
+        """
+        Get nested members of group
+        :param group:
+        :return:
+        """
         params = {"groupname": group}
         return self.get(self._crowd_api_url("group", "nested"), params=params)
 

atlassian/insight.py

@@ -142,8 +142,8 @@ def add_comment_to_object(self, comment, object_id, role):
         Add comment to Object
 
         :param comment: str
-        :param object_id: int
-        :param role: int
+        :param object_id: int - Object ID
+        :param role: int - Role ID
             0	Insight Users
             1	Insight Managers
             2	Insight Administrators

atlassian/jira.py

@@ -379,7 +379,7 @@ def get_cluster_zdu_state(self):
     # Issue Comments
     def issue_get_comments(self, issue_id):
         """
-        Get Comments on an Issue
+        Get Comments on an Issue.
         :param issue_id: Issue ID
         :raises: requests.exceptions.HTTPError
         :return:
@@ -570,7 +570,7 @@ def get_all_fields(self):
     def create_custom_field(self, name, type, search_key=None, description=None):
         """
         Creates a custom field with the given name and type
-        :param name: str
+        :param name: str - name of the custom field
         :param type: str, like 'com.atlassian.jira.plugin.system.customfieldtypes:textfield'
         :param search_key: str, like above
         :param description: str
@@ -739,7 +739,7 @@ def delete_filter(self, filter_id):
 
     def get_filter_share_permissions(self, filter_id):
         """
-        Gets share permissions of a filter
+        Gets share permissions of a filter.
         :param filter_id: Filter ID
         :return: Returns current share permissions of filter
         """
@@ -759,7 +759,7 @@ def add_filter_share_permission(
         edit=None,
     ):
         """
-        Adds share permission for a filter
+        Adds share permission for a filter. See the documentation of the sharePermissions.
         :param filter_id: Filter ID
         :param type: What type of permission is granted (i.e. user, project)
         :param project_id: Project ID, relevant for type 'project' and 'projectRole'
@@ -815,8 +815,8 @@ def get_groups(self, query=None, exclude=None, limit=20):
         specifically Showing X of Y matching groups.
         The number of groups returned is limited by the system property "jira.ajax.autocomplete.limit"
         The groups will be unique and sorted.
-        :param query: str
-        :param exclude: str
+        :param query: str - Query of searching groups by name.
+        :param exclude: str - Exclude groups from search results.
         :param limit: int
         :return: Returned even if no groups match the given substring
         """
@@ -849,9 +849,8 @@ def remove_group(self, name, swap_group=None):
         If you delete a group and content is restricted to that group, the content will be hidden from all users
         To prevent this, use this parameter to specify a different group to transfer the restrictions
         (comments and worklogs only) to
-
-        :param name: str
-        :param swap_group: str
+        :param name: str - name
+        :param swap_group: str - swap group
         :return:
         """
         log.warning("Removing group...")
@@ -1487,8 +1486,8 @@ def get_issue_remote_links(self, issue_key, global_id=None, internal_id=None):
         """
         Finding all Remote Links on an issue, also with filtering by Global ID and internal ID
         :param issue_key:
-        :param global_id: str
-        :param internal_id: str
+        :param global_id: str - Global ID
+        :param internal_id: str - internal ID
         :return:
         """
         base_url = self.resource_url("issue")
@@ -1512,9 +1511,9 @@ def create_or_update_issue_remote_links(
     ):
         """
         Add Remote Link to Issue, update url if global_id is passed
-        :param issue_key: str
-        :param link_url: str
-        :param title: str
+        :param issue_key: str - issue key
+        :param link_url: str - url of the link
+        :param title: str - title of the link
         :param global_id: str, OPTIONAL:
         :param relationship: str, OPTIONAL: Default by built-in method: 'Web Link'
         :param icon_url: str, OPTIONAL: Link to a 16x16 icon representing the type of the object in the remote system
@@ -4439,7 +4438,7 @@ def get_all_sprint(self, board_id, state=None, start=0, limit=50):
         Returns all sprints from a board, for a given board ID.
         This only includes sprints that the user has permission to view.
         :param board_id:
-        :param state: Filters results to sprints in specified states.
+        :param state: Filter results to sprints in specified states.
                       Valid values: future, active, closed.
                       You can define multiple states separated by commas, e.g. state=active,closed
         :param start: The starting index of the returned sprints.
@@ -4575,23 +4574,23 @@ def dvcs_update_linked_repo_with_remote(self, repository_id):
         url = "rest/bitbucket/1.0/repositories/{}/sync".format(repository_id)
         return self.post(url)
 
-    def flag_issue(self, issueKeys, flag=True):
+    def flag_issue(self, issue_keys, flag=True):
         """
         Flags or un-flags one or multiple issues in Jira with a flag indicator.
-        :param issueKeys: List of issue keys to flag or un-flag.
-        :type issueKeys: list[str]
+        :param issue_keys: List of issue keys to flag or un-flag.
+        :type issue_keys: list[str]
         :param flag: Flag indicating whether to flag or un-flag the issues (default is True for flagging).
         :type flag: bool
         :return: POST request response.
         :rtype: dict
         """
         url = "rest/greenhopper/1.0/xboard/issue/flag/flag.json"
-        data = {"issueKeys": issueKeys, "flag": flag}
+        data = {"issueKeys": issue_keys, "flag": flag}
         return self.post(url, data)
 
     def health_check(self):
         """
-        Get health status
+        Get health status of Jira.
         https://confluence.atlassian.com/jirakb/how-to-retrieve-health-check-results-using-rest-api-867195158.html
         :return:
         """

atlassian/rest_client.py

@@ -209,7 +209,7 @@ def request(
         :param params:
         :param headers:
         :param files:
-        :param trailing: bool
+        :param trailing: bool - OPTIONAL: Add trailing slash to url
         :param absolute: bool, OPTIONAL: Do not prefix url, url is absolute
         :param advanced_mode: bool, OPTIONAL: Return the raw response
         :return: