Merge branch 'main' into typos

9 files changed, 237 insertions, 52 deletions

diff --git a/docs/api-objects.rst b/docs/api-objects.rst
index cccf1c6..8c7bb19 100644
--- a/docs/api-objects.rst
+++ b/docs/api-objects.rst
@@ -11,6 +11,7 @@ API examples
    gl_objects/emojis
    gl_objects/badges
    gl_objects/branches
+   gl_objects/bulk_imports
    gl_objects/messages
    gl_objects/ci_lint
    gl_objects/commits
@@ -51,6 +52,7 @@ API examples
    gl_objects/remote_mirrors
    gl_objects/repositories
    gl_objects/repository_tags
+   gl_objects/resource_groups
    gl_objects/search
    gl_objects/secure_files
    gl_objects/settings
diff --git a/docs/api-usage-advanced.rst b/docs/api-usage-advanced.rst
index 2b069b8..dcc27ca 100644
--- a/docs/api-usage-advanced.rst
+++ b/docs/api-usage-advanced.rst
@@ -123,9 +123,16 @@ GitLab server can sometimes return a transient HTTP error.
 python-gitlab can automatically retry in such case, when
 ``retry_transient_errors`` argument is set to ``True``.  When enabled,
 HTTP error codes 500 (Internal Server Error), 502 (502 Bad Gateway),
-503 (Service Unavailable), and 504 (Gateway Timeout) are retried. It will retry until reaching
-the ``max_retries`` value. By default, ``retry_transient_errors`` is set to ``False`` and an exception
-is raised for these errors.
+503 (Service Unavailable), 504 (Gateway Timeout), and Cloudflare
+errors (520-530) are retried.
+
+Additionally, HTTP error code 409 (Conflict) is retried if the reason
+is a
+`Resource lock <https://gitlab.com/gitlab-org/gitlab/-/blob/443c12cf3b238385db728f03b2cdbb4f17c70292/lib/api/api.rb#L111>`__.
+
+It will retry until reaching the ``max_retries``
+value. By default, ``retry_transient_errors`` is set to ``False`` and an
+exception is raised for these errors.
 
 .. code-block:: python
 
diff --git a/docs/api-usage.rst b/docs/api-usage.rst
index 444064b..2e7f5c6 100644
--- a/docs/api-usage.rst
+++ b/docs/api-usage.rst
@@ -171,6 +171,8 @@ conflict with python or python-gitlab when using them as kwargs:
 
    gl.user_activities.list(query_parameters={'from': '2019-01-01'}, iterator=True)  # OK
 
+.. _objects:
+
 Gitlab Objects
 ==============
 
@@ -220,21 +222,16 @@ the value on the object is accepted:
       issue.my_super_awesome_feature_flag = "random_value"
       issue.save()
 
+As a dictionary
+---------------
+
 You can get a dictionary representation copy of the Gitlab Object. Modifications made to
 the dictionary will have no impact on the GitLab Object.
 
- * ``asdict()`` method. Returns a dictionary representation of the Gitlab object.
- * ``attributes`` property. Returns a dictionary representation of the Gitlab
+* ``asdict()`` method. Returns a dictionary representation of the Gitlab object.
+* ``attributes`` property. Returns a dictionary representation of the Gitlab
    object. Also returns any relevant parent object attributes.
 
-.. note::
-
-   ``attributes`` returns the parent object attributes that are defined in
-   ``object._from_parent_attrs``. What this can mean is that for example a ``ProjectIssue``
-   object will have a ``project_id`` key in the dictionary returned from ``attributes`` but
-   ``asdict()`` will not.
-
-
 .. code-block:: python
 
    project = gl.projects.get(1)
@@ -244,6 +241,22 @@ the dictionary will have no impact on the GitLab Object.
    issue = project.issues.get(1)
    attribute_dict = issue.attributes
 
