diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/c-api/unicode.rst | 32 | ||||
| -rw-r--r-- | Doc/c-api/weakref.rst | 9 | ||||
| -rw-r--r-- | Doc/distutils/apiref.rst | 169 | ||||
| -rw-r--r-- | Doc/distutils/builtdist.rst | 2 | ||||
| -rw-r--r-- | Doc/distutils/extending.rst | 4 | ||||
| -rw-r--r-- | Doc/library/constants.rst | 23 | ||||
| -rw-r--r-- | Doc/library/functions.rst | 8 | ||||
| -rw-r--r-- | Doc/library/os.path.rst | 4 | ||||
| -rw-r--r-- | Doc/reference/compound_stmts.rst | 50 | ||||
| -rw-r--r-- | Doc/reference/lexical_analysis.rst | 11 |
10 files changed, 172 insertions, 140 deletions
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 32a7ca9..4db7671 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -641,6 +641,38 @@ These are the UTF-16 codec APIs: Return *NULL* if an exception was raised by the codec. +UTF-7 Codecs +"""""""""""" + +These are the UTF-7 codec APIs: + + +.. cfunction:: PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors) + + Create a Unicode object by decoding *size* bytes of the UTF-7 encoded string + *s*. Return *NULL* if an exception was raised by the codec. + + +.. cfunction:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed) + + If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF7`. If + *consumed* is not *NULL*, trailing incomplete UTF-7 base-64 sections will not + be treated as an error. Those bytes will not be decoded and the number of + bytes that have been decoded will be stored in *consumed*. + + +.. cfunction:: PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors) + + Encode the :ctype:`Py_UNICODE` buffer of the given size using UTF-7 and + return a Python bytes object. Return *NULL* if an exception was raised by + the codec. + + If *base64SetO* is nonzero, "Set O" (punctuation that has no otherwise + special meaning) will be encoded in base-64. If *base64WhiteSpace* is + nonzero, whitespace will be encoded in base-64. Both are set to zero for the + Python "utf-7" codec. + + Unicode-Escape Codecs """"""""""""""""""""" diff --git a/Doc/c-api/weakref.rst b/Doc/c-api/weakref.rst index 081419d..8a36110 100644 --- a/Doc/c-api/weakref.rst +++ b/Doc/c-api/weakref.rst @@ -53,7 +53,14 @@ as much as it can. .. cfunction:: PyObject* PyWeakref_GetObject(PyObject *ref) Return the referenced object from a weak reference, *ref*. If the referent is - no longer live, returns ``None``. + no longer live, returns :const:`Py_None`. + + .. warning:: + + This function returns a **borrowed reference** to the referenced object. + This means that you should always call :cfunc:`Py_INCREF` on the object + except if you know that it cannot be destroyed while you are still + using it. .. cfunction:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref) diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst index 366c713..2401da3 100644 --- a/Doc/distutils/apiref.rst +++ b/Doc/distutils/apiref.rst @@ -147,11 +147,11 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and In addition, the :mod:`distutils.core` module exposed a number of classes that live elsewhere. -* :class:`Extension` from :mod:`distutils.extension` +* :class:`~distutils.extension.Extension` from :mod:`distutils.extension` -* :class:`Command` from :mod:`distutils.cmd` +* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd` -* :class:`Distribution` from :mod:`distutils.dist` +* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist` A short description of each of these follows, but see the relevant module for the full reference. @@ -1679,8 +1679,8 @@ lines, and joining lines with backslashes. =================================================================== .. module:: distutils.cmd - :synopsis: This module provides the abstract base class Command. This class is subclassed - by the modules in the distutils.command subpackage. + :synopsis: This module provides the abstract base class Command. This class + is subclassed by the modules in the distutils.command subpackage. This module supplies the abstract base class :class:`Command`. @@ -1690,20 +1690,84 @@ This module supplies the abstract base class :class:`Command`. Abstract base class for defining command classes, the "worker bees" of the Distutils. A useful analogy for command classes is to think of them as - subroutines with local variables called *options*. The options are declared in - :meth:`initialize_options` and defined (given their final values) in - :meth:`finalize_options`, both of which must be defined by every command class. - The distinction between the two is necessary because option values might come - from the outside world (command line, config file, ...), and any options - dependent on other options must be computed after these outside influences have - been processed --- hence :meth:`finalize_options`. The body of the subroutine, - where it does all its work based on the values of its options, is the - :meth:`run` method, which must also be implemented by every command class. - - The class constructor takes a single argument *dist*, a :class:`Distribution` + subroutines with local variables called *options*. The options are declared + in :meth:`initialize_options` and defined (given their final values) in + :meth:`finalize_options`, both of which must be defined by every command + class. The distinction between the two is necessary because option values + might come from the outside world (command line, config file, ...), and any + options dependent on other options must be computed after these outside + influences have been processed --- hence :meth:`finalize_options`. The body + of the subroutine, where it does all its work based on the values of its + options, is the :meth:`run` method, which must also be implemented by every + command class. + + The class constructor takes a single argument *dist*, a :class:`Distribution` instance. +Creating a new Distutils command +================================ + +This section outlines the steps to create a new Distutils command. + +A new command lives in a module in the :mod:`distutils.command` package. There +is a sample template in that directory called :file:`command_template`. Copy +this file to a new module with the same name as the new command you're +implementing. This module should implement a class with the same name as the +module (and the command). So, for instance, to create the command +``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy +:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit +it so that it's implementing the class :class:`peel_banana`, a subclass of +:class:`distutils.cmd.Command`. + +Subclasses of :class:`Command` must define the following methods. + +.. method:: Command.initialize_options() + + Set default values for all the options that this command supports. Note that + these defaults may be overridden by other commands, by the setup script, by + config files, or by the command-line. Thus, this is not the place to code + dependencies between options; generally, :meth:`initialize_options` + implementations are just a bunch of ``self.foo = None`` assignments. + + +.. method:: Command.finalize_options() + + Set final values for all the options that this command supports. This is + always called as late as possible, ie. after any option assignments from the + command-line or from other commands have been done. Thus, this is the place + to to code option dependencies: if *foo* depends on *bar*, then it is safe to + set *foo* from *bar* as long as *foo* still has the same value it was + assigned in :meth:`initialize_options`. + + +.. method:: Command.run() + + A command's raison d'etre: carry out the action it exists to perform, controlled + by the options initialized in :meth:`initialize_options`, customized by other + commands, the setup script, the command-line, and config files, and finalized in + :meth:`finalize_options`. All terminal output and filesystem interaction should + be done by :meth:`run`. + + +.. attribute:: Command.sub_commands + + *sub_commands* formalizes the notion of a "family" of commands, + e.g. ``install`` as the parent with sub-commands ``install_lib``, + ``install_headers``, etc. The parent of a family of commands defines + *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name, + predicate)``, with *command_name* a string and *predicate* a function, a + string or ``None``. *predicate* is a method of the parent command that + determines whether the corresponding command is applicable in the current + situation. (E.g. we ``install_headers`` is only applicable if we have any C + header files to install.) If *predicate* is ``None``, that command is always + applicable. + + *sub_commands* is usually defined at the *end* of a class, because + predicates can be methods of the class, so they must already have been + defined. The canonical example is the :command:`install` command. + + :mod:`distutils.command` --- Individual Distutils commands ========================================================== @@ -1942,76 +2006,3 @@ The ``register`` command registers the package with the Python Package Index. This is described in more detail in :pep:`301`. .. % todo - -:mod:`distutils.command.check` --- Check the meta-data of a package -=================================================================== - -.. module:: distutils.command.check - :synopsis: Check the metadata of a package - - -The ``check`` command performs some tests on the meta-data of a package. -For example, it verifies that all required meta-data are provided as -the arguments passed to the :func:`setup` function. - -.. % todo - - -Creating a new Distutils command -================================ - -This section outlines the steps to create a new Distutils command. - -A new command lives in a module in the :mod:`distutils.command` package. There -is a sample template in that directory called :file:`command_template`. Copy -this file to a new module with the same name as the new command you're -implementing. This module should implement a class with the same name as the -module (and the command). So, for instance, to create the command -``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy -:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit -it so that it's implementing the class :class:`peel_banana`, a subclass of -:class:`distutils.cmd.Command`. - -Subclasses of :class:`Command` must define the following methods. - - -.. method:: Command.initialize_options() - - Set default values for all the options that this command supports. Note that - these defaults may be overridden by other commands, by the setup script, by - config files, or by the command-line. Thus, this is not the place to code - dependencies between options; generally, :meth:`initialize_options` - implementations are just a bunch of ``self.foo = None`` assignments. - - -.. method:: Command.finalize_options() - - Set final values for all the options that this command supports. This is - always called as late as possible, ie. after any option assignments from the - command-line or from other commands have been done. Thus, this is the place - to to code option dependencies: if *foo* depends on *bar*, then it is safe to - set *foo* from *bar* as long as *foo* still has the same value it was - assigned in :meth:`initialize_options`. - - -.. method:: Command.run() - - A command's raison d'etre: carry out the action it exists to perform, controlled - by the options initialized in :meth:`initialize_options`, customized by other - commands, the setup script, the command-line, and config files, and finalized in - :meth:`finalize_options`. All terminal output and filesystem interaction should - be done by :meth:`run`. - -*sub_commands* formalizes the notion of a "family" of commands, eg. ``install`` -as the parent with sub-commands ``install_lib``, ``install_headers``, etc. The -parent of a family of commands defines *sub_commands* as a class attribute; it's -a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string -and *predicate* a function, a string or None. *predicate* is a method of -the parent command that determines whether the corresponding command is -applicable in the current situation. (Eg. we ``install_headers`` is only -applicable if we have any C header files to install.) If *predicate* is None, -that command is always applicable. - -*sub_commands* is usually defined at the \*end\* of a class, because predicates -can be methods of the class, so they must already have been defined. The -canonical example is the :command:`install` command. diff --git a/Doc/distutils/builtdist.rst b/Doc/distutils/builtdist.rst index 4f086c6..1cd5891 100644 --- a/Doc/distutils/builtdist.rst +++ b/Doc/distutils/builtdist.rst @@ -176,7 +176,7 @@ easily specify multiple formats in one run. If you need to do both, you can explicitly specify multiple :command:`bdist_\*` commands and their options:: python setup.py bdist_rpm --packager="John Doe <jdoe@example.org>" \ - bdist_wininst --target_version="2.0" + bdist_wininst --target-version="2.0" Creating RPM packages is driven by a :file:`.spec` file, much as using the Distutils is driven by the setup script. To make your life easier, the diff --git a/Doc/distutils/extending.rst b/Doc/distutils/extending.rst index 972ff02..5a70d03 100644 --- a/Doc/distutils/extending.rst +++ b/Doc/distutils/extending.rst @@ -15,8 +15,8 @@ want to modify existing commands; many simply add a few file extensions that should be copied into packages in addition to :file:`.py` files as a convenience. -Most distutils command implementations are subclasses of the :class:`Command` -class from :mod:`distutils.cmd`. New commands may directly inherit from +Most distutils command implementations are subclasses of the +:class:`distutils.cmd.Command` class. New commands may directly inherit from :class:`Command`, while replacements often derive from :class:`Command` indirectly, directly subclassing the command they are replacing. Commands are required to derive from :class:`Command`. diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst index f734b5c..51a1c26 100644 --- a/Doc/library/constants.rst +++ b/Doc/library/constants.rst @@ -3,15 +3,6 @@ Built-in Constants A small number of constants live in the built-in namespace. They are: - -.. note:: - - :data:`None`, :data:`False`, :data:`True` and :data:`__debug__` cannot be - reassigned (assignments to them raise :exc:`SyntaxError`), so they can be - considered "true" constants. - -.. XXX False, True, None are keywords too - .. data:: False The false value of the :class:`bool` type. Assignments to ``False`` @@ -40,19 +31,23 @@ A small number of constants live in the built-in namespace. They are: .. data:: Ellipsis - The same as ``...``. Special value used mostly in conjunction with extended - slicing syntax for user-defined container data types, as in :: - - .. XXX Someone who understands extended slicing should fill in here. + The same as ``...``. Special value used mostly in conjunction with extended + slicing syntax for user-defined container data types. .. data:: __debug__ This constant is true if Python was not started with an :option:`-O` option. - Assignments to :const:`__debug__` are illegal and raise a :exc:`SyntaxError`. See also the :keyword:`assert` statement. +.. note:: + + The names :data:`None`, :data:`False`, :data:`True` and :data:`__debug__` + cannot be reassigned (assignments to them, even as an attribute name, raise + :exc:`SyntaxError`), so they can be considered "true" constants. + + Constants added by the :mod:`site` module ----------------------------------------- diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index d73b279..c1a576c 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -331,6 +331,9 @@ are always available. They are listed here in alphabetical order. returns the current global and local dictionary, respectively, which may be useful to pass around for use by :func:`eval` or :func:`exec`. + See :func:`ast.literal_eval` for a function that can safely evaluate strings + with expressions containing only literals. + .. function:: exec(object[, globals[, locals]]) @@ -855,7 +858,7 @@ are always available. They are listed here in alphabetical order. *fget* is a function for getting an attribute value, likewise *fset* is a function for setting, and *fdel* a function for del'ing, an attribute. Typical - use is to define a managed attribute x:: + use is to define a managed attribute ``x``:: class C(object): def __init__(self): @@ -869,6 +872,9 @@ are always available. They are listed here in alphabetical order. del self._x x = property(getx, setx, delx, "I'm the 'x' property.") + If then *c* is an instance of *C*, ``c.x`` will invoke the getter, + ``c.x = value`` will invoke the setter and ``del c.x`` the deleter. + If given, *doc* will be the docstring of the property attribute. Otherwise, the property will copy *fget*'s docstring (if it exists). This makes it possible to create read-only properties easily using :func:`property` as a :term:`decorator`:: diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index 9f71de6..3e60e9e 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -206,7 +206,9 @@ applications should use string objects to access all files. .. function:: normpath(path) Normalize a pathname. This collapses redundant separators and up-level - references so that ``A//B``, ``A/./B`` and ``A/foo/../B`` all become ``A/B``. + references so that ``A//B``, ``A/B/``, ``A/./B`` and ``A/foo/../B`` all become + ``A/B``. + It does not normalize the case (use :func:`normcase` for that). On Windows, it converts forward slashes to backward slashes. It should be understood that this may change the meaning of the path if it contains symbolic links! diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 9bcb108..e2db33c 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -550,24 +550,27 @@ Class definitions A class definition defines a class object (see section :ref:`types`): -.. XXX need to document PEP 3115 changes here (new metaclasses) - .. productionlist:: classdef: [`decorators`] "class" `classname` [`inheritance`] ":" `suite` - inheritance: "(" [`expression_list`] ")" + inheritance: "(" [`argument_list` [","] ] ")" classname: `identifier` -A class definition is an executable statement. It first evaluates the -inheritance list, if present. Each item in the inheritance list should evaluate -to a class object or class type which allows subclassing. The class's suite is -then executed in a new execution frame (see section :ref:`naming`), using a -newly created local namespace and the original global namespace. (Usually, the -suite contains only function definitions.) When the class's suite finishes -execution, its execution frame is discarded but its local namespace is -saved. [#]_ A class object is then created using the inheritance list for the -base classes and the saved local namespace for the attribute dictionary. The -class name is bound to this class object in the original local namespace. +A class definition is an executable statement. The inheritance list usually +gives a list of base classes (see :ref:`metaclasses` for more advanced uses), so +each item in the list should evaluate to a class object which allows +subclassing. + +The class's suite is then executed in a new execution frame (see :ref:`naming`), +using a newly created local namespace and the original global namespace. +(Usually, the suite contains mostly function definitions.) When the class's +suite finishes execution, its execution frame is discarded but its local +namespace is saved. [#]_ A class object is then created using the inheritance +list for the base classes and the saved local namespace for the attribute +dictionary. The class name is bound to this class object in the original local +namespace. + +Class creation can be customized heavily using :ref:`metaclasses <metaclasses>`. Classes can also be decorated; as with functions, :: @@ -581,25 +584,20 @@ is equivalent to :: Foo = f1(arg)(f2(Foo)) **Programmer's note:** Variables defined in the class definition are class -variables; they are shared by instances. Instance variables can be set in a -method with ``self.name = value``. Both class and instance variables are -accessible through the notation "``self.name``", and an instance variable hides -a class variable with the same name when accessed in this way. Class variables -can be used as defaults for instance variables, but using mutable values there -can lead to unexpected results. Descriptors can be used to create instance -variables with different implementation details. +attributes; they are shared by instances. Instance attributes can be set in a +method with ``self.name = value``. Both class and instance attributes are +accessible through the notation "``self.name``", and an instance attribute hides +a class attribute with the same name when accessed in this way. Class +attributes can be used as defaults for instance attributes, but using mutable +values there can lead to unexpected results. :ref:`Descriptors <descriptors>` +can be used to create instance variables with different implementation details. -.. XXX add link to descriptor docs above .. seealso:: + :pep:`3116` - Metaclasses in Python 3 :pep:`3129` - Class Decorators -Class definitions, like function definitions, may be wrapped by one or more -:term:`decorator` expressions. The evaluation rules for the decorator -expressions are the same as for functions. The result must be a class object, -which is then bound to the class name. - .. rubric:: Footnotes diff --git a/Doc/reference/lexical_analysis.rst b/Doc/reference/lexical_analysis.rst index 1b8b7b5..51a291e 100644 --- a/Doc/reference/lexical_analysis.rst +++ b/Doc/reference/lexical_analysis.rst @@ -362,11 +362,12 @@ characters: information on this convention. ``__*__`` - System-defined names. These names are defined by the interpreter and its - implementation (including the standard library); applications should not expect - to define additional names using this convention. The set of names of this - class defined by Python may be extended in future versions. See section - :ref:`specialnames`. + System-defined names. These names are defined by the interpreter and its + implementation (including the standard library). Current system names are + discussed in the :ref:`specialnames` section and elsewhere. More will likely + be defined in future versions of Python. *Any* use of ``__*__`` names, in + any context, that does not follow explicitly documented use, is subject to + breakage without warning. ``__*`` Class-private names. Names in this category, when used within the context of a |