From a7cbe28bcc8016d22e499b72babd87c93394aa7b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Thu, 1 Sep 2011 19:49:31 +0200 Subject: Avoid using the default reST role. Makes Doc/tools/rstlint.py happy. --- Doc/documenting/building.rst | 10 +++++----- Doc/library/struct.rst | 4 ++-- Doc/library/unittest.rst | 10 +++++----- Doc/library/urllib2.rst | 2 +- 4 files changed, 13 insertions(+), 13 deletions(-) diff --git a/Doc/documenting/building.rst b/Doc/documenting/building.rst index 02b3ee3..dc1c6a0 100644 --- a/Doc/documenting/building.rst +++ b/Doc/documenting/building.rst @@ -17,9 +17,9 @@ installed Python and Subversion, you can just run :: cd Doc make html -to check out the necessary toolset in the `tools/` subdirectory and build the -HTML output files. To view the generated HTML, point your favorite browser at -the top-level index `build/html/index.html` after running "make". +to check out the necessary toolset in the :file:`tools/` subdirectory and build +the HTML output files. To view the generated HTML, point your favorite browser +at the top-level index :file:`build/html/index.html` after running "make". Available make targets are: @@ -50,10 +50,10 @@ Available make targets are: * "pydoc-topics", which builds a Python module containing a dictionary with plain text documentation for the labels defined in - `tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic and + :file:`tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic and keyword help. -A "make update" updates the Subversion checkouts in `tools/`. +A "make update" updates the Subversion checkouts in :file:`tools/`. Without make diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst index 9c7fdd8..817c570 100644 --- a/Doc/library/struct.rst +++ b/Doc/library/struct.rst @@ -22,8 +22,8 @@ structs and the intended conversion to/from Python values. alignment is taken into account when unpacking. This behavior is chosen so that the bytes of a packed struct correspond exactly to the layout in memory of the corresponding C struct. To handle platform-independent data formats - or omit implicit pad bytes, use `standard` size and alignment instead of - `native` size and alignment: see :ref:`struct-alignment` for details. + or omit implicit pad bytes, use ``standard`` size and alignment instead of + ``native`` size and alignment: see :ref:`struct-alignment` for details. Functions and Exceptions ------------------------ diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index 42ae8e2..16a3a36 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -307,7 +307,7 @@ as the start directory. Test discovery loads tests by importing them. Once test discovery has found all the test files from the start directory you specify it turns the - paths into package names to import. For example `foo/bar/baz.py` will be + paths into package names to import. For example :file:`foo/bar/baz.py` will be imported as ``foo.bar.baz``. If you have a package installed globally and attempt test discovery on @@ -905,11 +905,11 @@ Test cases +---------------------------------------------------------+--------------------------------------+------------+ | Method | Checks that | New in | +=========================================================+======================================+============+ - | :meth:`assertRaises(exc, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises `exc` | | + | :meth:`assertRaises(exc, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises *exc* | | | ` | | | +---------------------------------------------------------+--------------------------------------+------------+ - | :meth:`assertRaisesRegexp(exc, re, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises `exc` | 2.7 | - | ` | and the message matches `re` | | + | :meth:`assertRaisesRegexp(exc, re, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises *exc* | 2.7 | + | ` | and the message matches *re* | | +---------------------------------------------------------+--------------------------------------+------------+ .. method:: assertRaises(exception, callable, *args, **kwds) @@ -995,7 +995,7 @@ Test cases | ` | works with unhashable objs | | +---------------------------------------+--------------------------------+--------------+ | :meth:`assertDictContainsSubset(a, b) | all the key/value pairs | 2.7 | - | ` | in `a` exist in `b` | | + | ` | in *a* exist in *b* | | +---------------------------------------+--------------------------------+--------------+ diff --git a/Doc/library/urllib2.rst b/Doc/library/urllib2.rst index d0d4727..b66ebd7 100644 --- a/Doc/library/urllib2.rst +++ b/Doc/library/urllib2.rst @@ -36,7 +36,7 @@ The :mod:`urllib2` module defines the following functions: :mimetype:`application/x-www-form-urlencoded` format. The :func:`urllib.urlencode` function takes a mapping or sequence of 2-tuples and returns a string in this format. urllib2 module sends HTTP/1.1 requests with - `Connection:close` header included. + ``Connection:close`` header included. The optional *timeout* parameter specifies a timeout in seconds for blocking operations like the connection attempt (if not specified, the global default -- cgit v0.12 From 7ce05e07c01378a7187135cc2df89ecd6e57f9ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Thu, 1 Sep 2011 19:54:05 +0200 Subject: Fix some markup and one typo --- Doc/c-api/init.rst | 4 ++-- Doc/faq/design.rst | 2 +- Doc/faq/windows.rst | 2 +- Doc/library/argparse.rst | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 7c70281..c323eef 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -126,7 +126,7 @@ Process-wide parameters program name is ``'/usr/local/bin/python'``, the prefix is ``'/usr/local'``. The returned string points into static storage; the caller should not modify its value. This corresponds to the :makevar:`prefix` variable in the top-level - :file:`Makefile` and the :option:`--prefix` argument to the :program:`configure` + :file:`Makefile` and the ``--prefix`` argument to the :program:`configure` script at build time. The value is available to Python code as ``sys.prefix``. It is only useful on Unix. See also the next function. @@ -139,7 +139,7 @@ Process-wide parameters program name is ``'/usr/local/bin/python'``, the exec-prefix is ``'/usr/local'``. The returned string points into static storage; the caller should not modify its value. This corresponds to the :makevar:`exec_prefix` - variable in the top-level :file:`Makefile` and the :option:`--exec-prefix` + variable in the top-level :file:`Makefile` and the ``--exec-prefix`` argument to the :program:`configure` script at build time. The value is available to Python code as ``sys.exec_prefix``. It is only useful on Unix. diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst index 0943796..962b4ef 100644 --- a/Doc/faq/design.rst +++ b/Doc/faq/design.rst @@ -684,7 +684,7 @@ construction of large programs. Python 2.6 adds an :mod:`abc` module that lets you define Abstract Base Classes (ABCs). You can then use :func:`isinstance` and :func:`issubclass` to check whether an instance or a class implements a particular ABC. The -:mod:`collections` modules defines a set of useful ABCs such as +:mod:`collections` module defines a set of useful ABCs such as :class:`Iterable`, :class:`Container`, and :class:`MutableMapping`. For Python, many of the advantages of interface specifications can be obtained diff --git a/Doc/faq/windows.rst b/Doc/faq/windows.rst index 47c09ad..96d1c51 100644 --- a/Doc/faq/windows.rst +++ b/Doc/faq/windows.rst @@ -542,7 +542,7 @@ A trick to get it to run an arbitrary file is to construct a call to :func:`execfile` with the name of your file as argument. Also note that you can not mix-and-match Debug and Release versions. If you -wish to use the Debug Multithreaded DLL, then your module *must* have an "_d" +wish to use the Debug Multithreaded DLL, then your module *must* have ``_d`` appended to the base name. diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index bf0899d..09f97a9 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -153,7 +153,7 @@ ArgumentParser objects conflicting optionals. * prog_ - The name of the program (default: - :data:`sys.argv[0]`) + ``sys.argv[0]``) * usage_ - The string describing the program usage (default: generated) -- cgit v0.12 From 2c378ae364df3d8cf263db022b9c6a92a0f6ccb1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Thu, 1 Sep 2011 19:56:04 +0200 Subject: =?UTF-8?q?Document=20that=20True/False/None=20don=E2=80=99t=20use?= =?UTF-8?q?=20:keyword:=20in=20doc?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Doc/documenting/markup.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst index 4f1fcae..25801c7 100644 --- a/Doc/documenting/markup.rst +++ b/Doc/documenting/markup.rst @@ -472,7 +472,10 @@ in a different style: .. describe:: keyword - The name of a keyword in Python. + The name of a Python keyword. Using this role will generate a link to the + documentation of the keyword. ``True``, ``False`` and ``None`` do not use + this role, but simple code markup (````True````), given that they're + fundamental to the language and should be known to any programmer. .. describe:: mailheader -- cgit v0.12 From cd90f791252346741a2f0e374ef6afc7529cd4e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Thu, 1 Sep 2011 19:57:01 +0200 Subject: =?UTF-8?q?Document=20that=20format=20string=20don=E2=80=99t=20sup?= =?UTF-8?q?port=20arbitrary=20dictonary=20keys.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Text adapted from the PEP. Addition requested by Terry J. Reedy on 2011-02-23 on python-dev. --- Doc/library/string.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 9ee81b5..20fcae9 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -248,6 +248,8 @@ keyword. If it's a number, it refers to a positional argument, and if it's a ke it refers to a named keyword argument. If the numerical arg_names in a format string are 0, 1, 2, ... in sequence, they can all be omitted (not just some) and the numbers 0, 1, 2, ... will be automatically inserted in that order. +Because *arg_name* is not quote-delimited, it is not possible to specify arbitrary +dictionary keys (e.g., the strings ``'10'`` or ``':-]'``) within a format string. The *arg_name* can be followed by any number of index or attribute expressions. An expression of the form ``'.name'`` selects the named attribute using :func:`getattr`, while an expression of the form ``'[index]'`` -- cgit v0.12 From 2532f11321808b8af8c54d6a7171373b64a67748 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Thu, 1 Sep 2011 20:04:50 +0200 Subject: Clarify compileall command-line options (#10454). MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Backport of R. David Murray’s 3.2 patch. The code is ugly, with print statements split across lines, but the output is readable. --- Lib/compileall.py | 39 ++++++++++++++++++++++++++------------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/Lib/compileall.py b/Lib/compileall.py index 910f305..5cfa8be 100644 --- a/Lib/compileall.py +++ b/Lib/compileall.py @@ -1,4 +1,4 @@ -"""Module/script to "compile" all .py files to .pyc (or .pyo) file. +"""Module/script to byte-compile all .py files to .pyc (or .pyo) files. When called as a script with arguments, this compiles the directories given as arguments recursively; the -l option prevents it from @@ -26,8 +26,8 @@ def compile_dir(dir, maxlevels=10, ddir=None, dir: the directory to byte-compile maxlevels: maximum recursion level (default 10) - ddir: if given, purported directory name (this is the - directory name that will show up in error messages) + ddir: the directory that will be prepended to the path to the + file as it is compiled into each byte-code file. force: if 1, force compilation, even if timestamps are up-to-date quiet: if 1, be quiet during compilation """ @@ -64,8 +64,8 @@ def compile_file(fullname, ddir=None, force=0, rx=None, quiet=0): Arguments (only fullname is required): fullname: the file to byte-compile - ddir: if given, purported directory name (this is the - directory name that will show up in error messages) + ddir: if given, the directory name compiled in to the + byte-code file. force: if 1, force compilation, even if timestamps are up-to-date quiet: if 1, be quiet during compilation """ @@ -157,14 +157,27 @@ def main(): print msg print "usage: python compileall.py [-l] [-f] [-q] [-d destdir] " \ "[-x regexp] [-i list] [directory|file ...]" - print "-l: don't recurse down" + print + print "arguments: zero or more file and directory names to compile; " \ + "if no arguments given, " + print " defaults to the equivalent of -l sys.path" + print + print "options:" + print "-l: don't recurse into subdirectories" print "-f: force rebuild even if timestamps are up-to-date" - print "-q: quiet operation" - print "-d destdir: purported directory name for error messages" - print " if no directory arguments, -l sys.path is assumed" - print "-x regexp: skip files matching the regular expression regexp" - print " the regexp is searched for in the full path of the file" - print "-i list: expand list with its content (file and directory names)" + print "-q: output only error messages" + print "-d destdir: directory to prepend to file paths for use in " \ + "compile-time tracebacks and in" + print " runtime tracebacks in cases where the source " \ + "file is unavailable" + print "-x regexp: skip files matching the regular expression regexp; " \ + "the regexp is searched for" + print " in the full path of each file considered for " \ + "compilation" + print "-i file: add all the files and directories listed in file to " \ + "the list considered for" + print ' compilation; if "-", names are read from stdin' + sys.exit(2) maxlevels = 10 ddir = None @@ -205,7 +218,7 @@ def main(): else: success = compile_path() except KeyboardInterrupt: - print "\n[interrupt]" + print "\n[interrupted]" success = 0 return success -- cgit v0.12 From 1fc20760c7a9e1181011549b6ccb1d71d5ba3ef8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Thu, 1 Sep 2011 22:06:49 +0200 Subject: Remove obsolete comment --- Lib/pipes.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/Lib/pipes.py b/Lib/pipes.py index 02e1257..26750f6 100644 --- a/Lib/pipes.py +++ b/Lib/pipes.py @@ -54,8 +54,6 @@ for the built-in function open() or for os.popen(). To create a new template object initialized to a given one: t2 = t.clone() - -For an example, see the function test() at the end of the file. """ # ' -- cgit v0.12