diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 5d9645ac..98e7acf6 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -780,6 +780,41 @@ mutables are lists and dictionaries: All lists have mutating methods, like :py:meth:`list.append` or :py:meth:`list.pop`, and can be modified in place. The same goes for dictionaries. + +.. note:: + + Be careful when assigning mutable objects to new variables. + Assigning a list to another variable does not create a copy; + both variables refer to the same list. Modifying the list + through either variable will affect the shared object. + + For example: + + .. code-block:: python + + class Data: + mylist = [1, 2, 3, 4] + + def test_function(): + local_list = Data.mylist + local_list += [5] + + test_function() + print(Data.mylist) # [1, 2, 3, 4, 5] + + To avoid modifying the original list, create a copy before + making changes: + + .. code-block:: python + + def test_function(): + local_list = Data.mylist.copy() + local_list += [5] + + test_function() + print(Data.mylist) # [1, 2, 3, 4] + + Immutable types provide no method for changing their content. For instance, the variable x set to the integer 6 has no "increment" method. If you want to compute x + 1, you have to create another integer and give it a name. @@ -792,7 +827,6 @@ compute x + 1, you have to create another integer and give it a name. x = 6 x = x + 1 # The new x is another object - One consequence of this difference in behavior is that mutable types are not "stable", and therefore cannot be used as dictionary keys.