diff options
Diffstat (limited to 'Doc/library')
| -rw-r--r-- | Doc/library/2to3.rst | 49 | ||||
| -rw-r--r-- | Doc/library/getopt.rst | 7 | ||||
| -rw-r--r-- | Doc/library/multiprocessing.rst | 2 | ||||
| -rw-r--r-- | Doc/library/optparse.rst | 8 | ||||
| -rw-r--r-- | Doc/library/smtplib.rst | 10 | ||||
| -rw-r--r-- | Doc/library/sqlite3.rst | 2 |
6 files changed, 56 insertions, 22 deletions
diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst index 99749b3..e8ea861 100644 --- a/Doc/library/2to3.rst +++ b/Doc/library/2to3.rst @@ -7,15 +7,21 @@ 2to3 is a Python program that reads Python 2.x source code and applies a series of *fixers* to transform it into valid Python 3.x code. The standard library -contains a rich set of fixers that will handle almost all code. It is, however, -possible to write your own fixers. +contains a rich set of fixers that will handle almost all code. 2to3 supporting +library :mod:`lib2to3` is, however, a flexible and generic library, so it is +possible to write your own fixers for 2to3. :mod:`lib2to3` could also be +adapted to custom applications in which Python code needs to be edited +automatically. Using 2to3 ---------- -2to3 can be run with a list of files to transform or a directory to recursively -traverse looking for files with the ``.py`` extension. +2to3 will usually be installed with the Python interpreter as a script. It is +also located in the :file:`Tools/scripts` directory of the Python root. + +2to3's basic arguments are a list of files or directories to transform. The +directories are to recursively traversed for Python sources. Here is a sample Python 2.x source file, :file:`example.py`:: @@ -29,13 +35,14 @@ It can be converted to Python 3.x code via 2to3 on the command line:: $ 2to3 example.py -A diff against the original source file will be printed. 2to3 can also write -the needed modifications right back to the source file. (A backup of the -original file will also be made.) This is done with the :option:`-w` flag:: +A diff against the original source file is printed. 2to3 can also write the +needed modifications right back to the source file. (Of course, a backup of the +original is also be made.) Writing the changes back is enabled with the +:option:`-w` flag:: $ 2to3 -w example.py -:file:`example.py` will now look like this:: +After transformation, :file:`example.py` looks like this:: def greet(name): print("Hello, {0}!".format(name)) @@ -43,10 +50,10 @@ original file will also be made.) This is done with the :option:`-w` flag:: name = input() greet(name) -Comments and and exact indentation will be preserved throughout the translation +Comments and and exact indentation are preserved throughout the translation process. -By default, 2to3 will run a set of predefined fixers. The :option:`-l` flag +By default, 2to3 runs a set of predefined fixers. The :option:`-l` flag lists all avaible fixers. An explicit set of fixers to run can be given by use of the :option:`-f` flag. The following example runs only the ``imports`` and ``has_key`` fixers:: @@ -54,16 +61,30 @@ of the :option:`-f` flag. The following example runs only the ``imports`` and $ 2to3 -f imports -f has_key example.py Some fixers are *explicit*, meaning they aren't run be default and must be -listed on the command line. Here, in addition to the default fixers, the -``idioms`` fixer is run:: +listed on the command line to be run. Here, in addition to the default fixers, +the ``idioms`` fixer is run:: $ 2to3 -f all -f idioms example.py -Notice how ``all`` enables all default fixers. +Notice how passing ``all`` enables all default fixers. Sometimes 2to3 will find will find a place in your source code that needs to be changed, but 2to3 cannot fix automatically. In this case, 2to3 will print a -warning beneath the diff for a file. +warning beneath the diff for a file. You should address the warning in order to +have compliant 3.x code. + +2to3 can also refactor doctests. To enable this mode, use the :option:`-d` +flag. Note that *only* doctests will be refactored. + +The :option:`-v` option enables the output of more information on the +translation process. + +When the :option:`-p` is passed to it, 2to3 treats ``print`` as a function +instead of a statement. This is useful when ``from __future__ import +print_function`` is being used. If this option is not given, the print fixer +will surround print calls in an extra set of parentheses because it cannot +differentiate between the and print statement with parentheses (such as ``print +("a" + "b" + "c")``) and a true function call. :mod:`lib2to3` - 2to3's library diff --git a/Doc/library/getopt.rst b/Doc/library/getopt.rst index cdc40bf..4bf5bef 100644 --- a/Doc/library/getopt.rst +++ b/Doc/library/getopt.rst @@ -11,7 +11,12 @@ This module helps scripts to parse the command line arguments in ``sys.argv``. It supports the same conventions as the Unix :cfunc:`getopt` function (including the special meanings of arguments of the form '``-``' and '``--``'). Long options similar to those supported by GNU software may be used as well via an -optional third argument. This module provides two functions and an +optional third argument. + +A more convenient, flexible, and powerful alternative is the +:mod:`optparse` module. + +This module provides two functions and an exception: diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index a247e2f..3621412 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -1859,7 +1859,7 @@ Joining processes that use queues Bear in mind that a process that has put items in a queue will wait before terminating until all the buffered items are fed by the "feeder" thread to the underlying pipe. (The child process can call the - :meth:`Queue.cancel_join` method of the queue to avoid this behaviour.) + :meth:`Queue.cancel_join_thread` method of the queue to avoid this behaviour.) This means that whenever you use a queue you need to make sure that all items which have been put on the queue will eventually be removed before the diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index bd0b02a..de1a116 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -8,7 +8,7 @@ ``optparse`` is a more convenient, flexible, and powerful library for parsing -command-line options than ``getopt``. ``optparse`` uses a more declarative +command-line options than the old :mod:`getopt` module. ``optparse`` uses a more declarative style of command-line parsing: you create an instance of :class:`OptionParser`, populate it with options, and parse the command line. ``optparse`` allows users to specify options in the conventional GNU/POSIX syntax, and additionally @@ -92,7 +92,7 @@ argument ``sys.argv[1:]``, or of some other list provided as a substitute for ``sys.argv[1:]``". -option +option an argument used to supply extra information to guide or customize the execution of a program. There are many different syntaxes for options; the traditional Unix syntax is a hyphen ("-") followed by a single letter, e.g. ``"-x"`` or @@ -464,7 +464,7 @@ user-friendly (documented) options:: action="store_true", dest="verbose", default=True, help="make lots of noise [default]") parser.add_option("-q", "--quiet", - action="store_false", dest="verbose", + action="store_false", dest="verbose", help="be vewwy quiet (I'm hunting wabbits)") parser.add_option("-f", "--filename", metavar="FILE", help="write output to FILE"), @@ -1632,7 +1632,7 @@ arguments:: setattr(parser.values, option.dest, value) [...] - parser.add_option("-c", "--callback", + parser.add_option("-c", "--callback", dest="vararg_attr", action="callback", callback=vararg_callback) The main weakness with this particular implementation is that negative numbers diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index 31f1ad6..74be645 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -171,6 +171,8 @@ An :class:`SMTP` instance has the following methods: Identify yourself to the SMTP server using ``HELO``. The hostname argument defaults to the fully qualified domain name of the local host. + The message returned by the server is stored as the :attr:`helo_resp` attribute + of the object. In normal operation it should not be necessary to call this method explicitly. It will be implicitly called by the :meth:`sendmail` when necessary. @@ -180,7 +182,13 @@ An :class:`SMTP` instance has the following methods: Identify yourself to an ESMTP server using ``EHLO``. The hostname argument defaults to the fully qualified domain name of the local host. Examine the - response for ESMTP option and store them for use by :meth:`has_extn`. + response for ESMTP option and store them for use by :meth:`has_extn`. + Also sets several informational attributes: the message returned by + the server is stored as the :attr:`ehlo_resp` attribute, :attr:`does_esmtp` + is set to true or false depending on whether the server supports ESMTP, and + :attr:`esmtp_features` will be a dictionary containing the names of the + SMTP service extensions this server supports, and their + parameters (if any). Unless you wish to use :meth:`has_extn` before sending mail, it should not be necessary to call this method explicitly. It will be implicitly called by diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index baf12e8..3e3faca 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -419,7 +419,7 @@ A :class:`Connection` instance has the following attributes and methods: import sqlite3, os con = sqlite3.connect('existing_db.db') - full_dump = os.linesep.join([line for line in con.iterdump()]) + full_dump = os.linesep.join(con.iterdump()) f = open('dump.sql', 'w') f.writelines(full_dump) f.close() |