[Python-checkins] cpython (merge 3.3 -> default): Issue #19197: Improved cross-references in the shlex module documentation.
serhiy.storchaka
python-checkins at python.org
Sun Oct 13 20:21:01 CEST 2013
http://hg.python.org/cpython/rev/dfbd5115fb95
changeset: 86328:dfbd5115fb95
parent: 86325:3752c94368dd
parent: 86327:325fedff6178
user: Serhiy Storchaka <storchaka at gmail.com>
date: Sun Oct 13 21:20:30 2013 +0300
summary:
Issue #19197: Improved cross-references in the shlex module documentation.
files:
Doc/library/shlex.rst | 110 ++++++++++++++++-------------
1 files changed, 59 insertions(+), 51 deletions(-)
diff --git a/Doc/library/shlex.rst b/Doc/library/shlex.rst
--- a/Doc/library/shlex.rst
+++ b/Doc/library/shlex.rst
@@ -12,9 +12,9 @@
--------------
-The :class:`shlex` class makes it easy to write lexical analyzers for simple
-syntaxes resembling that of the Unix shell. This will often be useful for
-writing minilanguages, (for example, in run control files for Python
+The :class:`~shlex.shlex` class makes it easy to write lexical analyzers for
+simple syntaxes resembling that of the Unix shell. This will often be useful
+for writing minilanguages, (for example, in run control files for Python
applications) or for parsing quoted strings.
The :mod:`shlex` module defines the following functions:
@@ -24,15 +24,16 @@
Split the string *s* using shell-like syntax. If *comments* is :const:`False`
(the default), the parsing of comments in the given string will be disabled
- (setting the :attr:`commenters` attribute of the :class:`shlex` instance to
- the empty string). This function operates in POSIX mode by default, but uses
- non-POSIX mode if the *posix* argument is false.
+ (setting the :attr:`~shlex.commenters` attribute of the
+ :class:`~shlex.shlex` instance to the empty string). This function operates
+ in POSIX mode by default, but uses non-POSIX mode if the *posix* argument is
+ false.
.. note::
- Since the :func:`split` function instantiates a :class:`shlex` instance,
- passing ``None`` for *s* will read the string to split from standard
- input.
+ Since the :func:`split` function instantiates a :class:`~shlex.shlex`
+ instance, passing ``None`` for *s* will read the string to split from
+ standard input.
.. function:: quote(s)
@@ -73,17 +74,19 @@
.. class:: shlex(instream=None, infile=None, posix=False)
- A :class:`shlex` instance or subclass instance is a lexical analyzer object.
- The initialization argument, if present, specifies where to read characters
- from. It must be a file-/stream-like object with :meth:`read` and
- :meth:`readline` methods, or a string. If no argument is given, input will
- be taken from ``sys.stdin``. The second optional argument is a filename
- string, which sets the initial value of the :attr:`infile` attribute. If the
- *instream* argument is omitted or equal to ``sys.stdin``, this second
- argument defaults to "stdin". The *posix* argument defines the operational
- mode: when *posix* is not true (default), the :class:`shlex` instance will
- operate in compatibility mode. When operating in POSIX mode, :class:`shlex`
- will try to be as close as possible to the POSIX shell parsing rules.
+ A :class:`~shlex.shlex` instance or subclass instance is a lexical analyzer
+ object. The initialization argument, if present, specifies where to read
+ characters from. It must be a file-/stream-like object with
+ :meth:`~io.TextIOBase.read` and :meth:`~io.TextIOBase.readline` methods, or
+ a string. If no argument is given, input will be taken from ``sys.stdin``.
+ The second optional argument is a filename string, which sets the initial
+ value of the :attr:`~shlex.infile` attribute. If the *instream*
+ argument is omitted or equal to ``sys.stdin``, this second argument
+ defaults to "stdin". The *posix* argument defines the operational mode:
+ when *posix* is not true (default), the :class:`~shlex.shlex` instance will
+ operate in compatibility mode. When operating in POSIX mode,
+ :class:`~shlex.shlex` will try to be as close as possible to the POSIX shell
+ parsing rules.
.. seealso::
@@ -97,14 +100,14 @@
shlex Objects
-------------
-A :class:`shlex` instance has the following methods:
+A :class:`~shlex.shlex` instance has the following methods:
.. method:: shlex.get_token()
Return a token. If tokens have been stacked using :meth:`push_token`, pop a
token off the stack. Otherwise, read one from the input stream. If reading
- encounters an immediate end-of-file, :attr:`self.eof` is returned (the empty
+ encounters an immediate end-of-file, :attr:`eof` is returned (the empty
string (``''``) in non-POSIX mode, and ``None`` in POSIX mode).
@@ -122,9 +125,9 @@
.. method:: shlex.sourcehook(filename)
- When :class:`shlex` detects a source request (see :attr:`source` below) this
- method is given the following token as argument, and expected to return a tuple
- consisting of a filename and an open file-like object.
+ When :class:`~shlex.shlex` detects a source request (see :attr:`source`
+ below) this method is given the following token as argument, and expected
+ to return a tuple consisting of a filename and an open file-like object.
Normally, this method first strips any quotes off the argument. If the result
is an absolute pathname, or there was no previous source request in effect, or
@@ -141,8 +144,9 @@
This hook is exposed so that you can use it to implement directory search paths,
addition of file extensions, and other namespace hacks. There is no
- corresponding 'close' hook, but a shlex instance will call the :meth:`close`
- method of the sourced input stream when it returns EOF.
+ corresponding 'close' hook, but a shlex instance will call the
+ :meth:`~io.IOBase.close` method of the sourced input stream when it returns
+ EOF.
For more explicit control of source stacking, use the :meth:`push_source` and
:meth:`pop_source` methods.
@@ -172,8 +176,8 @@
messages in the standard, parseable format understood by Emacs and other Unix
tools.
-Instances of :class:`shlex` subclasses have some public instance variables which
-either control lexical analysis or can be used for debugging:
+Instances of :class:`~shlex.shlex` subclasses have some public instance
+variables which either control lexical analysis or can be used for debugging:
.. attribute:: shlex.commenters
@@ -218,8 +222,8 @@
.. attribute:: shlex.whitespace_split
If ``True``, tokens will only be split in whitespaces. This is useful, for
- example, for parsing command lines with :class:`shlex`, getting tokens in a
- similar way to shell arguments.
+ example, for parsing command lines with :class:`~shlex.shlex`, getting
+ tokens in a similar way to shell arguments.
.. attribute:: shlex.infile
@@ -231,7 +235,8 @@
.. attribute:: shlex.instream
- The input stream from which this :class:`shlex` instance is reading characters.
+ The input stream from which this :class:`~shlex.shlex` instance is reading
+ characters.
.. attribute:: shlex.source
@@ -240,16 +245,16 @@
string will be recognized as a lexical-level inclusion request similar to the
``source`` keyword in various shells. That is, the immediately following token
will opened as a filename and input taken from that stream until EOF, at which
- point the :meth:`close` method of that stream will be called and the input
- source will again become the original input stream. Source requests may be
- stacked any number of levels deep.
+ point the :meth:`~io.IOBase.close` method of that stream will be called and
+ the input source will again become the original input stream. Source
+ requests may be stacked any number of levels deep.
.. attribute:: shlex.debug
- If this attribute is numeric and ``1`` or more, a :class:`shlex` instance will
- print verbose progress output on its behavior. If you need to use this, you can
- read the module source code to learn the details.
+ If this attribute is numeric and ``1`` or more, a :class:`~shlex.shlex`
+ instance will print verbose progress output on its behavior. If you need
+ to use this, you can read the module source code to learn the details.
.. attribute:: shlex.lineno
@@ -273,7 +278,7 @@
Parsing Rules
-------------
-When operating in non-POSIX mode, :class:`shlex` will try to obey to the
+When operating in non-POSIX mode, :class:`~shlex.shlex` will try to obey to the
following rules.
* Quote characters are not recognized within words (``Do"Not"Separate`` is
@@ -287,16 +292,17 @@
* Closing quotes separate words (``"Do"Separate`` is parsed as ``"Do"`` and
``Separate``);
-* If :attr:`whitespace_split` is ``False``, any character not declared to be a
- word character, whitespace, or a quote will be returned as a single-character
- token. If it is ``True``, :class:`shlex` will only split words in whitespaces;
+* If :attr:`~shlex.whitespace_split` is ``False``, any character not
+ declared to be a word character, whitespace, or a quote will be returned as
+ a single-character token. If it is ``True``, :class:`~shlex.shlex` will only
+ split words in whitespaces;
* EOF is signaled with an empty string (``''``);
* It's not possible to parse empty strings, even if quoted.
-When operating in POSIX mode, :class:`shlex` will try to obey to the following
-parsing rules.
+When operating in POSIX mode, :class:`~shlex.shlex` will try to obey to the
+following parsing rules.
* Quotes are stripped out, and do not separate words (``"Do"Not"Separate"`` is
parsed as the single word ``DoNotSeparate``);
@@ -304,14 +310,16 @@
* Non-quoted escape characters (e.g. ``'\'``) preserve the literal value of the
next character that follows;
-* Enclosing characters in quotes which are not part of :attr:`escapedquotes`
- (e.g. ``"'"``) preserve the literal value of all characters within the quotes;
+* Enclosing characters in quotes which are not part of
+ :attr:`~shlex.escapedquotes` (e.g. ``"'"``) preserve the literal value
+ of all characters within the quotes;
-* Enclosing characters in quotes which are part of :attr:`escapedquotes` (e.g.
- ``'"'``) preserves the literal value of all characters within the quotes, with
- the exception of the characters mentioned in :attr:`escape`. The escape
- characters retain its special meaning only when followed by the quote in use, or
- the escape character itself. Otherwise the escape character will be considered a
+* Enclosing characters in quotes which are part of
+ :attr:`~shlex.escapedquotes` (e.g. ``'"'``) preserves the literal value
+ of all characters within the quotes, with the exception of the characters
+ mentioned in :attr:`~shlex.escape`. The escape characters retain its
+ special meaning only when followed by the quote in use, or the escape
+ character itself. Otherwise the escape character will be considered a
normal character.
* EOF is signaled with a :const:`None` value;
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list