docs(api): add behavior in local attributes when updating objects

2 files changed, 25 insertions, 0 deletions

diff --git a/docs/api-usage.rst b/docs/api-usage.rst
index 2a40cfa..e911664 100644
--- a/docs/api-usage.rst
+++ b/docs/api-usage.rst
@@ -407,3 +407,23 @@ parameter to that API invocation:
    gl = gitlab.gitlab(url, token, api_version=4)
    gl.projects.import_github(ACCESS_TOKEN, 123456, "root", timeout=120.0)
 
+.. _object_attributes:
+
+Attributes in updated objects
+=============================
+
+When methods manipulate an existing object, such as with ``refresh()`` and ``save()``,
+the object will only have attributes that were returned by the server. In some cases,
+such as when the initial request fetches attributes that are needed later for additional
+processing, this may not be desired:
+
+.. code-block:: python
+
+   project = gl.projects.get(1, statistics=True)
+   project.statistics
+
+   project.refresh()
+   project.statistics # AttributeError
+
+To avoid this, either copy the object/attributes before calling ``refresh()``/``save()``
+or subsequently perform another ``get()`` call as needed, to fetch the attributes you want.
diff --git a/docs/faq.rst b/docs/faq.rst
index fe71198..0f914ed 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -31,3 +31,8 @@ How can I clone the repository of a project?
         print(project.attributes)  # displays all the attributes
         git_url = project.ssh_url_to_repo
         subprocess.call(['git', 'clone', git_url])
+
+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.