summaryrefslogtreecommitdiffstats
path: root/Doc/reference
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/reference')
-rw-r--r--Doc/reference/compound_stmts.rst17
-rw-r--r--Doc/reference/datamodel.rst33
-rw-r--r--Doc/reference/import.rst20
3 files changed, 47 insertions, 23 deletions
diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index 8afc69e..e35aa9f 100644
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -493,14 +493,15 @@ case the parameter's default value is substituted. If a parameter has a default
value, all following parameters up until the "``*``" must also have a default
value --- this is a syntactic restriction that is not expressed by the grammar.
-**Default parameter values are evaluated when the function definition is
-executed.** This means that the expression is evaluated once, when the function
-is defined, and that the same "pre-computed" value is used for each call. This
-is especially important to understand when a default parameter is a mutable
-object, such as a list or a dictionary: if the function modifies the object
-(e.g. by appending an item to a list), the default value is in effect modified.
-This is generally not what was intended. A way around this is to use ``None``
-as the default, and explicitly test for it in the body of the function, e.g.::
+**Default parameter values are evaluated from left to right when the function
+definition is executed.** This means that the expression is evaluated once, when
+the function is defined, and that the same "pre-computed" value is used for each
+call. This is especially important to understand when a default parameter is a
+mutable object, such as a list or a dictionary: if the function modifies the
+object (e.g. by appending an item to a list), the default value is in effect
+modified. This is generally not what was intended. A way around this is to use
+``None`` as the default, and explicitly test for it in the body of the function,
+e.g.::
def whats_on_the_telly(penguin=None):
if penguin is None:
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 2128ffc..0c6a0ab 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -934,6 +934,20 @@ Internal types
frame). A debugger can implement a Jump command (aka Set Next Statement)
by writing to f_lineno.
+ Frame objects support one method:
+
+ .. method:: frame.clear()
+
+ This method clears all references to local variables held by the
+ frame. Also, if the frame belonged to a generator, the generator
+ is finalized. This helps break reference cycles involving frame
+ objects (for example when catching an exception and storing its
+ traceback for later use).
+
+ :exc:`RuntimeError` is raised if the frame is currently executing.
+
+ .. versionadded:: 3.4
+
Traceback objects
.. index::
object: traceback
@@ -1121,12 +1135,10 @@ Basic customization
``sys.last_traceback`` keeps the stack frame alive). The first situation
can only be remedied by explicitly breaking the cycles; the latter two
situations can be resolved by storing ``None`` in ``sys.last_traceback``.
- Circular references which are garbage are detected when the option cycle
- detector is enabled (it's on by default), but can only be cleaned up if
- there are no Python- level :meth:`__del__` methods involved. Refer to the
- documentation for the :mod:`gc` module for more information about how
- :meth:`__del__` methods are handled by the cycle detector, particularly
- the description of the ``garbage`` value.
+ Circular references which are garbage are detected and cleaned up when
+ the cyclic garbage collector is enabled (it's on by default). Refer to the
+ documentation for the :mod:`gc` module for more information about this
+ topic.
.. warning::
@@ -1830,6 +1842,15 @@ through the container; for mappings, :meth:`__iter__` should be the same as
considered to be false in a Boolean context.
+.. method:: object.__length_hint__(self)
+
+ Called to implement :func:`operator.length_hint`. Should return an estimated
+ length for the object (which may be greater or less than the actual length).
+ The length must be an integer ``>=`` 0. This method is purely an
+ optimization and is never required for correctness.
+
+ .. versionadded:: 3.4
+
.. note::
Slicing is done exclusively with the following three methods. A call like ::
diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst
index eb497a1..b587fc9 100644
--- a/Doc/reference/import.rst
+++ b/Doc/reference/import.rst
@@ -373,16 +373,18 @@ Loaders must satisfy the following requirements:
* The ``__loader__`` attribute must be set to the loader object that loaded
the module. This is mostly for introspection and reloading, but can be
used for additional loader-specific functionality, for example getting
- data associated with a loader.
+ data associated with a loader. If the attribute is missing or set to ``None``
+ then the import machinery will automatically set it **after** the module has
+ been imported.
- * The module's ``__package__`` attribute should be set. Its value must be a
+ * The module's ``__package__`` attribute must be set. Its value must be a
string, but it can be the same value as its ``__name__``. If the attribute
is set to ``None`` or is missing, the import system will fill it in with a
- more appropriate value. When the module is a package, its ``__package__``
- value should be set to its ``__name__``. When the module is not a package,
- ``__package__`` should be set to the empty string for top-level modules, or
- for submodules, to the parent package's name. See :pep:`366` for further
- details.
+ more appropriate value **after** the module has been imported.
+ When the module is a package, its ``__package__`` value should be set to its
+ ``__name__``. When the module is not a package, ``__package__`` should be
+ set to the empty string for top-level modules, or for submodules, to the
+ parent package's name. See :pep:`366` for further details.
This attribute is used instead of ``__name__`` to calculate explicit
relative imports for main modules, as defined in :pep:`366`.
@@ -425,8 +427,8 @@ Here are the exact rules used:
* If the module has a ``__file__`` attribute, this is used as part of the
module's repr.
- * If the module has no ``__file__`` but does have a ``__loader__``, then the
- loader's repr is used as part of the module's repr.
+ * If the module has no ``__file__`` but does have a ``__loader__`` that is not
+ ``None``, then the loader's repr is used as part of the module's repr.
* Otherwise, just use the module's ``__name__`` in the repr.