diff options
Diffstat (limited to 'gitlab')
30 files changed, 635 insertions, 640 deletions
diff --git a/gitlab/base.py b/gitlab/base.py index 5e5f57b..92c2f28 100644 --- a/gitlab/base.py +++ b/gitlab/base.py @@ -298,7 +298,7 @@ class RESTManager(object): """REST manager constructor. Args: - gl (Gitlab): :class:`~gitlab.Gitlab` connection to use to make + gl: :class:`~gitlab.Gitlab` connection to use to make requests. parent: REST object to which the manager is attached. """ diff --git a/gitlab/client.py b/gitlab/client.py index 295712c..3334c42 100644 --- a/gitlab/client.py +++ b/gitlab/client.py @@ -39,21 +39,21 @@ class Gitlab(object): """Represents a GitLab server connection. Args: - url (str): The URL of the GitLab server (defaults to https://gitlab.com). - private_token (str): The user private token - oauth_token (str): An oauth token - job_token (str): A CI job token - ssl_verify (bool|str): Whether SSL certificates should be validated. If + url: The URL of the GitLab server (defaults to https://gitlab.com). + private_token: The user private token + oauth_token: An oauth token + job_token: A CI job token + ssl_verify: Whether SSL certificates should be validated. If the value is a string, it is the path to a CA file used for certificate validation. - timeout (float): Timeout to use for requests to the GitLab server. - http_username (str): Username for HTTP authentication - http_password (str): Password for HTTP authentication - api_version (str): Gitlab API version to use (support for 4 only) - pagination (str): Can be set to 'keyset' to use keyset pagination - order_by (str): Set order_by globally - user_agent (str): A custom user agent to use for making HTTP requests. - retry_transient_errors (bool): Whether to retry after 500, 502, 503, or + timeout: Timeout to use for requests to the GitLab server. + http_username: Username for HTTP authentication + http_password: Password for HTTP authentication + api_version: Gitlab API version to use (support for 4 only) + pagination: Can be set to 'keyset' to use keyset pagination + order_by: Set order_by globally + user_agent: A custom user agent to use for making HTTP requests. + retry_transient_errors: Whether to retry after 500, 502, 503, or 504 responses. Defaults to False. """ @@ -225,11 +225,11 @@ class Gitlab(object): """Create a Gitlab connection from configuration files. Args: - gitlab_id (str): ID of the configuration section. - config_files list[str]: List of paths to configuration files. + gitlab_id: ID of the configuration section. + config_files: List of paths to configuration files. Returns: - (gitlab.Gitlab): A Gitlab connection. + A Gitlab connection. Raises: gitlab.config.GitlabDataError: If the configuration is not correct. @@ -269,7 +269,7 @@ class Gitlab(object): object. Returns: - tuple (str, str): The server version and server revision. + The server version and server revision. ('unknown', 'unknwown') if the server doesn't perform as expected. """ @@ -293,7 +293,7 @@ class Gitlab(object): """Validate a gitlab CI configuration. Args: - content (txt): The .gitlab-ci.yml content + content: The .gitlab-ci.yml content **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -301,8 +301,7 @@ class Gitlab(object): GitlabVerifyError: If the validation could not be done Returns: - tuple: (True, []) if the file is valid, (False, errors(list)) - otherwise + ``(True, [])`` if the file is valid, ``(False, errors(list))`` otherwise """ post_data = {"content": content} data = self.http_post("/ci/lint", post_data=post_data, **kwargs) @@ -317,11 +316,9 @@ class Gitlab(object): """Render an arbitrary Markdown document. Args: - text (str): The markdown text to render - gfm (bool): Render text using GitLab Flavored Markdown. Default is - False - project (str): Full path of a project used a context when `gfm` is - True + text: The markdown text to render + gfm: Render text using GitLab Flavored Markdown. Default is False + project: Full path of a project used a context when `gfm` is True **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -329,7 +326,7 @@ class Gitlab(object): GitlabMarkdownError: If the server cannot perform the request Returns: - str: The HTML rendering of the markdown text. + The HTML rendering of the markdown text. """ post_data = {"text": text, "gfm": gfm} if project is not None: @@ -351,7 +348,7 @@ class Gitlab(object): GitlabGetError: If the server cannot perform the request Returns: - dict: The current license information + The current license information """ result = self.http_get("/license", **kwargs) if isinstance(result, dict): @@ -363,7 +360,7 @@ class Gitlab(object): """Add a new license. Args: - license (str): The license string + license: The license string **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -371,7 +368,7 @@ class Gitlab(object): GitlabPostError: If the server cannot perform the request Returns: - dict: The new license information + The new license information """ data = {"license": license} result = self.http_post("/license", post_data=data, **kwargs) @@ -446,7 +443,7 @@ class Gitlab(object): """Return the base URL with the trailing slash stripped. If the URL is a Falsy value, return the default URL. Returns: - str: The base URL + The base URL """ if not url: return gitlab.const.DEFAULT_URL @@ -460,7 +457,7 @@ class Gitlab(object): it to the stored url. Returns: - str: The full URL + The full URL """ if path.startswith("http://") or path.startswith("https://"): return path @@ -541,20 +538,19 @@ class Gitlab(object): """Make an HTTP request to the Gitlab server. Args: - verb (str): The HTTP method to call ('get', 'post', 'put', - 'delete') - path (str): Path or full URL to query ('/projects' or + verb: The HTTP method to call ('get', 'post', 'put', 'delete') + path: Path or full URL to query ('/projects' or 'http://whatever/v4/api/projecs') - query_data (dict): Data to send as query parameters - post_data (dict|bytes): Data to send in the body (will be converted to + query_data: Data to send as query parameters + post_data: Data to send in the body (will be converted to json by default) - raw (bool): If True, do not convert post_data to json - streamed (bool): Whether the data should be streamed - files (dict): The files to send to the server - timeout (float): The timeout, in seconds, for the request - obey_rate_limit (bool): Whether to obey 429 Too Many Request + raw: If True, do not convert post_data to json + streamed: Whether the data should be streamed + files: The files to send to the server + timeout: The timeout, in seconds, for the request + obey_rate_limit: Whether to obey 429 Too Many Request responses. Defaults to True. - max_retries (int): Max retries after 429 or transient errors, + max_retries: Max retries after 429 or transient errors, set to -1 to retry forever. Defaults to 10. **kwargs: Extra options to send to the server (e.g. sudo) @@ -667,11 +663,11 @@ class Gitlab(object): """Make a GET request to the Gitlab server. Args: - path (str): Path or full URL to query ('/projects' or + path: Path or full URL to query ('/projects' or 'http://whatever/v4/api/projecs') - query_data (dict): Data to send as query parameters - streamed (bool): Whether the data should be streamed - raw (bool): If True do not try to parse the output as json + query_data: Data to send as query parameters + streamed: Whether the data should be streamed + raw: If True do not try to parse the output as json **kwargs: Extra options to send to the server (e.g. sudo) Returns: @@ -712,16 +708,16 @@ class Gitlab(object): """Make a GET request to the Gitlab server for list-oriented queries. Args: - path (str): Path or full URL to query ('/projects' or + path: Path or full URL to query ('/projects' or 'http://whatever/v4/api/projects') - query_data (dict): Data to send as query parameters + query_data: Data to send as query parameters **kwargs: Extra options to send to the server (e.g. sudo, page, per_page) Returns: - list: A list of the objects returned by the server. If `as_list` is - False and no pagination-related arguments (`page`, `per_page`, - `all`) are defined then a GitlabList object (generator) is returned + A list of the objects returned by the server. If ``as_list`` is + False and no pagination-related arguments (``page``, ``per_page``, + ``all``) are defined then a GitlabList object (generator) is returned instead. This object will make API calls when needed to fetch the next items from the server. @@ -761,13 +757,13 @@ class Gitlab(object): """Make a POST request to the Gitlab server. Args: - path (str): Path or full URL to query ('/projects' or + path: Path or full URL to query ('/projects' or 'http://whatever/v4/api/projecs') - query_data (dict): Data to send as query parameters - post_data (dict): Data to send in the body (will be converted to + query_data: Data to send as query parameters + post_data: Data to send in the body (will be converted to json by default) - raw (bool): If True, do not convert post_data to json - files (dict): The files to send to the server + raw: If True, do not convert post_data to json + files: The files to send to the server **kwargs: Extra options to send to the server (e.g. sudo) Returns: @@ -810,13 +806,13 @@ class Gitlab(object): """Make a PUT request to the Gitlab server. Args: - path (str): Path or full URL to query ('/projects' or + path: Path or full URL to query ('/projects' or 'http://whatever/v4/api/projecs') - query_data (dict): Data to send as query parameters + query_data: Data to send as query parameters post_data (dict|bytes): Data to send in the body (will be converted to json by default) - raw (bool): If True, do not convert post_data to json - files (dict): The files to send to the server + raw: If True, do not convert post_data to json + files: The files to send to the server **kwargs: Extra options to send to the server (e.g. sudo) Returns: @@ -849,7 +845,7 @@ class Gitlab(object): """Make a DELETE request to the Gitlab server. Args: - path (str): Path or full URL to query ('/projects' or + path: Path or full URL to query ('/projects' or 'http://whatever/v4/api/projecs') **kwargs: Extra options to send to the server (e.g. sudo) @@ -868,8 +864,8 @@ class Gitlab(object): """Search GitLab resources matching the provided string.' Args: - scope (str): Scope of the search - search (str): Search string + scope: Scope of the search + search: Search string **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -877,7 +873,7 @@ class Gitlab(object): GitlabSearchError: If the server failed to perform the request Returns: - GitlabList: A list of dicts describing the resources found. + A list of dicts describing the resources found. """ data = {"scope": scope, "search": search} return self.http_list("/search", query_data=data, **kwargs) diff --git a/gitlab/exceptions.py b/gitlab/exceptions.py index a756030..6b86471 100644 --- a/gitlab/exceptions.py +++ b/gitlab/exceptions.py @@ -297,8 +297,7 @@ def on_http_error(error: Type[Exception]) -> Callable[[__F], __F]: raise specialized exceptions instead. Args: - error(Exception): The exception type to raise -- must inherit from - GitlabError + The exception type to raise -- must inherit from GitlabError """ def wrap(f: __F) -> __F: diff --git a/gitlab/mixins.py b/gitlab/mixins.py index 0159ecd..ac357b2 100644 --- a/gitlab/mixins.py +++ b/gitlab/mixins.py @@ -87,13 +87,13 @@ class GetMixin(_RestManagerBase): Args: id (int or str): ID of the object to retrieve - lazy (bool): If True, don't request the server, but create a + lazy: If True, don't request the server, but create a shallow object giving access to the managers. This is useful if you want to avoid useless calls to the API. **kwargs: Extra options to send to the server (e.g. sudo) Returns: - object: The generated RESTObject. + The generated RESTObject. Raises: GitlabAuthenticationError: If authentication is not correct @@ -134,7 +134,7 @@ class GetWithoutIdMixin(_RestManagerBase): **kwargs: Extra options to send to the server (e.g. sudo) Returns: - object: The generated RESTObject + The generated RESTObject Raises: GitlabAuthenticationError: If authentication is not correct @@ -199,15 +199,15 @@ class ListMixin(_RestManagerBase): """Retrieve a list of objects. Args: - all (bool): If True, return all the items, without pagination - per_page (int): Number of items to retrieve per request - page (int): ID of the page to return (starts with page 1) - as_list (bool): If set to False and no pagination option is + all: If True, return all the items, without pagination + per_page: Number of items to retrieve per request + page: ID of the page to return (starts with page 1) + as_list: If set to False and no pagination option is defined, return a generator instead of a list **kwargs: Extra options to send to the server (e.g. sudo) Returns: - list: The list of objects, or a generator if `as_list` is False + The list of objects, or a generator if `as_list` is False Raises: GitlabAuthenticationError: If authentication is not correct @@ -282,12 +282,12 @@ class CreateMixin(_RestManagerBase): """Create a new object. Args: - data (dict): parameters to send to the server to create the + data: parameters to send to the server to create the resource **kwargs: Extra options to send to the server (e.g. sudo) Returns: - RESTObject: a new instance of the managed object class built with + a new instance of the managed object class built with the data sent by the server Raises: @@ -357,7 +357,7 @@ class UpdateMixin(_RestManagerBase): """Return the HTTP method to use. Returns: - object: http_put (default) or http_post + http_put (default) or http_post """ if self._update_uses_post: http_method = self.gitlab.http_post @@ -380,7 +380,7 @@ class UpdateMixin(_RestManagerBase): **kwargs: Extra options to send to the server (e.g. sudo) Returns: - dict: The new object data (*not* a RESTObject) + The new object data (*not* a RESTObject) Raises: GitlabAuthenticationError: If authentication is not correct @@ -433,8 +433,8 @@ class SetMixin(_RestManagerBase): """Create or update the object. Args: - key (str): The key of the object to create/update - value (str): The value to set for the object + key: The key of the object to create/update + value: The value to set for the object **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -442,7 +442,7 @@ class SetMixin(_RestManagerBase): GitlabSetError: If an error occurred Returns: - obj: The created/updated attribute + The created/updated attribute """ path = f"{self.path}/{utils.clean_str_id(key)}" data = {"value": value} @@ -623,7 +623,7 @@ class AccessRequestMixin(_RestObjectBase): """Approve an access request. Args: - access_level (int): The access level for the user + access_level: The access level for the user **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -659,12 +659,12 @@ class DownloadMixin(_RestObjectBase): """Download the archive of a resource export. Args: - streamed (bool): If True the data will be processed by chunks of + streamed: If True the data will be processed by chunks of `chunk_size` and each chunk is passed to `action` for treatment action (callable): Callable responsible of dealing with chunk of data - chunk_size (int): Size of each chunk + chunk_size: Size of each chunk **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -672,7 +672,7 @@ class DownloadMixin(_RestObjectBase): GitlabGetError: If the server failed to perform the request Returns: - str: The blob content if streamed is False, None otherwise + The blob content if streamed is False, None otherwise """ path = f"{self.manager.path}/download" result = self.manager.gitlab.http_get( @@ -793,7 +793,7 @@ class TimeTrackingMixin(_RestObjectBase): """Set an estimated time of work for the object. Args: - duration (str): Duration in human format (e.g. 3h30) + duration: Duration in human format (e.g. 3h30) **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -831,7 +831,7 @@ class TimeTrackingMixin(_RestObjectBase): """Add time spent working on the object. Args: - duration (str): Duration in human format (e.g. 3h30) + duration: Duration in human format (e.g. 3h30) **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -878,10 +878,10 @@ class ParticipantsMixin(_RestObjectBase): """List the participants. Args: - all (bool): If True, return all the items, without pagination - per_page (int): Number of items to retrieve per request - page (int): ID of the page to return (starts with page 1) - as_list (bool): If set to False and no pagination option is + all: If True, return all the items, without pagination + per_page: Number of items to retrieve per request + page: ID of the page to return (starts with page 1) + as_list: If set to False and no pagination option is defined, return a generator instead of a list **kwargs: Extra options to send to the server (e.g. sudo) @@ -890,7 +890,7 @@ class ParticipantsMixin(_RestObjectBase): GitlabListError: If the list could not be retrieved Returns: - RESTObjectList: The list of participants + The list of participants """ path = f"{self.manager.path}/{self.get_id()}/participants" @@ -909,8 +909,8 @@ class BadgeRenderMixin(_RestManagerBase): """Preview link_url and image_url after interpolation. Args: - link_url (str): URL of the badge link - image_url (str): URL of the badge image + link_url: URL of the badge link + image_url: URL of the badge image **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -918,7 +918,7 @@ class BadgeRenderMixin(_RestManagerBase): GitlabRenderError: If the rendering failed Returns: - dict: The rendering properties + The rendering properties """ path = f"{self.path}/render" data = {"link_url": link_url, "image_url": image_url} @@ -943,7 +943,7 @@ class PromoteMixin(_RestObjectBase): """Return the HTTP method to use. Returns: - object: http_put (default) or http_post + http_put (default) or http_post """ if self._update_uses_post: http_method = self.manager.gitlab.http_post @@ -964,7 +964,7 @@ class PromoteMixin(_RestObjectBase): GitlabParsingError: If the json data could not be parsed Returns: - dict: The updated object data (*not* a RESTObject) + The updated object data (*not* a RESTObject) """ path = f"{self.manager.path}/{self.id}/promote" diff --git a/gitlab/v4/objects/appearance.py b/gitlab/v4/objects/appearance.py index 6a0c20a..0639c13 100644 --- a/gitlab/v4/objects/appearance.py +++ b/gitlab/v4/objects/appearance.py @@ -48,7 +48,7 @@ class ApplicationAppearanceManager(GetWithoutIdMixin, UpdateMixin, RESTManager): **kwargs: Extra options to send to the server (e.g. sudo) Returns: - dict: The new object data (*not* a RESTObject) + The new object data (*not* a RESTObject) Raises: GitlabAuthenticationError: If authentication is not correct diff --git a/gitlab/v4/objects/clusters.py b/gitlab/v4/objects/clusters.py index 5491654..8bd712a 100644 --- a/gitlab/v4/objects/clusters.py +++ b/gitlab/v4/objects/clusters.py @@ -41,7 +41,7 @@ class GroupClusterManager(CRUDMixin, RESTManager): """Create a new object. Args: - data (dict): Parameters to send to the server to create the + data: Parameters to send to the server to create the resource **kwargs: Extra options to send to the server (e.g. sudo or 'ref_name', 'stage', 'name', 'all') @@ -51,7 +51,7 @@ class GroupClusterManager(CRUDMixin, RESTManager): GitlabCreateError: If the server cannot perform the request Returns: - RESTObject: A new instance of the manage object class build with + A new instance of the manage object class build with the data sent by the server """ path = f"{self.path}/user" @@ -92,7 +92,7 @@ class ProjectClusterManager(CRUDMixin, RESTManager): """Create a new object. Args: - data (dict): Parameters to send to the server to create the + data: Parameters to send to the server to create the resource **kwargs: Extra options to send to the server (e.g. sudo or 'ref_name', 'stage', 'name', 'all') @@ -102,7 +102,7 @@ class ProjectClusterManager(CRUDMixin, RESTManager): GitlabCreateError: If the server cannot perform the request Returns: - RESTObject: A new instance of the manage object class build with + A new instance of the manage object class build with the data sent by the server """ path = f"{self.path}/user" diff --git a/gitlab/v4/objects/commits.py b/gitlab/v4/objects/commits.py index b93dcdf..c675b0f 100644 --- a/gitlab/v4/objects/commits.py +++ b/gitlab/v4/objects/commits.py @@ -39,7 +39,7 @@ class ProjectCommit(RESTObject): GitlabGetError: If the diff could not be retrieved Returns: - list: The changes done in this commit + The changes done in this commit """ path = f"{self.manager.path}/{self.get_id()}/diff" return self.manager.gitlab.http_get(path, **kwargs) @@ -50,7 +50,7 @@ class ProjectCommit(RESTObject): """Cherry-pick a commit into a branch. Args: - branch (str): Name of target branch + branch: Name of target branch **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -69,7 +69,7 @@ class ProjectCommit(RESTObject): """List the references the commit is pushed to. Args: - type (str): The scope of references ('branch', 'tag' or 'all') + type: The scope of references ('branch', 'tag' or 'all') **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -77,7 +77,7 @@ class ProjectCommit(RESTObject): GitlabGetError: If the references could not be retrieved Returns: - list: The references the commit is pushed to. + The references the commit is pushed to. """ path = f"{self.manager.path}/{self.get_id()}/refs" data = {"type": type} @@ -96,7 +96,7 @@ class ProjectCommit(RESTObject): GitlabGetError: If the references could not be retrieved Returns: - list: The merge requests related to the commit. + The merge requests related to the commit. """ path = f"{self.manager.path}/{self.get_id()}/merge_requests" return self.manager.gitlab.http_get(path, **kwargs) @@ -108,16 +108,16 @@ class ProjectCommit(RESTObject): ) -> Union[Dict[str, Any], requests.Response]: """Revert a commit on a given branch. - Args: - branch (str): Name of target branch - **kwargs: Extra options to send to the server (e.g. sudo) + Args: + branch: Name of target branch + **kwargs: Extra options to send to the server (e.g. sudo) - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabRevertError: If the revert could not be performed + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabRevertError: If the revert could not be performed - Returns: - dict: The new commit data (*not* a RESTObject) + Returns: + The new commit data (*not* a RESTObject) """ path = f"{self.manager.path}/{self.get_id()}/revert" post_data = {"branch": branch} @@ -128,15 +128,15 @@ class ProjectCommit(RESTObject): def signature(self, **kwargs: Any) -> Union[Dict[str, Any], requests.Response]: """Get the signature of the commit. - Args: - **kwargs: Extra options to send to the server (e.g. sudo) + Args: + **kwargs: Extra options to send to the server (e.g. sudo) - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the signature could not be retrieved + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the signature could not be retrieved - Returns: - dict: The commit's signature data + Returns: + The commit's signature data """ path = f"{self.manager.path}/{self.get_id()}/signature" return self.manager.gitlab.http_get(path, **kwargs) @@ -191,7 +191,7 @@ class ProjectCommitStatusManager(ListMixin, CreateMixin, RESTManager): """Create a new object. Args: - data (dict): Parameters to send to the server to create the + data: Parameters to send to the server to create the resource **kwargs: Extra options to send to the server (e.g. sudo or 'ref_name', 'stage', 'name', 'all') @@ -201,7 +201,7 @@ class ProjectCommitStatusManager(ListMixin, CreateMixin, RESTManager): GitlabCreateError: If the server cannot perform the request Returns: - RESTObject: A new instance of the manage object class build with + A new instance of the manage object class build with the data sent by the server """ # project_id and commit_id are in the data dict when using the CLI, but diff --git a/gitlab/v4/objects/deploy_keys.py b/gitlab/v4/objects/deploy_keys.py index 9233805..f325f69 100644 --- a/gitlab/v4/objects/deploy_keys.py +++ b/gitlab/v4/objects/deploy_keys.py @@ -43,7 +43,7 @@ class ProjectKeyManager(CRUDMixin, RESTManager): """Enable a deploy key for a project. Args: - key_id (int): The ID of the key to enable + key_id: The ID of the key to enable **kwargs: Extra options to send to the server (e.g. sudo) Raises: diff --git a/gitlab/v4/objects/epics.py b/gitlab/v4/objects/epics.py index 38d244c..aec670b 100644 --- a/gitlab/v4/objects/epics.py +++ b/gitlab/v4/objects/epics.py @@ -92,7 +92,7 @@ class GroupEpicIssueManager( """Create a new object. Args: - data (dict): Parameters to send to the server to create the + data: Parameters to send to the server to create the resource **kwargs: Extra options to send to the server (e.g. sudo) @@ -101,7 +101,7 @@ class GroupEpicIssueManager( GitlabCreateError: If the server cannot perform the request Returns: - RESTObject: A new instance of the manage object class build with + A new instance of the manage object class build with the data sent by the server """ if TYPE_CHECKING: diff --git a/gitlab/v4/objects/features.py b/gitlab/v4/objects/features.py index 4aaa185..80b0cd6 100644 --- a/gitlab/v4/objects/features.py +++ b/gitlab/v4/objects/features.py @@ -37,12 +37,12 @@ class FeatureManager(ListMixin, DeleteMixin, RESTManager): """Create or update the object. Args: - name (str): The value to set for the object + name: The value to set for the object value (bool/int): The value to set for the object - feature_group (str): A feature group name - user (str): A GitLab username - group (str): A GitLab group - project (str): A GitLab project in form group/project + feature_group: A feature group name + user: A GitLab username + group: A GitLab group + project: A GitLab project in form group/project **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -50,7 +50,7 @@ class FeatureManager(ListMixin, DeleteMixin, RESTManager): GitlabSetError: If an error occurred Returns: - obj: The created/updated attribute + The created/updated attribute """ path = f"{self.path}/{name.replace('/', '%2F')}" data = { diff --git a/gitlab/v4/objects/files.py b/gitlab/v4/objects/files.py index ce7317d..206bdeb 100644 --- a/gitlab/v4/objects/files.py +++ b/gitlab/v4/objects/files.py @@ -32,7 +32,7 @@ class ProjectFile(SaveMixin, ObjectDeleteMixin, RESTObject): """Returns the decoded content of the file. Returns: - (bytes): the decoded content. + : the decoded content. """ return base64.b64decode(self.content) @@ -46,8 +46,8 @@ class ProjectFile(SaveMixin, ObjectDeleteMixin, RESTObject): The object is updated to match what the server returns. Args: - branch (str): Branch in which the file will be updated - commit_message (str): Message to send with the commit + branch: Branch in which the file will be updated + commit_message: Message to send with the commit **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -68,8 +68,8 @@ class ProjectFile(SaveMixin, ObjectDeleteMixin, RESTObject): """Delete the file from the server. Args: - branch (str): Branch from which the file will be removed - commit_message (str): Commit message for the deletion + branch: Branch from which the file will be removed + commit_message: Commit message for the deletion **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -102,8 +102,8 @@ class ProjectFileManager(GetMixin, CreateMixin, UpdateMixin, DeleteMixin, RESTMa """Retrieve a single file. Args: - file_path (str): Path of the file to retrieve - ref (str): Name of the branch, tag or commit + file_path: Path of the file to retrieve + ref: Name of the branch, tag or commit **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -111,7 +111,7 @@ class ProjectFileManager(GetMixin, CreateMixin, UpdateMixin, DeleteMixin, RESTMa GitlabGetError: If the file could not be retrieved Returns: - object: The generated RESTObject + The generated RESTObject """ return cast(ProjectFile, GetMixin.get(self, file_path, ref=ref, **kwargs)) @@ -127,12 +127,12 @@ class ProjectFileManager(GetMixin, CreateMixin, UpdateMixin, DeleteMixin, RESTMa """Create a new object. Args: - data (dict): parameters to send to the server to create the + data: parameters to send to the server to create the resource **kwargs: Extra options to send to the server (e.g. sudo) Returns: - RESTObject: a new instance of the managed object class built with + a new instance of the managed object class built with the data sent by the server Raises: @@ -165,7 +165,7 @@ class ProjectFileManager(GetMixin, CreateMixin, UpdateMixin, DeleteMixin, RESTMa **kwargs: Extra options to send to the server (e.g. sudo) Returns: - dict: The new object data (*not* a RESTObject) + The new object data (*not* a RESTObject) Raises: GitlabAuthenticationError: If authentication is not correct @@ -194,9 +194,9 @@ class ProjectFileManager(GetMixin, CreateMixin, UpdateMixin, DeleteMixin, RESTMa """Delete a file on the server. Args: - file_path (str): Path of the file to remove - branch (str): Branch from which the file will be removed - commit_message (str): Commit message for the deletion + file_path: Path of the file to remove + branch: Branch from which the file will be removed + commit_message: Commit message for the deletion **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -220,23 +220,23 @@ class ProjectFileManager(GetMixin, CreateMixin, UpdateMixin, DeleteMixin, RESTMa ) -> Optional[bytes]: """Return the content of a file for a commit. - Args: - ref (str): ID of the commit - filepath (str): Path of the file to return - streamed (bool): If True the data will be processed by chunks of - `chunk_size` and each chunk is passed to `action` for - treatment - action (callable): Callable responsible of dealing with chunk of - data - chunk_size (int): Size of each chunk - **kwargs: Extra options to send to the server (e.g. sudo) - - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the file could not be retrieved - - Returns: - str: The file content + Args: + ref: ID of the commit + filepath: Path of the file to return + streamed: If True the data will be processed by chunks of + `chunk_size` and each chunk is passed to `action` for + treatment + action (callable): Callable responsible of dealing with chunk of + data + chunk_size: Size of each chunk + **kwargs: Extra options to send to the server (e.g. sudo) + + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the file could not be retrieved + + Returns: + The file content """ file_path = file_path.replace("/", "%2F").replace(".", "%2E") path = f"{self.path}/{file_path}/raw" @@ -254,8 +254,8 @@ class ProjectFileManager(GetMixin, CreateMixin, UpdateMixin, DeleteMixin, RESTMa """Return the content of a file for a commit. Args: - file_path (str): Path of the file to retrieve - ref (str): Name of the branch, tag or commit + file_path: Path of the file to retrieve + ref: Name of the branch, tag or commit **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -263,7 +263,7 @@ class ProjectFileManager(GetMixin, CreateMixin, UpdateMixin, DeleteMixin, RESTMa GitlabListError: If the server failed to perform the request Returns: - list(blame): a list of commits/lines matching the file + a list of commits/lines matching the file """ file_path = file_path.replace("/", "%2F").replace(".", "%2E") path = f"{self.path}/{file_path}/blame" diff --git a/gitlab/v4/objects/geo_nodes.py b/gitlab/v4/objects/geo_nodes.py index 7fffb63..1bb3412 100644 --- a/gitlab/v4/objects/geo_nodes.py +++ b/gitlab/v4/objects/geo_nodes.py @@ -41,15 +41,15 @@ class GeoNode(SaveMixin, ObjectDeleteMixin, RESTObject): def status(self, **kwargs: Any) -> Dict[str, Any]: """Get the status of the geo node. - Args: - **kwargs: Extra options to send to the server (e.g. sudo) + Args: + **kwargs: Extra options to send to the server (e.g. sudo) - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the server failed to perform the request + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the server failed to perform the request - Returns: - dict: The status of the geo node + Returns: + The status of the geo node """ path = f"/geo_nodes/{self.get_id()}/status" result = self.manager.gitlab.http_get(path, **kwargs) @@ -73,15 +73,15 @@ class GeoNodeManager(RetrieveMixin, UpdateMixin, DeleteMixin, RESTManager): def status(self, **kwargs: Any) -> List[Dict[str, Any]]: """Get the status of all the geo nodes. - Args: - **kwargs: Extra options to send to the server (e.g. sudo) + Args: + **kwargs: Extra options to send to the server (e.g. sudo) - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the server failed to perform the request + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the server failed to perform the request - Returns: - list: The status of all the geo nodes + Returns: + The status of all the geo nodes """ result = self.gitlab.http_list("/geo_nodes/status", **kwargs) if TYPE_CHECKING: @@ -93,15 +93,15 @@ class GeoNodeManager(RetrieveMixin, UpdateMixin, DeleteMixin, RESTManager): def current_failures(self, **kwargs: Any) -> List[Dict[str, Any]]: """Get the list of failures on the current geo node. - Args: - **kwargs: Extra options to send to the server (e.g. sudo) + Args: + **kwargs: Extra options to send to the server (e.g. sudo) - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the server failed to perform the request + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the server failed to perform the request - Returns: - list: The list of failures + Returns: + The list of failures """ result = self.gitlab.http_list("/geo_nodes/current/failures", **kwargs) if TYPE_CHECKING: diff --git a/gitlab/v4/objects/groups.py b/gitlab/v4/objects/groups.py index 7016e52..4ac47e3 100644 --- a/gitlab/v4/objects/groups.py +++ b/gitlab/v4/objects/groups.py @@ -83,7 +83,7 @@ class Group(SaveMixin, ObjectDeleteMixin, RESTObject): """Transfer a project to this group. Args: - to_project_id (int): ID of the project to transfer + to_project_id: ID of the project to transfer **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -101,8 +101,8 @@ class Group(SaveMixin, ObjectDeleteMixin, RESTObject): """Search the group resources matching the provided string.' Args: - scope (str): Scope of the search - search (str): Search string + scope: Scope of the search + search: Search string **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -110,7 +110,7 @@ class Group(SaveMixin, ObjectDeleteMixin, RESTObject): GitlabSearchError: If the server failed to perform the request Returns: - GitlabList: A list of dicts describing the resources found. + A list of dicts describing the resources found. """ data = {"scope": scope, "search": search} path = f"/groups/{self.get_id()}/search" @@ -124,10 +124,10 @@ class Group(SaveMixin, ObjectDeleteMixin, RESTObject): """Add an LDAP group link. Args: - cn (str): CN of the LDAP group - group_access (int): Minimum access level for members of the LDAP + cn: CN of the LDAP group + group_access: Minimum access level for members of the LDAP group - provider (str): LDAP provider for the LDAP group + provider: LDAP provider for the LDAP group **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -146,8 +146,8 @@ class Group(SaveMixin, ObjectDeleteMixin, RESTObject): """Delete an LDAP group link. Args: - cn (str): CN of the LDAP group - provider (str): LDAP provider for the LDAP group + cn: CN of the LDAP group + provider: LDAP provider for the LDAP group **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -187,8 +187,8 @@ class Group(SaveMixin, ObjectDeleteMixin, RESTObject): """Share the group with a group. Args: - group_id (int): ID of the group. - group_access (int): Access level for the group. + group_id: ID of the group. + group_access: Access level for the group. **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -215,7 +215,7 @@ class Group(SaveMixin, ObjectDeleteMixin, RESTObject): """Delete a shared group link within a group. Args: - group_id (int): ID of the group. + group_id: ID of the group. **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -306,20 +306,20 @@ class GroupManager(CRUDMixin, RESTManager): ) -> Union[Dict[str, Any], requests.Response]: """Import a group from an archive file. - Args: - file: Data or file object containing the group - path (str): The path for the new group to be imported. - name (str): The name for the new group. - parent_id (str): ID of a parent group that the group will - be imported into. - **kwargs: Extra options to send to the server (e.g. sudo) + Args: + file: Data or file object containing the group + path: The path for the new group to be imported. + name: The name for the new group. + parent_id: ID of a parent group that the group will + be imported into. + **kwargs: Extra options to send to the server (e.g. sudo) - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabImportError: If the server failed to perform the request + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabImportError: If the server failed to perform the request - Returns: - dict: A representation of the import status. + Returns: + A representation of the import status. """ files = {"file": ("file.tar.gz", file, "application/octet-stream")} data = {"path": path, "name": name} diff --git a/gitlab/v4/objects/issues.py b/gitlab/v4/objects/issues.py index 8cd2317..c615144 100644 --- a/gitlab/v4/objects/issues.py +++ b/gitlab/v4/objects/issues.py @@ -152,7 +152,7 @@ class ProjectIssue( GitlabGetErrot: If the merge requests could not be retrieved Returns: - list: The list of merge requests. + The list of merge requests. """ path = f"{self.manager.path}/{self.get_id()}/related_merge_requests" result = self.manager.gitlab.http_get(path, **kwargs) @@ -165,15 +165,15 @@ class ProjectIssue( def closed_by(self, **kwargs: Any) -> Dict[str, Any]: """List merge requests that will close the issue when merged. - Args: - **kwargs: Extra options to send to the server (e.g. sudo) + Args: + **kwargs: Extra options to send to the server (e.g. sudo) - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetErrot: If the merge requests could not be retrieved + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetErrot: If the merge requests could not be retrieved - Returns: - list: The list of merge requests. + Returns: + The list of merge requests. """ path = f"{self.manager.path}/{self.get_id()}/closed_by" result = self.manager.gitlab.http_get(path, **kwargs) @@ -260,12 +260,12 @@ class ProjectIssueLinkManager(ListMixin, CreateMixin, DeleteMixin, RESTManager): """Create a new object. Args: - data (dict): parameters to send to the server to create the + data: parameters to send to the server to create the resource **kwargs: Extra options to send to the server (e.g. sudo) Returns: - RESTObject, RESTObject: The source and target issues + The source and target issues Raises: GitlabAuthenticationError: If authentication is not correct diff --git a/gitlab/v4/objects/jobs.py b/gitlab/v4/objects/jobs.py index eba9648..63cb5fd 100644 --- a/gitlab/v4/objects/jobs.py +++ b/gitlab/v4/objects/jobs.py @@ -123,12 +123,12 @@ class ProjectJob(RefreshMixin, RESTObject): """Get the job artifacts. Args: - streamed (bool): If True the data will be processed by chunks of + streamed: If True the data will be processed by chunks of `chunk_size` and each chunk is passed to `action` for treatment action (callable): Callable responsible of dealing with chunk of data - chunk_size (int): Size of each chunk + chunk_size: Size of each chunk **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -136,7 +136,7 @@ class ProjectJob(RefreshMixin, RESTObject): GitlabGetError: If the artifacts could not be retrieved Returns: - bytes: The artifacts if `streamed` is False, None otherwise. + The artifacts if `streamed` is False, None otherwise. """ path = f"{self.manager.path}/{self.get_id()}/artifacts" result = self.manager.gitlab.http_get( @@ -159,13 +159,13 @@ class ProjectJob(RefreshMixin, RESTObject): """Get a single artifact file from within the job's artifacts archive. Args: - path (str): Path of the artifact - streamed (bool): If True the data will be processed by chunks of + path: Path of the artifact + streamed: If True the data will be processed by chunks of `chunk_size` and each chunk is passed to `action` for treatment action (callable): Callable responsible of dealing with chunk of data - chunk_size (int): Size of each chunk + chunk_size: Size of each chunk **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -173,7 +173,7 @@ class ProjectJob(RefreshMixin, RESTObject): GitlabGetError: If the artifacts could not be retrieved Returns: - bytes: The artifacts if `streamed` is False, None otherwise. + The artifacts if `streamed` is False, None otherwise. """ path = f"{self.manager.path}/{self.get_id()}/artifacts/{path}" result = self.manager.gitlab.http_get( @@ -194,21 +194,21 @@ class ProjectJob(RefreshMixin, RESTObject): ) -> Dict[str, Any]: """Get the job trace. - Args: - streamed (bool): If True the data will be processed by chunks of - `chunk_size` and each chunk is passed to `action` for - treatment - action (callable): Callable responsible of dealing with chunk of - data - chunk_size (int): Size of each chunk - **kwargs: Extra options to send to the server (e.g. sudo) - - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the artifacts could not be retrieved - - Returns: - str: The trace + Args: + streamed: If True the data will be processed by chunks of + `chunk_size` and each chunk is passed to `action` for + treatment + action (callable): Callable responsible of dealing with chunk of + data + chunk_size: Size of each chunk + **kwargs: Extra options to send to the server (e.g. sudo) + + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the artifacts could not be retrieved + + Returns: + The trace """ path = f"{self.manager.path}/{self.get_id()}/trace" result = self.manager.gitlab.http_get( diff --git a/gitlab/v4/objects/ldap.py b/gitlab/v4/objects/ldap.py index 0ba9354..10667b4 100644 --- a/gitlab/v4/objects/ldap.py +++ b/gitlab/v4/objects/ldap.py @@ -23,15 +23,15 @@ class LDAPGroupManager(RESTManager): """Retrieve a list of objects. Args: - all (bool): If True, return all the items, without pagination - per_page (int): Number of items to retrieve per request - page (int): ID of the page to return (starts with page 1) - as_list (bool): If set to False and no pagination option is + all: If True, return all the items, without pagination + per_page: Number of items to retrieve per request + page: ID of the page to return (starts with page 1) + as_list: If set to False and no pagination option is defined, return a generator instead of a list **kwargs: Extra options to send to the server (e.g. sudo) Returns: - list: The list of objects, or a generator if `as_list` is False + The list of objects, or a generator if `as_list` is False Raises: GitlabAuthenticationError: If authentication is not correct diff --git a/gitlab/v4/objects/merge_request_approvals.py b/gitlab/v4/objects/merge_request_approvals.py index e487322..109d04b 100644 --- a/gitlab/v4/objects/merge_request_approvals.py +++ b/gitlab/v4/objects/merge_request_approvals.py @@ -55,8 +55,8 @@ class ProjectApprovalManager(GetWithoutIdMixin, UpdateMixin, RESTManager): """Change project-level allowed approvers and approver groups. Args: - approver_ids (list): User IDs that can approve MRs - approver_group_ids (list): Group IDs whose members can approve MRs + approver_ids: User IDs that can approve MRs + approver_group_ids: Group IDs whose members can approve MRs Raises: GitlabAuthenticationError: If authentication is not correct @@ -119,7 +119,7 @@ class ProjectMergeRequestApprovalManager(GetWithoutIdMixin, UpdateMixin, RESTMan Args: approvals_required (integer): The number of required approvals for this rule approver_ids (list of integers): User IDs that can approve MRs - approver_group_ids (list): Group IDs whose members can approve MRs + approver_group_ids: Group IDs whose members can approve MRs Raises: GitlabAuthenticationError: If authentication is not correct @@ -211,7 +211,7 @@ class ProjectMergeRequestApprovalRuleManager( """Create a new object. Args: - data (dict): Parameters to send to the server to create the + data: Parameters to send to the server to create the resource **kwargs: Extra options to send to the server (e.g. sudo or 'ref_name', 'stage', 'name', 'all') @@ -221,7 +221,7 @@ class ProjectMergeRequestApprovalRuleManager( GitlabCreateError: If the server cannot perform the request Returns: - RESTObject: A new instance of the manage object class build with + A new instance of the manage object class build with the data sent by the server """ if TYPE_CHECKING: diff --git a/gitlab/v4/objects/merge_requests.py b/gitlab/v4/objects/merge_requests.py index 068f25d..bede4bd 100644 --- a/gitlab/v4/objects/merge_requests.py +++ b/gitlab/v4/objects/merge_requests.py @@ -196,10 +196,10 @@ class ProjectMergeRequest( """List issues that will close on merge." Args: - all (bool): If True, return all the items, without pagination - per_page (int): Number of items to retrieve per request - page (int): ID of the page to return (starts with page 1) - as_list (bool): If set to False and no pagination option is + all: If True, return all the items, without pagination + per_page: Number of items to retrieve per request + page: ID of the page to return (starts with page 1) + as_list: If set to False and no pagination option is defined, return a generator instead of a list **kwargs: Extra options to send to the server (e.g. sudo) @@ -208,7 +208,7 @@ class ProjectMergeRequest( GitlabListError: If the list could not be retrieved Returns: - RESTObjectList: List of issues + List of issues """ path = f"{self.manager.path}/{self.get_id()}/closes_issues" data_list = self.manager.gitlab.http_list(path, as_list=False, **kwargs) @@ -223,10 +223,10 @@ class ProjectMergeRequest( """List the merge request commits. Args: - all (bool): If True, return all the items, without pagination - per_page (int): Number of items to retrieve per request - page (int): ID of the page to return (starts with page 1) - as_list (bool): If set to False and no pagination option is + all: If True, return all the items, without pagination + per_page: Number of items to retrieve per request + page: ID of the page to return (starts with page 1) + as_list: If set to False and no pagination option is defined, return a generator instead of a list **kwargs: Extra options to send to the server (e.g. sudo) @@ -235,7 +235,7 @@ class ProjectMergeRequest( GitlabListError: If the list could not be retrieved Returns: - RESTObjectList: The list of commits + The list of commits """ path = f"{self.manager.path}/{self.get_id()}/commits" @@ -258,7 +258,7 @@ class ProjectMergeRequest( GitlabListError: If the list could not be retrieved Returns: - RESTObjectList: List of changes + List of changes """ path = f"{self.manager.path}/{self.get_id()}/changes" return self.manager.gitlab.http_get(path, **kwargs) @@ -269,7 +269,7 @@ class ProjectMergeRequest( """Approve the merge request. Args: - sha (str): Head SHA of MR + sha: Head SHA of MR **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -365,10 +365,10 @@ class ProjectMergeRequest( """Accept the merge request. Args: - merge_commit_message (str): Commit message - should_remove_source_branch (bool): If True, removes the source + merge_commit_message: Commit message + should_remove_source_branch: If True, removes the source branch - merge_when_pipeline_succeeds (bool): Wait for the build to succeed, + merge_when_pipeline_succeeds: Wait for the build to succeed, then merge **kwargs: Extra options to send to the server (e.g. sudo) diff --git a/gitlab/v4/objects/milestones.py b/gitlab/v4/objects/milestones.py index 8ba9d61..a1e48a5 100644 --- a/gitlab/v4/objects/milestones.py +++ b/gitlab/v4/objects/milestones.py @@ -30,10 +30,10 @@ class GroupMilestone(SaveMixin, ObjectDeleteMixin, RESTObject): """List issues related to this milestone. Args: - all (bool): If True, return all the items, without pagination - per_page (int): Number of items to retrieve per request - page (int): ID of the page to return (starts with page 1) - as_list (bool): If set to False and no pagination option is + all: If True, return all the items, without pagination + per_page: Number of items to retrieve per request + page: ID of the page to return (starts with page 1) + as_list: If set to False and no pagination option is defined, return a generator instead of a list **kwargs: Extra options to send to the server (e.g. sudo) @@ -42,7 +42,7 @@ class GroupMilestone(SaveMixin, ObjectDeleteMixin, RESTObject): GitlabListError: If the list could not be retrieved Returns: - RESTObjectList: The list of issues + The list of issues """ path = f"{self.manager.path}/{self.get_id()}/issues" @@ -59,10 +59,10 @@ class GroupMilestone(SaveMixin, ObjectDeleteMixin, RESTObject): """List the merge requests related to this milestone. Args: - all (bool): If True, return all the items, without pagination - per_page (int): Number of items to retrieve per request - page (int): ID of the page to return (starts with page 1) - as_list (bool): If set to False and no pagination option is + all: If True, return all the items, without pagination + per_page: Number of items to retrieve per request + page: ID of the page to return (starts with page 1) + as_list: If set to False and no pagination option is defined, return a generator instead of a list **kwargs: Extra options to send to the server (e.g. sudo) @@ -71,7 +71,7 @@ class GroupMilestone(SaveMixin, ObjectDeleteMixin, RESTObject): GitlabListError: If the list could not be retrieved Returns: - RESTObjectList: The list of merge requests + The list of merge requests """ path = f"{self.manager.path}/{self.get_id()}/merge_requests" data_list = self.manager.gitlab.http_list(path, as_list=False, **kwargs) @@ -111,10 +111,10 @@ class ProjectMilestone(PromoteMixin, SaveMixin, ObjectDeleteMixin, RESTObject): """List issues related to this milestone. Args: - all (bool): If True, return all the items, without pagination - per_page (int): Number of items to retrieve per request - page (int): ID of the page to return (starts with page 1) - as_list (bool): If set to False and no pagination option is + all: If True, return all the items, without pagination + per_page: Number of items to retrieve per request + page: ID of the page to return (starts with page 1) + as_list: If set to False and no pagination option is defined, return a generator instead of a list **kwargs: Extra options to send to the server (e.g. sudo) @@ -123,7 +123,7 @@ class ProjectMilestone(PromoteMixin, SaveMixin, ObjectDeleteMixin, RESTObject): GitlabListError: If the list could not be retrieved Returns: - RESTObjectList: The list of issues + The list of issues """ path = f"{self.manager.path}/{self.get_id()}/issues" @@ -140,10 +140,10 @@ class ProjectMilestone(PromoteMixin, SaveMixin, ObjectDeleteMixin, RESTObject): """List the merge requests related to this milestone. Args: - all (bool): If True, return all the items, without pagination - per_page (int): Number of items to retrieve per request - page (int): ID of the page to return (starts with page 1) - as_list (bool): If set to False and no pagination option is + all: If True, return all the items, without pagination + per_page: Number of items to retrieve per request + page: ID of the page to return (starts with page 1) + as_list: If set to False and no pagination option is defined, return a generator instead of a list **kwargs: Extra options to send to the server (e.g. sudo) @@ -152,7 +152,7 @@ class ProjectMilestone(PromoteMixin, SaveMixin, ObjectDeleteMixin, RESTObject): GitlabListError: If the list could not be retrieved Returns: - RESTObjectList: The list of merge requests + The list of merge requests """ path = f"{self.manager.path}/{self.get_id()}/merge_requests" data_list = self.manager.gitlab.http_list(path, as_list=False, **kwargs) diff --git a/gitlab/v4/objects/packages.py b/gitlab/v4/objects/packages.py index 0062067..9aa496c 100644 --- a/gitlab/v4/objects/packages.py +++ b/gitlab/v4/objects/packages.py @@ -52,12 +52,12 @@ class GenericPackageManager(RESTManager): """Upload a file as a generic package. Args: - package_name (str): The package name. Must follow generic package + package_name: The package name. Must follow generic package name regex rules - package_version (str): The package version. Must follow semantic + package_version: The package version. Must follow semantic version regex rules - file_name (str): The name of the file as uploaded in the registry - path (str): The path to a local file to upload + file_name: The name of the file as uploaded in the registry + path: The path to a local file to upload Raises: GitlabConnectionError: If the server cannot be reached @@ -65,7 +65,7 @@ class GenericPackageManager(RESTManager): GitlabUploadError: If ``filepath`` cannot be read Returns: - GenericPackage: An object storing the metadata of the uploaded package. + An object storing the metadata of the uploaded package. https://docs.gitlab.com/ee/user/packages/generic_packages/ """ @@ -109,24 +109,24 @@ class GenericPackageManager(RESTManager): ) -> Optional[bytes]: """Download a generic package. - Args: - package_name (str): The package name. - package_version (str): The package version. - file_name (str): The name of the file in the registry - streamed (bool): If True the data will be processed by chunks of - `chunk_size` and each chunk is passed to `action` for - treatment - action (callable): Callable responsible of dealing with chunk of - data - chunk_size (int): Size of each chunk - **kwargs: Extra options to send to the server (e.g. sudo) - - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the server failed to perform the request - - Returns: - str: The package content if streamed is False, None otherwise + Args: + package_name: The package name. + package_version: The package version. + file_name: The name of the file in the registry + streamed: If True the data will be processed by chunks of + `chunk_size` and each chunk is passed to `action` for + treatment + action (callable): Callable responsible of dealing with chunk of + data + chunk_size: Size of each chunk + **kwargs: Extra options to send to the server (e.g. sudo) + + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the server failed to perform the request + + Returns: + The package content if streamed is False, None otherwise """ path = f"{self._computed_path}/{package_name}/{package_version}/{file_name}" result = self.gitlab.http_get(path, streamed=streamed, raw=True, **kwargs) diff --git a/gitlab/v4/objects/pipelines.py b/gitlab/v4/objects/pipelines.py index 56da896..fd597da 100644 --- a/gitlab/v4/objects/pipelines.py +++ b/gitlab/v4/objects/pipelines.py @@ -113,7 +113,7 @@ class ProjectPipelineManager(RetrieveMixin, CreateMixin, DeleteMixin, RESTManage """Creates a new object. Args: - data (dict): Parameters to send to the server to create the + data: Parameters to send to the server to create the resource **kwargs: Extra options to send to the server (e.g. sudo) @@ -122,7 +122,7 @@ class ProjectPipelineManager(RetrieveMixin, CreateMixin, DeleteMixin, RESTManage GitlabCreateError: If the server cannot perform the request Returns: - RESTObject: A new instance of the managed object class build with + A new instance of the managed object class build with the data sent by the server """ if TYPE_CHECKING: diff --git a/gitlab/v4/objects/projects.py b/gitlab/v4/objects/projects.py index c5ce717..87d25cd 100644 --- a/gitlab/v4/objects/projects.py +++ b/gitlab/v4/objects/projects.py @@ -171,7 +171,7 @@ class Project(RefreshMixin, SaveMixin, ObjectDeleteMixin, RepositoryMixin, RESTO """Create a forked from/to relation between existing projects. Args: - forked_from_id (int): The ID of the project that was forked from + forked_from_id: The ID of the project that was forked from **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -297,8 +297,8 @@ class Project(RefreshMixin, SaveMixin, ObjectDeleteMixin, RepositoryMixin, RESTO """Share the project with a group. Args: - group_id (int): ID of the group. - group_access (int): Access level for the group. + group_id: ID of the group. + group_access: Access level for the group. **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -319,7 +319,7 @@ class Project(RefreshMixin, SaveMixin, ObjectDeleteMixin, RepositoryMixin, RESTO """Delete a shared project link within a group. Args: - group_id (int): ID of the group. + group_id: ID of the group. **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -344,9 +344,9 @@ class Project(RefreshMixin, SaveMixin, ObjectDeleteMixin, RepositoryMixin, RESTO See https://gitlab.com/help/ci/triggers/README.md#trigger-a-build Args: - ref (str): Commit to build; can be a branch name or a tag - token (str): The trigger token - variables (dict): Variables passed to the build script + ref: Commit to build; can be a branch name or a tag + token: The trigger token + variables: Variables passed to the build script **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -389,28 +389,28 @@ class Project(RefreshMixin, SaveMixin, ObjectDeleteMixin, RepositoryMixin, RESTO ) -> Dict[str, Any]: """Upload the specified file into the project. - .. note:: + .. note:: - Either ``filedata`` or ``filepath`` *MUST* be specified. + Either ``filedata`` or ``filepath`` *MUST* be specified. - Args: - filename (str): The name of the file being uploaded - filedata (bytes): The raw data of the file being uploaded - filepath (str): The path to a local file to upload (optional) + Args: + filename: The name of the file being uploaded + filedata (bytes): The raw data of the file being uploaded + filepath: The path to a local file to upload (optional) - Raises: - GitlabConnectionError: If the server cannot be reached - GitlabUploadError: If the file upload fails - GitlabUploadError: If ``filedata`` and ``filepath`` are not - specified - GitlabUploadError: If both ``filedata`` and ``filepath`` are - specified + Raises: + GitlabConnectionError: If the server cannot be reached + GitlabUploadError: If the file upload fails + GitlabUploadError: If ``filedata`` and ``filepath`` are not + specified + GitlabUploadError: If both ``filedata`` and ``filepath`` are + specified - Returns: - dict: A ``dict`` with the keys: - * ``alt`` - The alternate text for the upload - * ``url`` - The direct url to the uploaded file - * ``markdown`` - Markdown for the uploaded file + Returns: + A ``dict`` with the keys: + * ``alt`` - The alternate text for the upload + * ``url`` - The direct url to the uploaded file + * ``markdown`` - Markdown for the uploaded file """ if filepath is None and filedata is None: raise exc.GitlabUploadError("No file contents or path specified") @@ -442,22 +442,22 @@ class Project(RefreshMixin, SaveMixin, ObjectDeleteMixin, RepositoryMixin, RESTO ) -> Optional[bytes]: """Return a snapshot of the repository. - Args: - wiki (bool): If True return the wiki repository - streamed (bool): If True the data will be processed by chunks of - `chunk_size` and each chunk is passed to `action` for - treatment. - action (callable): Callable responsible of dealing with chunk of - data - chunk_size (int): Size of each chunk - **kwargs: Extra options to send to the server (e.g. sudo) - - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the content could not be retrieved - - Returns: - str: The uncompressed tar archive of the repository + Args: + wiki: If True return the wiki repository + streamed: If True the data will be processed by chunks of + `chunk_size` and each chunk is passed to `action` for + treatment. + action (callable): Callable responsible of dealing with chunk of + data + chunk_size: Size of each chunk + **kwargs: Extra options to send to the server (e.g. sudo) + + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the content could not be retrieved + + Returns: + The uncompressed tar archive of the repository """ path = f"/projects/{self.get_id()}/snapshot" result = self.manager.gitlab.http_get( @@ -475,8 +475,8 @@ class Project(RefreshMixin, SaveMixin, ObjectDeleteMixin, RepositoryMixin, RESTO """Search the project resources matching the provided string.' Args: - scope (str): Scope of the search - search (str): Search string + scope: Scope of the search + search: Search string **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -484,7 +484,7 @@ class Project(RefreshMixin, SaveMixin, ObjectDeleteMixin, RepositoryMixin, RESTO GitlabSearchError: If the server failed to perform the request Returns: - GitlabList: A list of dicts describing the resources found. + A list of dicts describing the resources found. """ data = {"scope": scope, "search": search} path = f"/projects/{self.get_id()}/search" @@ -511,7 +511,7 @@ class Project(RefreshMixin, SaveMixin, ObjectDeleteMixin, RepositoryMixin, RESTO """Transfer a project to the given namespace ID Args: - to_namespace (str): ID or path of the namespace to transfer the + to_namespace: ID or path of the namespace to transfer the project to **kwargs: Extra options to send to the server (e.g. sudo) @@ -537,26 +537,26 @@ class Project(RefreshMixin, SaveMixin, ObjectDeleteMixin, RepositoryMixin, RESTO ) -> Optional[bytes]: """Get the job artifacts archive from a specific tag or branch. - Args: - ref_name (str): Branch or tag name in repository. HEAD or SHA references - are not supported. - artifact_path (str): Path to a file inside the artifacts archive. - job (str): The name of the job. - job_token (str): Job token for multi-project pipeline triggers. - streamed (bool): If True the data will be processed by chunks of - `chunk_size` and each chunk is passed to `action` for - treatment - action (callable): Callable responsible of dealing with chunk of - data - chunk_size (int): Size of each chunk - **kwargs: Extra options to send to the server (e.g. sudo) - - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the artifacts could not be retrieved - - Returns: - str: The artifacts if `streamed` is False, None otherwise. + Args: + ref_name: Branch or tag name in repository. HEAD or SHA references + are not supported. + artifact_path: Path to a file inside the artifacts archive. + job: The name of the job. + job_token: Job token for multi-project pipeline triggers. + streamed: If True the data will be processed by chunks of + `chunk_size` and each chunk is passed to `action` for + treatment + action (callable): Callable responsible of dealing with chunk of + data + chunk_size: Size of each chunk + **kwargs: Extra options to send to the server (e.g. sudo) + + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the artifacts could not be retrieved + + Returns: + The artifacts if `streamed` is False, None otherwise. """ path = f"/projects/{self.get_id()}/jobs/artifacts/{ref_name}/download" result = self.manager.gitlab.http_get( @@ -580,24 +580,24 @@ class Project(RefreshMixin, SaveMixin, ObjectDeleteMixin, RepositoryMixin, RESTO ) -> Optional[bytes]: """Download a single artifact file from a specific tag or branch from within the job’s artifacts archive. - Args: - ref_name (str): Branch or tag name in repository. HEAD or SHA references are not supported. - artifact_path (str): Path to a file inside the artifacts archive. - job (str): The name of the job. - streamed (bool): If True the data will be processed by chunks of - `chunk_size` and each chunk is passed to `action` for - treatment - action (callable): Callable responsible of dealing with chunk of - data - chunk_size (int): Size of each chunk - **kwargs: Extra options to send to the server (e.g. sudo) - - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the artifacts could not be retrieved - - Returns: - str: The artifacts if `streamed` is False, None otherwise. + Args: + ref_name: Branch or tag name in repository. HEAD or SHA references are not supported. + artifact_path: Path to a file inside the artifacts archive. + job: The name of the job. + streamed: If True the data will be processed by chunks of + `chunk_size` and each chunk is passed to `action` for + treatment + action (callable): Callable responsible of dealing with chunk of + data + chunk_size: Size of each chunk + **kwargs: Extra options to send to the server (e.g. sudo) + + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the artifacts could not be retrieved + + Returns: + The artifacts if `streamed` is False, None otherwise. """ path = f"/projects/{self.get_id()}/jobs/artifacts/{ref_name}/raw/{artifact_path}?job={job}" @@ -788,22 +788,22 @@ class ProjectManager(CRUDMixin, RESTManager): ) -> Union[Dict[str, Any], requests.Response]: """Import a project from an archive file. - Args: - file: Data or file object containing the project - path (str): Name and path for the new project - namespace (str): The ID or path of the namespace that the project - will be imported to - overwrite (bool): If True overwrite an existing project with the - same path - override_params (dict): Set the specific settings for the project - **kwargs: Extra options to send to the server (e.g. sudo) - - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabListError: If the server failed to perform the request - - Returns: - dict: A representation of the import status. + Args: + file: Data or file object containing the project + path: Name and path for the new project + namespace: The ID or path of the namespace that the project + will be imported to + overwrite: If True overwrite an existing project with the + same path + override_params: Set the specific settings for the project + **kwargs: Extra options to send to the server (e.g. sudo) + + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabListError: If the server failed to perform the request + + Returns: + A representation of the import status. """ files = {"file": ("file.tar.gz", file, "application/octet-stream")} data = {"path": path, "overwrite": str(overwrite)} @@ -831,56 +831,56 @@ class ProjectManager(CRUDMixin, RESTManager): ) -> Union[Dict[str, Any], requests.Response]: """Import a project from BitBucket Server to Gitlab (schedule the import) - This method will return when an import operation has been safely queued, - or an error has occurred. After triggering an import, check the - ``import_status`` of the newly created project to detect when the import - operation has completed. - - .. note:: - This request may take longer than most other API requests. - So this method will specify a 60 second default timeout if none is specified. - A timeout can be specified via kwargs to override this functionality. - - Args: - bitbucket_server_url (str): Bitbucket Server URL - bitbucket_server_username (str): Bitbucket Server Username - personal_access_token (str): Bitbucket Server personal access - token/password - bitbucket_server_project (str): Bitbucket Project Key - bitbucket_server_repo (str): Bitbucket Repository Name - new_name (str): New repository name (Optional) - target_namespace (str): Namespace to import repository into. - Supports subgroups like /namespace/subgroup (Optional) - **kwargs: Extra options to send to the server (e.g. sudo) - - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabListError: If the server failed to perform the request - - Returns: - dict: A representation of the import status. - - Example: - - .. code-block:: python - - gl = gitlab.Gitlab_from_config() - print("Triggering import") - result = gl.projects.import_bitbucket_server( - bitbucket_server_url="https://some.server.url", - bitbucket_server_username="some_bitbucket_user", - personal_access_token="my_password_or_access_token", - bitbucket_server_project="my_project", - bitbucket_server_repo="my_repo", - new_name="gl_project_name", - target_namespace="gl_project_path" - ) - project = gl.projects.get(ret['id']) - print("Waiting for import to complete") - while project.import_status == u'started': - time.sleep(1.0) - project = gl.projects.get(project.id) - print("BitBucket import complete") + This method will return when an import operation has been safely queued, + or an error has occurred. After triggering an import, check the + ``import_status`` of the newly created project to detect when the import + operation has completed. + + .. note:: + This request may take longer than most other API requests. + So this method will specify a 60 second default timeout if none is specified. + A timeout can be specified via kwargs to override this functionality. + + Args: + bitbucket_server_url: Bitbucket Server URL + bitbucket_server_username: Bitbucket Server Username + personal_access_token: Bitbucket Server personal access + token/password + bitbucket_server_project: Bitbucket Project Key + bitbucket_server_repo: Bitbucket Repository Name + new_name: New repository name (Optional) + target_namespace: Namespace to import repository into. + Supports subgroups like /namespace/subgroup (Optional) + **kwargs: Extra options to send to the server (e.g. sudo) + + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabListError: If the server failed to perform the request + + Returns: + A representation of the import status. + + Example: + + .. code-block:: python + + gl = gitlab.Gitlab_from_config() + print("Triggering import") + result = gl.projects.import_bitbucket_server( + bitbucket_server_url="https://some.server.url", + bitbucket_server_username="some_bitbucket_user", + personal_access_token="my_password_or_access_token", + bitbucket_server_project="my_project", + bitbucket_server_repo="my_repo", + new_name="gl_project_name", + target_namespace="gl_project_path" + ) + project = gl.projects.get(ret['id']) + print("Waiting for import to complete") + while project.import_status == u'started': + time.sleep(1.0) + project = gl.projects.get(project.id) + print("BitBucket import complete") """ data = { @@ -919,45 +919,45 @@ class ProjectManager(CRUDMixin, RESTManager): ) -> Union[Dict[str, Any], requests.Response]: """Import a project from Github to Gitlab (schedule the import) - This method will return when an import operation has been safely queued, - or an error has occurred. After triggering an import, check the - ``import_status`` of the newly created project to detect when the import - operation has completed. - - .. note:: - This request may take longer than most other API requests. - So this method will specify a 60 second default timeout if none is specified. - A timeout can be specified via kwargs to override this functionality. - - Args: - personal_access_token (str): GitHub personal access token - repo_id (int): Github repository ID - target_namespace (str): Namespace to import repo into - new_name (str): New repo name (Optional) - **kwargs: Extra options to send to the server (e.g. sudo) - - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabListError: If the server failed to perform the request - - Returns: - dict: A representation of the import status. - - Example: - - .. code-block:: python - - gl = gitlab.Gitlab_from_config() - print("Triggering import") - result = gl.projects.import_github(ACCESS_TOKEN, - 123456, - "my-group/my-subgroup") - project = gl.projects.get(ret['id']) - print("Waiting for import to complete") - while project.import_status == u'started': - time.sleep(1.0) - project = gl.projects.get(project.id) - print("Github import complete") + This method will return when an import operation has been safely queued, + or an error has occurred. After triggering an import, check the + ``import_status`` of the newly created project to detect when the import + operation has completed. + + .. note:: + This request may take longer than most other API requests. + So this method will specify a 60 second default timeout if none is specified. + A timeout can be specified via kwargs to override this functionality. + + Args: + personal_access_token: GitHub personal access token + repo_id: Github repository ID + target_namespace: Namespace to import repo into + new_name: New repo name (Optional) + **kwargs: Extra options to send to the server (e.g. sudo) + + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabListError: If the server failed to perform the request + + Returns: + A representation of the import status. + + Example: + + .. code-block:: python + + gl = gitlab.Gitlab_from_config() + print("Triggering import") + result = gl.projects.import_github(ACCESS_TOKEN, + 123456, + "my-group/my-subgroup") + project = gl.projects.get(ret['id']) + print("Waiting for import to complete") + while project.import_status == u'started': + time.sleep(1.0) + project = gl.projects.get(project.id) + print("Github import complete") """ data = { @@ -1012,7 +1012,7 @@ class ProjectForkManager(CreateMixin, ListMixin, RESTManager): """Creates a new object. Args: - data (dict): Parameters to send to the server to create the + data: Parameters to send to the server to create the resource **kwargs: Extra options to send to the server (e.g. sudo) @@ -1021,7 +1021,7 @@ class ProjectForkManager(CreateMixin, ListMixin, RESTManager): GitlabCreateError: If the server cannot perform the request Returns: - RESTObject: A new instance of the managed object class build with + A new instance of the managed object class build with the data sent by the server """ if TYPE_CHECKING: diff --git a/gitlab/v4/objects/repositories.py b/gitlab/v4/objects/repositories.py index 18b0f8f..400f9d4 100644 --- a/gitlab/v4/objects/repositories.py +++ b/gitlab/v4/objects/repositories.py @@ -28,10 +28,10 @@ class RepositoryMixin(_RestObjectBase): """Update a project submodule Args: - submodule (str): Full path to the submodule - branch (str): Name of the branch to commit into - commit_sha (str): Full commit SHA to update the submodule to - commit_message (str): Commit message. If no message is provided, a + submodule: Full path to the submodule + branch: Name of the branch to commit into + commit_sha: Full commit SHA to update the submodule to + commit_message: Commit message. If no message is provided, a default one will be set (optional) Raises: @@ -53,23 +53,23 @@ class RepositoryMixin(_RestObjectBase): ) -> Union[gitlab.client.GitlabList, List[Dict[str, Any]]]: """Return a list of files in the repository. - Args: - path (str): Path of the top folder (/ by default) - ref (str): Reference to a commit or branch - recursive (bool): Whether to get the tree recursively - all (bool): If True, return all the items, without pagination - per_page (int): Number of items to retrieve per request - page (int): ID of the page to return (starts with page 1) - as_list (bool): If set to False and no pagination option is - defined, return a generator instead of a list - **kwargs: Extra options to send to the server (e.g. sudo) - - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the server failed to perform the request - - Returns: - list: The representation of the tree + Args: + path: Path of the top folder (/ by default) + ref: Reference to a commit or branch + recursive: Whether to get the tree recursively + all: If True, return all the items, without pagination + per_page: Number of items to retrieve per request + page: ID of the page to return (starts with page 1) + as_list: If set to False and no pagination option is + defined, return a generator instead of a list + **kwargs: Extra options to send to the server (e.g. sudo) + + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the server failed to perform the request + + Returns: + The representation of the tree """ gl_path = f"/projects/{self.get_id()}/repository/tree" query_data: Dict[str, Any] = {"recursive": recursive} @@ -95,7 +95,7 @@ class RepositoryMixin(_RestObjectBase): GitlabGetError: If the server failed to perform the request Returns: - dict: The blob content and metadata + The blob content and metadata """ path = f"/projects/{self.get_id()}/repository/blobs/{sha}" @@ -115,12 +115,12 @@ class RepositoryMixin(_RestObjectBase): Args: sha(str): ID of the blob - streamed (bool): If True the data will be processed by chunks of + streamed: If True the data will be processed by chunks of `chunk_size` and each chunk is passed to `action` for treatment action (callable): Callable responsible of dealing with chunk of data - chunk_size (int): Size of each chunk + chunk_size: Size of each chunk **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -128,7 +128,7 @@ class RepositoryMixin(_RestObjectBase): GitlabGetError: If the server failed to perform the request Returns: - str: The blob content if streamed is False, None otherwise + The blob content if streamed is False, None otherwise """ path = f"/projects/{self.get_id()}/repository/blobs/{sha}/raw" result = self.manager.gitlab.http_get( @@ -145,17 +145,17 @@ class RepositoryMixin(_RestObjectBase): ) -> Union[Dict[str, Any], requests.Response]: """Return a diff between two branches/commits. - Args: - from_(str): Source branch/SHA - to(str): Destination branch/SHA - **kwargs: Extra options to send to the server (e.g. sudo) + Args: + from_(str): Source branch/SHA + to(str): Destination branch/SHA + **kwargs: Extra options to send to the server (e.g. sudo) - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the server failed to perform the request + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the server failed to perform the request - Returns: - str: The diff + Returns: + The diff """ path = f"/projects/{self.get_id()}/repository/compare" query_data = {"from": from_, "to": to} @@ -168,20 +168,20 @@ class RepositoryMixin(_RestObjectBase): ) -> Union[gitlab.client.GitlabList, List[Dict[str, Any]]]: """Return a list of contributors for the project. - Args: - all (bool): If True, return all the items, without pagination - per_page (int): Number of items to retrieve per request - page (int): ID of the page to return (starts with page 1) - as_list (bool): If set to False and no pagination option is - defined, return a generator instead of a list - **kwargs: Extra options to send to the server (e.g. sudo) + Args: + all: If True, return all the items, without pagination + per_page: Number of items to retrieve per request + page: ID of the page to return (starts with page 1) + as_list: If set to False and no pagination option is + defined, return a generator instead of a list + **kwargs: Extra options to send to the server (e.g. sudo) - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the server failed to perform the request + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the server failed to perform the request - Returns: - list: The contributors + Returns: + The contributors """ path = f"/projects/{self.get_id()}/repository/contributors" return self.manager.gitlab.http_list(path, **kwargs) @@ -199,13 +199,13 @@ class RepositoryMixin(_RestObjectBase): """Return a tarball of the repository. Args: - sha (str): ID of the commit (default branch by default) - streamed (bool): If True the data will be processed by chunks of + sha: ID of the commit (default branch by default) + streamed: If True the data will be processed by chunks of `chunk_size` and each chunk is passed to `action` for treatment action (callable): Callable responsible of dealing with chunk of data - chunk_size (int): Size of each chunk + chunk_size: Size of each chunk **kwargs: Extra options to send to the server (e.g. sudo) Raises: @@ -213,7 +213,7 @@ class RepositoryMixin(_RestObjectBase): GitlabListError: If the server failed to perform the request Returns: - bytes: The binary data of the archive + The binary data of the archive """ path = f"/projects/{self.get_id()}/repository/archive" query_data = {} diff --git a/gitlab/v4/objects/runners.py b/gitlab/v4/objects/runners.py index 7b59b8a..7c900e9 100644 --- a/gitlab/v4/objects/runners.py +++ b/gitlab/v4/objects/runners.py @@ -76,12 +76,12 @@ class RunnerManager(CRUDMixin, RESTManager): """List all the runners. Args: - scope (str): The scope of runners to show, one of: specific, + scope: The scope of runners to show, one of: specific, shared, active, paused, online - all (bool): If True, return all the items, without pagination - per_page (int): Number of items to retrieve per request - page (int): ID of the page to return (starts with page 1) - as_list (bool): If set to False and no pagination option is + all: If True, return all the items, without pagination + per_page: Number of items to retrieve per request + page: ID of the page to return (starts with page 1) + as_list: If set to False and no pagination option is defined, return a generator instead of a list **kwargs: Extra options to send to the server (e.g. sudo) @@ -90,7 +90,7 @@ class RunnerManager(CRUDMixin, RESTManager): GitlabListError: If the server failed to perform the request Returns: - list(Runner): a list of runners matching the scope. + a list of runners matching the scope. """ path = "/runners/all" query_data = {} @@ -105,7 +105,7 @@ class RunnerManager(CRUDMixin, RESTManager): """Validates authentication credentials for a registered Runner. Args: - token (str): The runner's authentication token + token: The runner's authentication token **kwargs: Extra options to send to the server (e.g. sudo) Raises: diff --git a/gitlab/v4/objects/services.py b/gitlab/v4/objects/services.py index a62fdf0..93e1fae 100644 --- a/gitlab/v4/objects/services.py +++ b/gitlab/v4/objects/services.py @@ -262,13 +262,13 @@ class ProjectServiceManager(GetMixin, UpdateMixin, DeleteMixin, ListMixin, RESTM Args: id (int or str): ID of the object to retrieve - lazy (bool): If True, don't request the server, but create a + lazy: If True, don't request the server, but create a shallow object giving access to the managers. This is useful if you want to avoid useless calls to the API. **kwargs: Extra options to send to the server (e.g. sudo) Returns: - object: The generated RESTObject. + The generated RESTObject. Raises: GitlabAuthenticationError: If authentication is not correct @@ -292,7 +292,7 @@ class ProjectServiceManager(GetMixin, UpdateMixin, DeleteMixin, ListMixin, RESTM **kwargs: Extra options to send to the server (e.g. sudo) Returns: - dict: The new object data (*not* a RESTObject) + The new object data (*not* a RESTObject) Raises: GitlabAuthenticationError: If authentication is not correct @@ -307,7 +307,7 @@ class ProjectServiceManager(GetMixin, UpdateMixin, DeleteMixin, ListMixin, RESTM def available(self, **kwargs: Any) -> List[str]: """List the services known by python-gitlab. - Returns: - list (str): The list of service code names. + Returns: + The list of service code names. """ return list(self._service_attrs.keys()) diff --git a/gitlab/v4/objects/settings.py b/gitlab/v4/objects/settings.py index 2e8ac79..0fb7f8a 100644 --- a/gitlab/v4/objects/settings.py +++ b/gitlab/v4/objects/settings.py @@ -103,7 +103,7 @@ class ApplicationSettingsManager(GetWithoutIdMixin, UpdateMixin, RESTManager): **kwargs: Extra options to send to the server (e.g. sudo) Returns: - dict: The new object data (*not* a RESTObject) + The new object data (*not* a RESTObject) Raises: GitlabAuthenticationError: If authentication is not correct diff --git a/gitlab/v4/objects/sidekiq.py b/gitlab/v4/objects/sidekiq.py index 9e00fe4..b42d1c6 100644 --- a/gitlab/v4/objects/sidekiq.py +++ b/gitlab/v4/objects/sidekiq.py @@ -23,15 +23,15 @@ class SidekiqManager(RESTManager): def queue_metrics(self, **kwargs: Any) -> Union[Dict[str, Any], requests.Response]: """Return the registered queues information. - Args: - **kwargs: Extra options to send to the server (e.g. sudo) + Args: + **kwargs: Extra options to send to the server (e.g. sudo) - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the information couldn't be retrieved + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the information couldn't be retrieved - Returns: - dict: Information about the Sidekiq queues + Returns: + Information about the Sidekiq queues """ return self.gitlab.http_get("/sidekiq/queue_metrics", **kwargs) @@ -42,15 +42,15 @@ class SidekiqManager(RESTManager): ) -> Union[Dict[str, Any], requests.Response]: """Return the registered sidekiq workers. - Args: - **kwargs: Extra options to send to the server (e.g. sudo) + Args: + **kwargs: Extra options to send to the server (e.g. sudo) - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the information couldn't be retrieved + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the information couldn't be retrieved - Returns: - dict: Information about the register Sidekiq worker + Returns: + Information about the register Sidekiq worker """ return self.gitlab.http_get("/sidekiq/process_metrics", **kwargs) @@ -59,15 +59,15 @@ class SidekiqManager(RESTManager): def job_stats(self, **kwargs: Any) -> Union[Dict[str, Any], requests.Response]: """Return statistics about the jobs performed. - Args: - **kwargs: Extra options to send to the server (e.g. sudo) + Args: + **kwargs: Extra options to send to the server (e.g. sudo) - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the information couldn't be retrieved + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the information couldn't be retrieved - Returns: - dict: Statistics about the Sidekiq jobs performed + Returns: + Statistics about the Sidekiq jobs performed """ return self.gitlab.http_get("/sidekiq/job_stats", **kwargs) @@ -78,14 +78,14 @@ class SidekiqManager(RESTManager): ) -> Union[Dict[str, Any], requests.Response]: """Return all available metrics and statistics. - Args: - **kwargs: Extra options to send to the server (e.g. sudo) + Args: + **kwargs: Extra options to send to the server (e.g. sudo) - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the information couldn't be retrieved + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the information couldn't be retrieved - Returns: - dict: All available Sidekiq metrics and statistics + Returns: + All available Sidekiq metrics and statistics """ return self.gitlab.http_get("/sidekiq/compound_metrics", **kwargs) diff --git a/gitlab/v4/objects/snippets.py b/gitlab/v4/objects/snippets.py index 96b80c4..ca174a1 100644 --- a/gitlab/v4/objects/snippets.py +++ b/gitlab/v4/objects/snippets.py @@ -34,21 +34,21 @@ class Snippet(UserAgentDetailMixin, SaveMixin, ObjectDeleteMixin, RESTObject): ) -> Optional[bytes]: """Return the content of a snippet. - Args: - streamed (bool): If True the data will be processed by chunks of - `chunk_size` and each chunk is passed to `action` for - treatment. - action (callable): Callable responsible of dealing with chunk of - data - chunk_size (int): Size of each chunk - **kwargs: Extra options to send to the server (e.g. sudo) - - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the content could not be retrieved - - Returns: - str: The snippet content + Args: + streamed: If True the data will be processed by chunks of + `chunk_size` and each chunk is passed to `action` for + treatment. + action (callable): Callable responsible of dealing with chunk of + data + chunk_size: Size of each chunk + **kwargs: Extra options to send to the server (e.g. sudo) + + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the content could not be retrieved + + Returns: + The snippet content """ path = f"/snippets/{self.get_id()}/raw" result = self.manager.gitlab.http_get( @@ -74,14 +74,14 @@ class SnippetManager(CRUDMixin, RESTManager): """List all the public snippets. Args: - all (bool): If True the returned object will be a list + all: If True the returned object will be a list **kwargs: Extra options to send to the server (e.g. sudo) Raises: GitlabListError: If the list could not be retrieved Returns: - RESTObjectList: A generator for the snippets list + A generator for the snippets list """ return self.list(path="/snippets/public", **kwargs) @@ -108,21 +108,21 @@ class ProjectSnippet(UserAgentDetailMixin, SaveMixin, ObjectDeleteMixin, RESTObj ) -> Optional[bytes]: """Return the content of a snippet. - Args: - streamed (bool): If True the data will be processed by chunks of - `chunk_size` and each chunk is passed to `action` for - treatment. - action (callable): Callable responsible of dealing with chunk of - data - chunk_size (int): Size of each chunk - **kwargs: Extra options to send to the server (e.g. sudo) - - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabGetError: If the content could not be retrieved - - Returns: - str: The snippet content + Args: + streamed: If True the data will be processed by chunks of + `chunk_size` and each chunk is passed to `action` for + treatment. + action (callable): Callable responsible of dealing with chunk of + data + chunk_size: Size of each chunk + **kwargs: Extra options to send to the server (e.g. sudo) + + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabGetError: If the content could not be retrieved + + Returns: + The snippet content """ path = f"{self.manager.path}/{self.get_id()}/raw" result = self.manager.gitlab.http_get( diff --git a/gitlab/v4/objects/todos.py b/gitlab/v4/objects/todos.py index 9f8c52d..e441eff 100644 --- a/gitlab/v4/objects/todos.py +++ b/gitlab/v4/objects/todos.py @@ -53,6 +53,6 @@ class TodoManager(ListMixin, DeleteMixin, RESTManager): GitlabTodoError: If the server failed to perform the request Returns: - int: The number of todos marked done + The number of todos marked done """ self.gitlab.http_post("/todos/mark_as_done", **kwargs) diff --git a/gitlab/v4/objects/users.py b/gitlab/v4/objects/users.py index 8649cba..fac448a 100644 --- a/gitlab/v4/objects/users.py +++ b/gitlab/v4/objects/users.py @@ -167,7 +167,7 @@ class User(SaveMixin, ObjectDeleteMixin, RESTObject): GitlabBlockError: If the user could not be blocked Returns: - bool: Whether the user status has been changed + Whether the user status has been changed """ path = f"/users/{self.id}/block" server_data = self.manager.gitlab.http_post(path, **kwargs) @@ -188,7 +188,7 @@ class User(SaveMixin, ObjectDeleteMixin, RESTObject): GitlabFollowError: If the user could not be followed Returns: - dict: The new object data (*not* a RESTObject) + The new object data (*not* a RESTObject) """ path = f"/users/{self.id}/follow" return self.manager.gitlab.http_post(path, **kwargs) @@ -206,7 +206,7 @@ class User(SaveMixin, ObjectDeleteMixin, RESTObject): GitlabUnfollowError: If the user could not be followed Returns: - dict: The new object data (*not* a RESTObject) + The new object data (*not* a RESTObject) """ path = f"/users/{self.id}/unfollow" return self.manager.gitlab.http_post(path, **kwargs) @@ -224,7 +224,7 @@ class User(SaveMixin, ObjectDeleteMixin, RESTObject): GitlabUnblockError: If the user could not be unblocked Returns: - bool: Whether the user status has been changed + Whether the user status has been changed """ path = f"/users/{self.id}/unblock" server_data = self.manager.gitlab.http_post(path, **kwargs) @@ -245,7 +245,7 @@ class User(SaveMixin, ObjectDeleteMixin, RESTObject): GitlabDeactivateError: If the user could not be deactivated Returns: - bool: Whether the user status has been changed + Whether the user status has been changed """ path = f"/users/{self.id}/deactivate" server_data = self.manager.gitlab.http_post(path, **kwargs) @@ -266,7 +266,7 @@ class User(SaveMixin, ObjectDeleteMixin, RESTObject): GitlabActivateError: If the user could not be activated Returns: - bool: Whether the user status has been changed + Whether the user status has been changed """ path = f"/users/{self.id}/activate" server_data = self.manager.gitlab.http_post(path, **kwargs) @@ -520,15 +520,15 @@ class UserProjectManager(ListMixin, CreateMixin, RESTManager): """Retrieve a list of objects. Args: - all (bool): If True, return all the items, without pagination - per_page (int): Number of items to retrieve per request - page (int): ID of the page to return (starts with page 1) - as_list (bool): If set to False and no pagination option is + all: If True, return all the items, without pagination + per_page: Number of items to retrieve per request + page: ID of the page to return (starts with page 1) + as_list: If set to False and no pagination option is defined, return a generator instead of a list **kwargs: Extra options to send to the server (e.g. sudo) Returns: - list: The list of objects, or a generator if `as_list` is False + The list of objects, or a generator if `as_list` is False Raises: GitlabAuthenticationError: If authentication is not correct |