From: Serhiy Storchaka Date: Sun, 13 Oct 2013 18:17:56 +0000 (+0300) Subject: Issue #19197: Improved cross-references in the shlex module documentation. X-Git-Tag: v2.7.6rc1~31 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=7378d6374c286c86daf4389fbbb4ee2d52ac3401;p=python Issue #19197: Improved cross-references in the shlex module documentation. --- diff --git a/Doc/library/shlex.rst b/Doc/library/shlex.rst index bb05c7d461..be08e01ab5 100644 --- a/Doc/library/shlex.rst +++ b/Doc/library/shlex.rst @@ -16,9 +16,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. Prior to Python 2.7.3, this module did not support Unicode input. @@ -30,9 +30,10 @@ The :mod:`shlex` module defines the following functions: 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. .. versionadded:: 2.3 @@ -41,26 +42,28 @@ The :mod:`shlex` module defines the following functions: .. 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. The :mod:`shlex` module defines the following class: .. class:: shlex([instream[, infile[, posix]]]) - 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 (strings are accepted since Python 2.3). - 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 - was introduced in Python 2.3, and 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 (strings are accepted since Python 2.3). 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 was + introduced in Python 2.3, and 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:: @@ -74,14 +77,14 @@ The :mod:`shlex` module defines the following class: 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). @@ -99,9 +102,9 @@ A :class:`shlex` instance has the following methods: .. 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 @@ -118,8 +121,9 @@ A :class:`shlex` instance has the following methods: 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. @@ -153,8 +157,8 @@ A :class:`shlex` instance has the following methods: 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 @@ -203,8 +207,8 @@ either control lexical analysis or can be used for debugging: .. 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. .. versionadded:: 2.3 @@ -218,7 +222,8 @@ either control lexical analysis or can be used for debugging: .. 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 @@ -227,16 +232,16 @@ either control lexical analysis or can be used for debugging: 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 @@ -262,7 +267,7 @@ either control lexical analysis or can be used for debugging: 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 @@ -276,16 +281,17 @@ following rules. * 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``); @@ -293,14 +299,16 @@ parsing rules. * 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;