🎨 Rearrange namespaces

Author: veit

docs/functions/variables.rst

@@ -1,6 +1,8 @@
 Variables
 =========
 
+.. _local_variables:
+
 Local variables
 ---------------
 
@@ -38,6 +40,8 @@ such as ``f = 1``, are local to the function:
        n
    NameError: name 'n' is not defined
 
+.. _global_variables:
+
 Global variables
 ----------------
 
@@ -75,6 +79,8 @@ true for ``y``; the local variable ``y`` inside ``my_func`` initially refers to
 the same value as the variable ``y`` outside ``my_func``, but the assignment
 causes ``y`` to refer to a new value that is local to the ``my_func`` function.
 
+.. _nonlocal_variables:
+
 Non-local variables
 -------------------
 

docs/oop/form_ns.py

@@ -63,6 +63,7 @@ def circumferences(cls):
         return csum
 
     def namespaces(self):
+        print("Builtin namespace:", dir(__builtins__))
         print("Global namespace:", list(globals().keys()))
         print("Superclass namespace:", dir(Form))
         print("Class namespace:", dir(Circle))

docs/oop/index.rst

@@ -51,7 +51,7 @@ be the beginning of a simple shapes module for a drawing program.
    coherent
    private
    property
-   namespaces
    types
+   namespaces
    dataclasses
    design/index

docs/oop/namespaces.rst

@@ -1,6 +1,20 @@
 Namespaces
 ==========
 
+A namespace is a collection of currently defined symbolic names and information
+about an object. You can think of a namespace as a dictionary in which the keys
+are the object names and the values are the objects themselves. Each of these
+key-value pairs assigns a name to the corresponding object.
+
+    Namespaces are one honking great idea – let’s do more of those!
+
+– `The Zen of Python <https://peps.python.org/pep-0020/>`_, by Tim Peters
+
+Python now uses namespaces extensively. We have already learnt about some of
+them in :doc:`function variables <../functions/variables>`: :ref:`local
+<local_variables>`, :ref:`global <global_variables>` and :ref:`non-local
+variables <nonlocal_variables>`.
+
 If you are in the method of a class, you have direct access
 
 #. to the **local namespace** with the parameters and variables declared in this
@@ -21,14 +35,15 @@ You can get an overview of the methods that are available in a namespace with
 .. literalinclude:: form_ns.py
     :language: python
     :linenos:
-    :lines: 65-70
+    :lines: 65-71
     :lineno-start: 65
 
 .. code-block:: pycon
 
     >>> import form_ns
     >>> c1 = form_ns.Circle()
     >>> c1.namespaces()
+    ['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException', 'BaseExceptionGroup', 'BlockingIOError', 'BrokenPipeError', 'BufferError', 'BytesWarning', 'ChildProcessError', 'ConnectionAbortedError', 'ConnectionError', 'ConnectionRefusedError', 'ConnectionResetError', 'DeprecationWarning', 'EOFError', 'Ellipsis', 'EncodingWarning', 'EnvironmentError', 'Exception', 'ExceptionGroup', 'False', 'FileExistsError', 'FileNotFoundError', 'FloatingPointError', 'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError', 'ImportWarning', 'IndentationError', 'IndexError', 'InterruptedError', 'IsADirectoryError', 'KeyError', 'KeyboardInterrupt', 'LookupError', 'MemoryError', 'ModuleNotFoundError', 'NameError', 'None', 'NotADirectoryError', 'NotImplemented', 'NotImplementedError', 'OSError', 'OverflowError', 'PendingDeprecationWarning', 'PermissionError', 'ProcessLookupError', 'PythonFinalizationError', 'RecursionError', 'ReferenceError', 'ResourceWarning', 'RuntimeError', 'RuntimeWarning', 'StopAsyncIteration', 'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError', 'SystemExit', 'TabError', 'TimeoutError', 'True', 'TypeError', 'UnboundLocalError', 'UnicodeDecodeError', 'UnicodeEncodeError', 'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserWarning', 'ValueError', 'Warning', 'ZeroDivisionError', '_', '_IncompleteInputError', '__build_class__', '__debug__', '__doc__', '__import__', '__loader__', '__name__', '__package__', '__spec__', 'abs', 'aiter', 'all', 'anext', 'any', 'ascii', 'bin', 'bool', 'breakpoint', 'bytearray', 'bytes', 'callable', 'chr', 'classmethod', 'compile', 'complex', 'copyright', 'credits', 'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval', 'exec', 'exit', 'filter', 'float', 'format', 'frozenset', 'getattr', 'globals', 'hasattr', 'hash', 'help', 'hex', 'id', 'input', 'int', 'isinstance', 'issubclass', 'iter', 'len', 'license', 'list', 'locals', 'map', 'max', 'memoryview', 'min', 'next', 'object', 'oct', 'open', 'ord', 'pow', 'print', 'property', 'quit', 'range', 'repr', 'reversed', 'round', 'set', 'setattr', 'slice', 'sorted', 'staticmethod', 'str', 'sum', 'super', 'tuple', 'type', 'vars', 'zip']
     Global namespace: ['__name__', '__doc__', '__package__', '__loader__', '__spec__', '__file__', '__cached__', '__builtins__', 'Form', 'Square', 'Circle']
     Superclass namespace: ['__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', 'move']
     Class namespace: ['__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', 'circles', 'circumference', 'circumferences', 'diameter', 'instance_variables', 'move', 'namespaces', 'pi']
@@ -64,8 +79,8 @@ You can now analyse the namespace of the instance with the method
 .. literalinclude:: form_ns.py
     :language: python
     :linenos:
-    :lines: 72-
-    :lineno-start: 72
+    :lines: 73-
+    :lineno-start: 73
 
 .. code-block:: pycon