+   # The following will return the same value
+   title = issue.title
+   title = issue.attributes["title"]
+
+.. hint::
+
+   This can be used to access attributes that clash with python-gitlab's own methods or managers.
+   Note that:
+
+   ``attributes`` returns the parent object attributes that are defined in
+   ``object._from_parent_attrs``. For example, a ``ProjectIssue`` object will have a
+   ``project_id`` key in the dictionary returned from ``attributes`` but ``asdict()`` will not.
+
+As JSON
+-------
+
 You can get a JSON string represenation of the Gitlab Object. For example:
 
 .. code-block:: python
@@ -380,6 +393,9 @@ The generator exposes extra listing information as received from the server:
    Prior to python-gitlab 3.6.0 the argument ``as_list`` was used instead of
    ``iterator``.  ``as_list=False`` is the equivalent of ``iterator=True``.
 
+.. note::
+   If ``page`` and ``iterator=True`` are used together, the latter is ignored.
+
 Sudo
 ====
 
diff --git a/docs/faq.rst b/docs/faq.rst
index 3f2ee6c..cd4734a 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -2,52 +2,79 @@
 FAQ
 ###
 
-I cannot edit the merge request / issue I've just retrieved
-    It is likely that you used a ``MergeRequest``, ``GroupMergeRequest``,
-    ``Issue`` or ``GroupIssue`` object. These objects cannot be edited. But you
-    can create a new ``ProjectMergeRequest`` or ``ProjectIssue`` object to
-    apply changes. For example::
+General
+-------
 
-        issue = gl.issues.list()[0]
-        project = gl.projects.get(issue.project_id, lazy=True)
-        editable_issue = project.issues.get(issue.iid, lazy=True)
-        # you can now edit the object
+I cannot edit the merge request / issue I've just retrieved.
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-    See the :ref:`merge requests example <merge_requests_examples>` and the
-    :ref:`issues examples <issues_examples>`.
+It is likely that you used a ``MergeRequest``, ``GroupMergeRequest``,
+``Issue`` or ``GroupIssue`` object. These objects cannot be edited. But you
+can create a new ``ProjectMergeRequest`` or ``ProjectIssue`` object to
+apply changes. For example::
 
-.. _attribute_error_list:
+    issue = gl.issues.list()[0]
+    project = gl.projects.get(issue.project_id, lazy=True)
+    editable_issue = project.issues.get(issue.iid, lazy=True)
+    # you can now edit the object
+
+See the :ref:`merge requests example <merge_requests_examples>` and the
+:ref:`issues examples <issues_examples>`.
 
-I get an ``AttributeError`` when accessing attributes of an object retrieved via a ``list()`` call.
-    Fetching a list of objects, doesn’t always include all attributes in the
-    objects. To retrieve an object with all attributes use a ``get()`` call.
+How can I clone the repository of a project?
+""""""""""""""""""""""""""""""""""""""""""""
 
-    Example with projects::
+python-gitlab does not provide an API to clone a project. You have to use a
+git library or call the ``git`` command.
 
-        for projects in gl.projects.list():
-            # Retrieve project object with all attributes
-            project = gl.projects.get(project.id)
+The git URI is exposed in the ``ssh_url_to_repo`` attribute of ``Project``
+objects.
 
-How can I clone the repository of a project?
-    python-gitlab doesn't provide an API to clone a project. You have to use a
-    git library or call the ``git`` command.
+Example::
+
+    import subprocess
+
+    project = gl.projects.create(data)  # or gl.projects.get(project_id)
+    print(project.attributes)  # displays all the attributes
+    git_url = project.ssh_url_to_repo
+    subprocess.call(['git', 'clone', git_url])
+
+Not all items are returned from the API
+"""""""""""""""""""""""""""""""""""""""
+
+If you've passed ``all=True`` (or ``--all`` via the CLI) to the API and still cannot see all items returned,
+use ``get_all=True`` (or ``--get-all`` via the CLI) instead. See :ref:`pagination` for more details.
+
+Common errors
+-------------
+
+.. _attribute_error_list:
+
+``AttributeError`` when accessing object attributes retrieved via ``list()``
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Fetching a list of objects does not always include all attributes in the objects.
+To retrieve an object with all attributes, use a ``get()`` call.
+
+Example with projects::
 
-    The git URI is exposed in the ``ssh_url_to_repo`` attribute of ``Project``
-    objects.
+    for projects in gl.projects.list():
+        # Retrieve project object with all attributes
+        project = gl.projects.get(project.id)
 
-    Example::
+``AttributeError`` when accessing attributes after ``save()`` or ``refresh()``
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-        import subprocess
+You are most likely trying to access an attribute that was not returned
+by the server on the second request. Please look at the documentation in
+:ref:`object_attributes` to see how to avoid this.
 
-        project = gl.projects.create(data)  # or gl.projects.get(project_id)
-        print(project.attributes)  # displays all the attributes
-        git_url = project.ssh_url_to_repo
-        subprocess.call(['git', 'clone', git_url])
+``TypeError`` when accessing object attributes
+""""""""""""""""""""""""""""""""""""""""""""""
 
