From 5e52db035d4fbce88c5a1a9820edca406fbf5f25 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 21 Oct 2007 10:45:46 +0000 Subject: [PATCH] Add :term:s for descriptors. --- Doc/distutils/apiref.rst | 2 +- Doc/extending/newtypes.rst | 4 ++-- Doc/glossary.rst | 16 +++++++++------- Doc/howto/functional.rst | 4 ++-- Doc/library/_ast.rst | 2 +- Doc/library/ctypes.rst | 14 +++++++------- Doc/library/pyclbr.rst | 8 ++++---- Doc/library/stdtypes.rst | 3 +-- Doc/tutorial/modules.rst | 4 ++-- Doc/using/cmdline.rst | 2 +- 10 files changed, 30 insertions(+), 29 deletions(-) diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst index bc5d2b03d70..e3348816e35 100644 --- a/Doc/distutils/apiref.rst +++ b/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 diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst index 2a535791353..e4d4e322166 100644 --- a/Doc/extending/newtypes.rst +++ b/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 diff --git a/Doc/glossary.rst b/Doc/glossary.rst index c92f6c2e759..88b1ccbce54 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -59,14 +59,16 @@ Glossary descriptor Any *new-style* object that defines the methods :meth:`__get__`, - :meth:`__set__`, or :meth:`__delete__`. When a class attribute is a + :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 - dictionary for *a*, but if *b* is a descriptor, the defined method gets - called. Understanding descriptors is a key to a deep understanding of - Python because they are the basis for many features including functions, - methods, properties, class methods, static methods, and reference to super - classes. + lookup. Normally, using *a.b* to get, set or delete an attribute looks up + the object named *b* in the class dictionary for *a*, but if *b* is a + descriptor, the respective descriptor method gets called. Understanding + descriptors is a key to a deep understanding of Python because they are + the basis for many features including functions, methods, properties, + 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 diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst index 78520d1b7f8..39a1e0509f0 100644 --- a/Doc/howto/functional.rst +++ b/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 -a result. +detected by Python's :term:`bytecode` compiler which compiles the function +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 diff --git a/Doc/library/_ast.rst b/Doc/library/_ast.rst index 9b195be4670..9383591e658 100644 --- a/Doc/library/_ast.rst +++ b/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. diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index a5d4a489917..c28fcd3d90e 100644 --- a/Doc/library/ctypes.rst +++ b/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 -debugging because they can provide useful information:: +Field :term:`descriptor`\s can be retrieved from the *class*, they are useful +for debugging because they can provide useful information:: >>> print POINT.x @@ -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 -Python object in the memory block does not store the object itself, instead the -``contents`` of the object is stored. Accessing the contents again constructs a -new Python each time! +block plus some :term:`descriptor`\s accessing the contents of the memory. +Storing a Python object in the memory block does not store the object itself, +instead the ``contents`` of the object is stored. Accessing the contents again +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 diff --git a/Doc/library/pyclbr.rst b/Doc/library/pyclbr.rst index 5a77b4e8765..a052a69d196 100644 --- a/Doc/library/pyclbr.rst +++ b/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 - may be the name of a module within a package. The *path* parameter should be a - sequence, and is used to augment the value of ``sys.path``, which is used to - locate module source code. + objects. The parameter *module* should be the name of a module as a string; + it may be the name of a module within a package. The *path* parameter should + be a sequence, and is used to augment the value of ``sys.path``, which is + used to locate module source code. .. % The 'inpackage' parameter appears to be for internal use only.... diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index c773e9b25fe..44467af437d 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1899,8 +1899,7 @@ Files have the following methods: .. method:: file.fileno() .. index:: - single: file descriptor - single: descriptor, file + pair: file; descriptor module: fcntl Return the integer "file descriptor" that is used by the underlying diff --git a/Doc/tutorial/modules.rst b/Doc/tutorial/modules.rst index 500bd5933ae..fbe931e1018 100644 --- a/Doc/tutorial/modules.rst +++ b/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 - and ``.py`` files are compiled to optimized bytecode. + :option:`-O` is used, *all* :term:`bytecode` is optimized; ``.pyc`` files are + 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 diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index eb18c898b33..952adb2d0d8 100644 --- a/Doc/using/cmdline.rst +++ b/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`.