Add :term:s for descriptors.

Doc/distutils/apiref.rst

@@ -1199,7 +1199,7 @@ other utility module.
 
    If *force* is true, all files are recompiled regardless of timestamps.
 
-   The source filename encoded in each bytecode file defaults to the filenames
+   The source filename encoded in each :term:`bytecode` file defaults to the filenames
    listed in *py_files*; you can modify these with *prefix* and *basedir*.
    *prefix* is a string that will be stripped off of each source filename, and
    *base_dir* is a directory name that will be prepended (after *prefix* is

Doc/extending/newtypes.rst

@@ -1149,7 +1149,7 @@ Note that this list does not place any restrictions on the values of the
 attributes, when the values are computed, or how relevant data is stored.
 
 When :cfunc:`PyType_Ready` is called, it uses three tables referenced by the
-type object to create *descriptors* which are placed in the dictionary of the
+type object to create :term:`descriptor`\s which are placed in the dictionary of the
 type object.  Each descriptor controls access to one attribute of the instance
 object.  Each of the tables is optional; if all three are *NULL*, instances of
 the type will only have attributes that are inherited from their base type, and
@@ -1193,7 +1193,7 @@ be read-only or read-write.  The structures in the table are defined as::
        char *doc;
    } PyMemberDef;
 
-For each entry in the table, a descriptor will be constructed and added to the
+For each entry in the table, a :term:`descriptor` will be constructed and added to the
 type which will be able to extract a value from the instance structure.  The
 :attr:`type` field should contain one of the type codes defined in the
 :file:`structmember.h` header; the value will be used to determine how to

Doc/glossary.rst

@@ -61,12 +61,14 @@ Glossary
       Any *new-style* object that defines the methods :meth:`__get__`,
       :meth:`__set__`, or :meth:`__delete__`.  When a class attribute is a
       descriptor, its special binding behavior is triggered upon attribute
-      lookup.  Normally, writing *a.b* looks up the object *b* in the class
+      lookup.  Normally, using *a.b* to get, set or delete an attribute looks up
-      dictionary for *a*, but if *b* is a descriptor, the defined method gets
+      the object named *b* in the class dictionary for *a*, but if *b* is a
-      called. Understanding descriptors is a key to a deep understanding of
+      descriptor, the respective descriptor method gets called.  Understanding
-      Python because they are the basis for many features including functions,
+      descriptors is a key to a deep understanding of Python because they are
-      methods, properties, class methods, static methods, and reference to super
+      the basis for many features including functions, methods, properties,
-      classes.
+      class methods, static methods, and reference to super classes.
+
+      For more information about descriptors' methods, see :ref:`descriptors`.
     
    dictionary
       An associative array, where arbitrary keys are mapped to values.  The use

Doc/howto/functional.rst

@@ -448,8 +448,8 @@ Here's the simplest example of a generator function::
             yield i
 
 Any function containing a ``yield`` keyword is a generator function; this is
-detected by Python's :term:`bytecode` compiler which compiles the function specially as
+detected by Python's :term:`bytecode` compiler which compiles the function
-a result.
+specially as a result.
 
 When you call a generator function, it doesn't return a single value; instead it
 returns a generator object that supports the iterator protocol.  On executing

Doc/library/_ast.rst

@@ -14,7 +14,7 @@ Abstract Syntax Trees
 The ``_ast`` module helps Python applications to process trees of the Python
 abstract syntax grammar. The Python compiler currently provides read-only access
 to such trees, meaning that applications can only create a tree for a given
-piece of Python source code; generating byte code from a (potentially modified)
+piece of Python source code; generating :term:`bytecode` from a (potentially modified)
 tree is not supported. The abstract syntax itself might change with each Python
 release; this module helps to find out programmatically what the current grammar
 looks like.

Doc/library/ctypes.rst

@@ -586,8 +586,8 @@ Nested structures can also be initialized in the constructor in several ways::
    >>> r = RECT(POINT(1, 2), POINT(3, 4))
    >>> r = RECT((1, 2), (3, 4))
 
-Fields descriptors can be retrieved from the *class*, they are useful for
+Field :term:`descriptor`\s can be retrieved from the *class*, they are useful
-debugging because they can provide useful information::
+for debugging because they can provide useful information::
 
    >>> print POINT.x
    <Field type=c_long, ofs=0, size=4>
@@ -1197,10 +1197,10 @@ Another example that may behave different from what one would expect is this::
    >>>
 
 Why is it printing ``False``?  ctypes instances are objects containing a memory
-block plus some descriptors accessing the contents of the memory.  Storing a
+block plus some :term:`descriptor`\s accessing the contents of the memory.
-Python object in the memory block does not store the object itself, instead the
+Storing a Python object in the memory block does not store the object itself,
-``contents`` of the object is stored. Accessing the contents again constructs a
+instead the ``contents`` of the object is stored.  Accessing the contents again
-new Python each time!
+constructs a new Python object each time!
 
 
 .. _ctypes-variable-sized-data-types:
@@ -2267,7 +2267,7 @@ other data types containing pointer type fields.
 
 Concrete structure and union types must be created by subclassing one of these
 types, and at least define a :attr:`_fields_` class variable. ``ctypes`` will
-create descriptors which allow reading and writing the fields by direct
+create :term:`descriptor`\s which allow reading and writing the fields by direct
 attribute accesses.  These are the
 
 

Doc/library/pyclbr.rst

@@ -19,10 +19,10 @@ in Python, including many standard and optional extension modules.
 .. function:: readmodule(module[, path])
 
    Read a module and return a dictionary mapping class names to class descriptor
-   objects.  The parameter *module* should be the name of a module as a string; it
+   objects.  The parameter *module* should be the name of a module as a string;
-   may be the name of a module within a package.  The *path* parameter should be a
+   it may be the name of a module within a package.  The *path* parameter should
-   sequence, and is used to augment the value of ``sys.path``, which is used to
+   be a sequence, and is used to augment the value of ``sys.path``, which is
-   locate module source code.
+   used to locate module source code.
 
    .. % The 'inpackage' parameter appears to be for internal use only....
 

Doc/library/stdtypes.rst

@@ -1899,8 +1899,7 @@ Files have the following methods:
 .. method:: file.fileno()
 
    .. index::
-      single: file descriptor
+      pair: file; descriptor
-      single: descriptor, file
       module: fcntl
 
    Return the integer "file descriptor" that is used by the underlying

Doc/tutorial/modules.rst

@@ -186,8 +186,8 @@ Some tips for experts:
 * When the Python interpreter is invoked with the :option:`-O` flag, optimized
   code is generated and stored in :file:`.pyo` files.  The optimizer currently
   doesn't help much; it only removes :keyword:`assert` statements.  When
-  :option:`-O` is used, *all* bytecode is optimized; ``.pyc`` files are ignored
+  :option:`-O` is used, *all* :term:`bytecode` is optimized; ``.pyc`` files are
-  and ``.py`` files are compiled to optimized bytecode.
+  ignored and ``.py`` files are compiled to optimized bytecode.
 
 * Passing two :option:`-O` flags to the Python interpreter (:option:`-OO`) will
   cause the bytecode compiler to perform optimizations that could in some rare

Doc/using/cmdline.rst

@@ -169,7 +169,7 @@ Miscellaneous options
 .. cmdoption:: -O
 
    Turn on basic optimizations.  This changes the filename extension for
-   compiled (:term:`byte code`) files from ``.pyc`` to ``.pyo``.  See also
+   compiled (:term:`bytecode`) files from ``.pyc`` to ``.pyo``.  See also
    :envvar:`PYTHONOPTIMIZE`.