From 38f65e8e9994f58bdc74fe2e0e9b971fc3edf723 Mon Sep 17 00:00:00 2001 From: Nejc Habjan Date: Sun, 2 May 2021 13:12:11 +0200 Subject: [PATCH] docs(api): add behavior in local attributes when updating objects --- docs/api-usage.rst | 20 ++++++++++++++++++++ docs/faq.rst | 5 +++++ 2 files changed, 25 insertions(+) diff --git a/docs/api-usage.rst b/docs/api-usage.rst index 2a40cfa19..e911664b7 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 fe71198ac..0f914edc4 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.