1212
1313--------------
1414
15- The :class: `shlex ` class makes it easy to write lexical analyzers for simple
16- syntaxes resembling that of the Unix shell. This will often be useful for
17- writing minilanguages, (for example, in run control files for Python
15+ The :class: `~ shlex.shlex
16+ simple syntaxes resembling that of the Unix shell. This will often be useful
17+ for writing minilanguages, (for example, in run control files for Python
1818applications) or for parsing quoted strings.
1919
2020The :mod: `shlex ` module defines the following functions:
@@ -24,15 +24,16 @@ The :mod:`shlex` module defines the following functions:
2424
2525 Split the string *s * using shell-like syntax. If *comments * is :const: `False `
2626 (the default), the parsing of comments in the given string will be disabled
27- (setting the :attr: `commenters ` attribute of the :class: `shlex ` instance to
28- the empty string). This function operates in POSIX mode by default, but uses
29- non-POSIX mode if the *posix * argument is false.
27+ (setting the :attr: `~shlex.commenters ` attribute of the
28+ :class: `~shlex.shlex ` instance to the empty string). This function operates
29+ in POSIX mode by default, but uses non-POSIX mode if the *posix * argument is
30+ false.
3031
3132 .. note ::
3233
33- Since the :func: `split ` function instantiates a :class: `shlex ` instance,
34- passing ``None `` for *s * will read the string to split from standard
35- input.
34+ Since the :func: `split ` function instantiates a :class: `~ shlex.shlex `
35+ instance, passing ``None `` for *s * will read the string to split from
36+ standard input.
3637
3738
3839.. function :: quote(s)
@@ -73,17 +74,19 @@ The :mod:`shlex` module defines the following class:
7374
7475.. class :: shlex(instream=None, infile=None, posix=False)
7576
76- A :class: `shlex ` instance or subclass instance is a lexical analyzer object.
77- The initialization argument, if present, specifies where to read characters
78- from. It must be a file-/stream-like object with :meth: `read ` and
79- :meth: `readline ` methods, or a string. If no argument is given, input will
80- be taken from ``sys.stdin ``. The second optional argument is a filename
81- string, which sets the initial value of the :attr: `infile ` attribute. If the
82- *instream * argument is omitted or equal to ``sys.stdin ``, this second
83- argument defaults to "stdin". The *posix * argument defines the operational
84- mode: when *posix * is not true (default), the :class: `shlex ` instance will
85- operate in compatibility mode. When operating in POSIX mode, :class: `shlex `
86- will try to be as close as possible to the POSIX shell parsing rules.
77+ A :class: `~shlex.shlex ` instance or subclass instance is a lexical analyzer
78+ object. The initialization argument, if present, specifies where to read
79+ characters from. It must be a file-/stream-like object with
80+ :meth: `~io.TextIOBase.read ` and :meth: `~io.TextIOBase.readline ` methods, or
81+ a string. If no argument is given, input will be taken from ``sys.stdin ``.
82+ The second optional argument is a filename string, which sets the initial
83+ value of the :attr: `~shlex.infile ` attribute. If the *instream *
84+ argument is omitted or equal to ``sys.stdin ``, this second argument
85+ defaults to "stdin". The *posix * argument defines the operational mode:
86+ when *posix * is not true (default), the :class: `~shlex.shlex ` instance will
87+ operate in compatibility mode. When operating in POSIX mode,
88+ :class: `~shlex.shlex ` will try to be as close as possible to the POSIX shell
89+ parsing rules.
8790
8891
8992.. seealso ::
@@ -97,14 +100,14 @@ The :mod:`shlex` module defines the following class:
97100shlex Objects
98101-------------
99102
100- A :class: `shlex ` instance has the following methods:
103+ A :class: `~shlex. shlex
101104
102105
103106.. method :: shlex.get_token()
104107
105108 Return a token. If tokens have been stacked using :meth: `push_token `, pop a
106109 token off the stack. Otherwise, read one from the input stream. If reading
107- encounters an immediate end-of-file, :attr: `self. eof
110+ encounters an immediate end-of-file, :attr: `eof ` is returned (the empty
108111 string (``'' ``) in non-POSIX mode, and ``None `` in POSIX mode).
109112
110113
@@ -122,9 +125,9 @@ A :class:`shlex` instance has the following methods:
122125
123126.. method :: shlex.sourcehook(filename)
124127
125- When :class: `shlex ` detects a source request (see :attr: `source ` below) this
126- method is given the following token as argument, and expected to return a tuple
127- consisting of a filename and an open file-like object.
128+ When :class: `~ shlex.shlex :attr: `source `
129+ below) this method is given the following token as argument, and expected
130+ to return a tuple consisting of a filename and an open file-like object.
128131
129132 Normally, this method first strips any quotes off the argument. If the result
130133 is an absolute pathname, or there was no previous source request in effect, or
@@ -141,8 +144,9 @@ A :class:`shlex` instance has the following methods:
141144
142145 This hook is exposed so that you can use it to implement directory search paths,
143146 addition of file extensions, and other namespace hacks. There is no
144- corresponding 'close' hook, but a shlex instance will call the :meth: `close `
145- method of the sourced input stream when it returns EOF.
147+ corresponding 'close' hook, but a shlex instance will call the
148+ :meth: `~io.IOBase.close ` method of the sourced input stream when it returns
149+ EOF.
146150
147151 For more explicit control of source stacking, use the :meth: `push_source ` and
148152 :meth: `pop_source ` methods.
@@ -172,8 +176,8 @@ A :class:`shlex` instance has the following methods:
172176 messages in the standard, parseable format understood by Emacs and other Unix
173177 tools.
174178
175- Instances of :class: `shlex ` subclasses have some public instance variables which
176- either control lexical analysis or can be used for debugging:
179+ Instances of :class: `~ shlex.shlex
180+ variables which either control lexical analysis or can be used for debugging:
177181
178182
179183.. attribute :: shlex.commenters
@@ -218,8 +222,8 @@ either control lexical analysis or can be used for debugging:
218222.. attribute :: shlex.whitespace_split
219223
220224 If ``True ``, tokens will only be split in whitespaces. This is useful, for
221- example, for parsing command lines with :class: `shlex `, getting tokens in a
222- similar way to shell arguments.
225+ example, for parsing command lines with :class: `~ shlex.shlex
226+ tokens in a similar way to shell arguments.
223227
224228
225229.. attribute :: shlex.infile
@@ -231,7 +235,8 @@ either control lexical analysis or can be used for debugging:
231235
232236.. attribute :: shlex.instream
233237
234- The input stream from which this :class: `shlex ` instance is reading characters.
238+ The input stream from which this :class: `~shlex.shlex ` instance is reading
239+ characters.
235240
236241
237242.. attribute :: shlex.source
@@ -240,16 +245,16 @@ either control lexical analysis or can be used for debugging:
240245 string will be recognized as a lexical-level inclusion request similar to the
241246 ``source `` keyword in various shells. That is, the immediately following token
242247 will opened as a filename and input taken from that stream until EOF, at which
243- point the :meth: `close ` method of that stream will be called and the input
244- source will again become the original input stream. Source requests may be
245- stacked any number of levels deep.
248+ point the :meth: `~io.IOBase. close
249+ the input source will again become the original input stream. Source
250+ requests may be stacked any number of levels deep.
246251
247252
248253.. attribute :: shlex.debug
249254
250- If this attribute is numeric and ``1 `` or more, a :class: `shlex ` instance will
251- print verbose progress output on its behavior. If you need to use this, you can
252- read the module source code to learn the details.
255+ If this attribute is numeric and ``1 `` or more, a :class: `~ shlex.shlex `
256+ instance will print verbose progress output on its behavior. If you need
257+ to use this, you can read the module source code to learn the details.
253258
254259
255260.. attribute :: shlex.lineno
@@ -273,7 +278,7 @@ either control lexical analysis or can be used for debugging:
273278Parsing Rules
274279-------------
275280
276- When operating in non-POSIX mode, :class: `shlex ` will try to obey to the
281+ When operating in non-POSIX mode, :class: `~shlex. shlex
277282following rules.
278283
279284* Quote characters are not recognized within words (``Do"Not"Separate `` is
@@ -287,31 +292,34 @@ following rules.
287292* Closing quotes separate words (``"Do"Separate `` is parsed as ``"Do" `` and
288293 ``Separate ``);
289294
290- * If :attr: `whitespace_split ` is ``False ``, any character not declared to be a
291- word character, whitespace, or a quote will be returned as a single-character
292- token. If it is ``True ``, :class: `shlex ` will only split words in whitespaces;
295+ * If :attr: `~shlex.whitespace_split ` is ``False ``, any character not
296+ declared to be a word character, whitespace, or a quote will be returned as
297+ a single-character token. If it is ``True ``, :class: `~shlex.shlex ` will only
298+ split words in whitespaces;
293299
294300* EOF is signaled with an empty string (``'' ``);
295301
296302* It's not possible to parse empty strings, even if quoted.
297303
298- When operating in POSIX mode, :class: `shlex ` will try to obey to the following
299- parsing rules.
304+ When operating in POSIX mode, :class: `~ shlex.shlex
305+ following parsing rules.
300306
301307* Quotes are stripped out, and do not separate words (``"Do"Not"Separate" `` is
302308 parsed as the single word ``DoNotSeparate ``);
303309
304310* Non-quoted escape characters (e.g. ``'\' ``) preserve the literal value of the
305311 next character that follows;
306312
307- * Enclosing characters in quotes which are not part of :attr: `escapedquotes `
308- (e.g. ``"'" ``) preserve the literal value of all characters within the quotes;
313+ * Enclosing characters in quotes which are not part of
314+ :attr: `~shlex.escapedquotes ` (e.g. ``"'" ``) preserve the literal value
315+ of all characters within the quotes;
309316
310- * Enclosing characters in quotes which are part of :attr: `escapedquotes ` (e.g.
311- ``'"' ``) preserves the literal value of all characters within the quotes, with
312- the exception of the characters mentioned in :attr: `escape `. The escape
313- characters retain its special meaning only when followed by the quote in use, or
314- the escape character itself. Otherwise the escape character will be considered a
317+ * Enclosing characters in quotes which are part of
318+ :attr: `~shlex.escapedquotes ` (e.g. ``'"' ``) preserves the literal value
319+ of all characters within the quotes, with the exception of the characters
320+ mentioned in :attr: `~shlex.escape `. The escape characters retain its
321+ special meaning only when followed by the quote in use, or the escape
322+ character itself. Otherwise the escape character will be considered a
315323 normal character.
316324
317325* EOF is signaled with a :const: `None ` value;
0 commit comments