diff options
Diffstat (limited to 'gitlab/v4/objects/projects.py')
| -rw-r--r-- | gitlab/v4/objects/projects.py | 380 |
1 files changed, 190 insertions, 190 deletions
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: |