-I get an ``AttributeError`` when accessing attributes after ``save()`` or ``refresh()``.
-    You are most likely trying to access an attribute that was not returned
-    by the server on the second request. Please look at the documentation in
-    :ref:`object_attributes` to see how to avoid this.
+When you encounter errors such as ``object is not iterable`` or ``object is not subscriptable``
+when trying to access object attributes returned from the server, you are most likely trying to
+access an attribute that is shadowed by python-gitlab's own methods or managers.
 
-I passed ``all=True`` (or ``--all`` via the CLI) to the API and I still cannot see all items returned.
-    Use ``get_all=True`` (or ``--get-all`` via the CLI). See :ref:`pagination` for more details.
+You can use the object's ``attributes`` dictionary to access it directly instead.
+See the :ref:`objects` section for more details on how attributes are exposed.
diff --git a/docs/gl_objects/bulk_imports.rst b/docs/gl_objects/bulk_imports.rst
new file mode 100644
index 0000000..fa386bd
--- /dev/null
+++ b/docs/gl_objects/bulk_imports.rst
@@ -0,0 +1,82 @@
+#########################
+Migrations (Bulk Imports)
+#########################
+
+References
+----------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.BulkImport`
+  + :class:`gitlab.v4.objects.BulkImportManager`
+  + :attr:`gitlab.Gitlab.bulk_imports`
+  + :class:`gitlab.v4.objects.BulkImportAllEntity`
+  + :class:`gitlab.v4.objects.BulkImportAllEntityManager`
+  + :attr:`gitlab.Gitlab.bulk_import_entities`
+  + :class:`gitlab.v4.objects.BulkImportEntity`
+  + :class:`gitlab.v4.objects.BulkImportEntityManager`
+  + :attr:`gitlab.v4.objects.BulkImport.entities`
+
+* GitLab API: https://docs.gitlab.com/ee/api/bulk_imports.html
+
+Examples
+--------
+
+.. note::
+
+    Like the project/group imports and exports, this is an asynchronous operation and you
+    will need to refresh the state from the server to get an accurate migration status. See
+    :ref:`project_import_export` in the import/export section for more details and examples.
+
+Start a bulk import/migration of a group and wait for completion::
+
+    # Create the migration
+    configuration = {
+        "url": "https://gitlab.example.com",
+        "access_token": private_token,
+    }
+    entity = {
+        "source_full_path": "source_group",
+        "source_type": "group_entity",
+        "destination_slug": "imported-group",
+        "destination_namespace": "imported-namespace",
+    }
+    migration = gl.bulk_imports.create(
+        {
+            "configuration": configuration,
+            "entities": [entity],
+        }
+    )
+
+    # Wait for the 'finished' status
+    while migration.status != "finished":
+        time.sleep(1)
+        migration.refresh()
+
+List all migrations::
+
+    gl.bulk_imports.list()
+
+List the entities of all migrations::
+
+    gl.bulk_import_entities.list()
+
+Get a single migration by ID::
+
+    migration = gl.bulk_imports.get(123)
+
+List the entities of a single migration::
+
+    entities = migration.entities.list()
+
+Get a single entity of a migration by ID::
+
+    entity = migration.entities.get(123)
+
+Refresh the state of a migration or entity from the server::
+
+    migration.refresh()
+    entity.refresh()
+
+    print(migration.status)
+    print(entity.status)
diff --git a/docs/gl_objects/groups.rst b/docs/gl_objects/groups.rst
index fafa40a..37977da 100644
--- a/docs/gl_objects/groups.rst
+++ b/docs/gl_objects/groups.rst
@@ -88,6 +88,11 @@ Remove a group::
     # or
     group.delete()
 
+Restore a Group marked for deletion (Premium only):::
+    
+    group.restore()
+
+
 Share/unshare the group with a group::
 
     group.share(group2.id, gitlab.const.AccessLevel.DEVELOPER)
diff --git a/docs/gl_objects/pipelines_and_jobs.rst b/docs/gl_objects/pipelines_and_jobs.rst
index fd293a9..1c33682 100644
--- a/docs/gl_objects/pipelines_and_jobs.rst
+++ b/docs/gl_objects/pipelines_and_jobs.rst
@@ -112,8 +112,8 @@ objects to get the associated project::
 
 Reference: https://docs.gitlab.com/ee/ci/triggers/#trigger-token
 
-Pipeline schedule
-=================
+Pipeline schedules
+==================
 
 You can schedule pipeline runs using a cron-like syntax. Variables can be
 associated with the scheduled pipelines.
@@ -128,7 +128,10 @@ Reference
   + :attr:`gitlab.v4.objects.Project.pipelineschedules`
   + :class:`gitlab.v4.objects.ProjectPipelineScheduleVariable`
   + :class:`gitlab.v4.objects.ProjectPipelineScheduleVariableManager`
-  + :attr:`gitlab.v4.objects.Project.pipelineschedules`
+  + :attr:`gitlab.v4.objects.ProjectPipelineSchedule.variables`
+  + :class:`gitlab.v4.objects.ProjectPipelineSchedulePipeline`
+  + :class:`gitlab.v4.objects.ProjectPipelineSchedulePipelineManager`
+  + :attr:`gitlab.v4.objects.ProjectPipelineSchedule.pipelines`
 
 * GitLab API: https://docs.gitlab.com/ce/api/pipeline_schedules.html
 
@@ -188,6 +191,9 @@ Delete a schedule variable::
 
     var.delete()
 
+List all pipelines triggered by a pipeline schedule::
+
+    pipelines = sched.pipelines.list()
 
 Jobs
 ====
diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst
index 7fc0ab9..b80df0d 100644
--- a/docs/gl_objects/projects.rst
+++ b/docs/gl_objects/projects.rst
@@ -275,6 +275,8 @@ Reference
 
 * GitLab API: https://docs.gitlab.com/ce/api/project_import_export.html
 
+.. _project_import_export:
+
 Examples
 --------
 
diff --git a/docs/gl_objects/resource_groups.rst b/docs/gl_objects/resource_groups.rst
new file mode 100644
index 0000000..3fa0f92
--- /dev/null
+++ b/docs/gl_objects/resource_groups.rst
@@ -0,0 +1,38 @@
+###############
+Resource Groups
+###############
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectResourceGroup`
+  + :class:`gitlab.v4.objects.ProjectResourceGroupManager`
+  + :attr:`gitlab.v4.objects.Project.resource_groups`
+  + :class:`gitlab.v4.objects.ProjectResourceGroupUpcomingJob`
+  + :class:`gitlab.v4.objects.ProjectResourceGroupUpcomingJobManager`
+  + :attr:`gitlab.v4.objects.ProjectResourceGroup.upcoming_jobs`
+
+* Gitlab API: https://docs.gitlab.com/ee/api/resource_groups.html
+
+Examples
+--------
+
+List resource groups for a project::
+
+    project = gl.projects.get(project_id, lazy=True)
+    resource_group = project.resource_groups.list()
+
+Get a single resource group::
+
+    resource_group = project.resource_groups.get("production")
+
+Edit a resource group::
+
+    resource_group.process_mode = "oldest_first"
+    resource_group.save()
+
+List upcoming jobs for a resource group::
+
+    upcoming_jobs = resource_group.upcoming_jobs.list()