rest25/reference/lexical_analysis.rst => rest262/reference/lexical_analysis.rst
70.. _physical:
71
72Physical lines
73--------------
74
75A physical line is a sequence of characters terminated by an end-of-line
76sequence.  In source files, any of the standard platform line termination
77sequences can be used - the Unix form using ASCII LF (linefeed), the Windows
n78-form using the ASCII sequence CR LF (return followed by linefeed), or the
n78+form using the ASCII sequence CR LF (return followed by linefeed), or the old
79Macintosh form using the ASCII CR (return) character.  All of these forms can be
80used equally, regardless of platform.
81
82When embedding Python, source code strings should be passed to Python APIs using
83the standard C conventions for newline characters (the ``\n`` character,
84representing ASCII LF, is the line terminator).
85
86
126
127If an encoding is declared, the encoding name must be recognized by Python. The
128encoding is used for all lexical analysis, in particular to find the end of a
129string, and to interpret the contents of Unicode literals. String literals are
130converted to Unicode for syntactical analysis, then converted back to their
131original encoding before interpretation starts. The encoding declaration must
132appear on a line of its own.
133
n134-.. % XXX there should be a list of supported encodings.
n134+.. XXX there should be a list of supported encodings.
135
136
137.. _explicit-joining:
138
139Explicit line joining
140---------------------
141
142.. index::
144   single: line joining
145   single: line continuation
146   single: backslash character
147
148Two or more physical lines may be joined into logical lines using backslash
149characters (``\``), as follows: when a physical line ends in a backslash that is
150not part of a string literal or comment, it is joined with the following forming
151a single logical line, deleting the backslash and the following end-of-line
n152-character.  For example:
n152+character.  For example::
153- 
154-.. % 
155- 
156-::
157
158   if 1900 < year < 2100 and 1 <= month <= 12 \
159      and 1 <= day <= 31 and 0 <= hour < 24 \
160      and 0 <= minute < 60 and 0 <= second < 60:   # Looks like a valid date
161           return 1
162
163A line ending in a backslash cannot carry a comment.  A backslash does not
164continue a comment.  A backslash does not continue a token except for string
318.. index::
319   single: identifier
320   single: name
321
322Identifiers (also referred to as *names*) are described by the following lexical
323definitions:
324
325.. productionlist::
n326-   identifier: (`letter`\|"_") (`letter` \| `digit` \| "_")\*
n322+   identifier: (`letter`|"_") (`letter` | `digit` | "_")*
327-   letter: `lowercase` \| `uppercase`
323+   letter: `lowercase` | `uppercase`
328   lowercase: "a"..."z"
329   uppercase: "A"..."Z"
330   digit: "0"..."9"
331
332Identifiers are unlimited in length.  Case is significant.
333
334
335.. _keywords:
338--------
339
340.. index::
341   single: keyword
342   single: reserved word
343
344The following identifiers are used as reserved words, or *keywords* of the
345language, and cannot be used as ordinary identifiers.  They must be spelled
n346-exactly as written here:
n342+exactly as written here::
347
n348-.. % 
349-.. % 
350- 
351-::
352- 
353-   and       del       from      not       while    
344+   and       del       from      not       while
354-   as        elif      global    or        with     
345+   as        elif      global    or        with
355-   assert    else      if        pass      yield    
346+   assert    else      if        pass      yield
356-   break     except    import    print              
347+   break     except    import    print
357-   class     exec      in        raise              
348+   class     exec      in        raise
358-   continue  finally   is        return             
349+   continue  finally   is        return
359-   def       for       lambda    try 
350+   def       for       lambda    try
360- 
361-.. % When adding keywords, use reswords.py for reformatting
362
363.. versionchanged:: 2.4
364   :const:`None` became a constant and is now recognized by the compiler as a name
365   for the built-in object :const:`None`.  Although it is not a keyword, you cannot
366   assign a different object to it.
367
368.. versionchanged:: 2.5
369   Both :keyword:`as` and :keyword:`with` are only recognized when the
381Certain classes of identifiers (besides keywords) have special meanings.  These
382classes are identified by the patterns of leading and trailing underscore
383characters:
384
385``_*``
386   Not imported by ``from module import *``.  The special identifier ``_`` is used
387   in the interactive interpreter to store the result of the last evaluation; it is
388   stored in the :mod:`__builtin__` module.  When not in interactive mode, ``_``
n389-   has no special meaning and is not defined. See section :ref:`import`, "The
n378+   has no special meaning and is not defined. See section :ref:`import`.
390-   :keyword:`import` statement."
391
392   .. note::
393
n394-      The name ``_`` is often used in conjunction with internationalization; refer to
n382+      The name ``_`` is often used in conjunction with internationalization;
395-      the documentation for the :mod:`gettext` module (XXX reference: ../lib/module-
383+      refer to the documentation for the :mod:`gettext` module for more
396-      gettext.html) for more information on this convention.
384+      information on this convention.
397
398``__*__``
399   System-defined names.  These names are defined by the interpreter and its
400   implementation (including the standard library); applications should not expect
401   to define additional names using this convention.  The set of names of this
402   class defined by Python may be extended in future versions. See section
n403-   :ref:`specialnames`, "Special method names."
n391+   :ref:`specialnames`.
404
405``__*``
406   Class-private names.  Names in this category, when used within the context of a
407   class definition, are re-written to use a mangled form to help avoid name
408   clashes between "private" attributes of base and derived classes. See section
n409-   :ref:`atom-identifiers`, "Identifiers (Names)."
n397+   :ref:`atom-identifiers`.
410
411
412.. _literals:
413
414Literals
415========
416
417.. index::
428
429.. index:: single: string literal
430
431String literals are described by the following lexical definitions:
432
433.. index:: single: ASCII@ASCII
434
435.. productionlist::
n436-   stringliteral: [`stringprefix`](`shortstring` \| `longstring`)
n424+   stringliteral: [`stringprefix`](`shortstring` | `longstring`)
437-   stringprefix: "r" \| "u" \| "ur" \| "R" \| "U" \| "UR" \| "Ur" \| "uR"
425+   stringprefix: "r" | "u" | "ur" | "R" | "U" | "UR" | "Ur" | "uR"
438-   shortstring: "'" `shortstringitem`\* "'" \| '"' `shortstringitem`\* '"'
426+   shortstring: "'" `shortstringitem`* "'" | '"' `shortstringitem`* '"'
439-   longstring: ""'" `longstringitem`\""'"
427+   longstring: "'''" `longstringitem`* "'''"
440-             : \| '"""' `longstringitem`\* '"""'
428+             : | '"""' `longstringitem`* '"""'
441-   shortstringitem: `shortstringchar` \| `escapeseq`
429+   shortstringitem: `shortstringchar` | `escapeseq`
442-   longstringitem: `longstringchar` \| `escapeseq`
430+   longstringitem: `longstringchar` | `escapeseq`
443   shortstringchar: <any source character except "\" or newline or the quote>
444   longstringchar: <any source character except "\">
445   escapeseq: "\" <any ASCII character>
446
447One syntactic restriction not indicated by these productions is that whitespace
448is not allowed between the :token:`stringprefix` and the rest of the string
449literal. The source character set is defined by the encoding declaration; it is
450ASCII if no encoding declaration is given in the source file; see section
453.. index::
454   single: triple-quoted string
455   single: Unicode Consortium
456   single: string; Unicode
457   single: raw string
458
459In plain English: String literals can be enclosed in matching single quotes
460(``'``) or double quotes (``"``).  They can also be enclosed in matching groups
n461-of three single or double quotes (these are generally referred to as *triple-
n449+of three single or double quotes (these are generally referred to as
462-quoted strings*).  The backslash (``\``) character is used to escape characters
450+*triple-quoted strings*).  The backslash (``\``) character is used to escape
463-that otherwise have a special meaning, such as newline, backslash itself, or the
451+characters that otherwise have a special meaning, such as newline, backslash
464-quote character.  String literals may optionally be prefixed with a letter
452+itself, or the quote character.  String literals may optionally be prefixed with
465-``'r'`` or ``'R'``; such strings are called :dfn:`raw strings` and use different
453+a letter ``'r'`` or ``'R'``; such strings are called :dfn:`raw strings` and use
466-rules for interpreting backslash escape sequences.  A prefix of ``'u'`` or
454+different rules for interpreting backslash escape sequences.  A prefix of
467-``'U'`` makes the string a Unicode string.  Unicode strings use the Unicode
455+``'u'`` or ``'U'`` makes the string a Unicode string.  Unicode strings use the
468-character set as defined by the Unicode Consortium and ISO 10646.  Some
456+Unicode character set as defined by the Unicode Consortium and ISO 10646.  Some
469additional escape sequences, described below, are available in Unicode strings.
470The two prefix characters may be combined; in this case, ``'u'`` must appear
471before ``'r'``.
472
473In triple-quoted strings, unescaped newlines and quotes are allowed (and are
474retained), except that three unescaped quotes in a row terminate the string.  (A
475"quote" is the character used to open the string, i.e. either ``'`` or ``"``.)
476
537   Multilingual Plane (BMP) will be encoded using a surrogate pair if Python is
538   compiled to use 16-bit code units (the default).  Individual code units which
539   form parts of a surrogate pair can be encoded using this escape sequence.
540
541(3)
542   As in Standard C, up to three octal digits are accepted.
543
544(4)
n545-   Unlike in Standard C, at most two hex digits are accepted.
n533+   Unlike in Standard C, exactly two hex digits are required.
546
547(5)
548   In a string literal, hexadecimal and octal escapes denote the byte with the
549   given value; it is not necessary that the byte encodes a character in the source
550   character set. In a Unicode literal, these escapes denote a Unicode character
551   with the given value.
552
553.. index:: single: unrecognized escape sequence
612.. index::
613   single: number
614   single: numeric literal
615   single: integer literal
616   single: plain integer literal
617   single: long integer literal
618   single: floating point literal
619   single: hexadecimal literal
n608+   single: binary literal
620   single: octal literal
621   single: decimal literal
622   single: imaginary literal
623   single: complex; literal
624
625There are four types of numeric literals: plain integers, long integers,
626floating point numbers, and imaginary numbers.  There are no complex literals
627(complex numbers can be formed by adding a real number and an imaginary number).
635
636Integer and long integer literals
637---------------------------------
638
639Integer and long integer literals are described by the following lexical
640definitions:
641
642.. productionlist::
n643-   longinteger: `integer` ("l" \| "L")
n632+   longinteger: `integer` ("l" | "L")
644-   integer: `decimalinteger` \| `octinteger` \| `hexinteger`
633+   integer: `decimalinteger` | `octinteger` | `hexinteger` | `bininteger`
645-   decimalinteger: `nonzerodigit` `digit`\\| "0"
634+   decimalinteger: `nonzerodigit` `digit`* | "0"
646-   octinteger: "0" `octdigit`\ +
635+   octinteger: "0" ("o" | "O") `octdigit`+ | "0" `octdigit`+
647-   hexinteger: "0" ("x" \| "X") `hexdigit`+
636+   hexinteger: "0" ("x" | "X") `hexdigit`+
637+   bininteger: "0" ("b" | "B") `bindigit`+
648   nonzerodigit: "1"..."9"
649   octdigit: "0"..."7"
n640+   bindigit: "0" | "1"
650-   hexdigit: `digit` \| "a"..."f" \| "A"..."F"
641+   hexdigit: `digit` | "a"..."f" | "A"..."F"
651
652Although both lower case ``'l'`` and upper case ``'L'`` are allowed as suffix
653for long integers, it is strongly recommended to always use ``'L'``, since the
654letter ``'l'`` looks too much like the digit ``'1'``.
655
656Plain integer literals that are above the largest representable plain integer
657(e.g., 2147483647 when using 32-bit arithmetic) are accepted as if they were
658long integers instead. [#]_  There is no limit for long integer literals apart
659from what can be stored in available memory.
660
661Some examples of plain integer literals (first row) and long integer literals
662(second and third rows)::
663
664   7     2147483647                        0177
665   3L    79228162514264337593543950336L    0377L   0x100000000L
n666-         79228162514264337593543950336             0xdeadbeef                                               
n657+         79228162514264337593543950336             0xdeadbeef
667
668
669.. _floating:
670
671Floating point literals
672-----------------------
673
674Floating point literals are described by the following lexical definitions:
675
676.. productionlist::
n677-   floatnumber: `pointfloat` \| `exponentfloat`
n668+   floatnumber: `pointfloat` | `exponentfloat`
678-   pointfloat: [`intpart`] `fraction` \| `intpart` "."
669+   pointfloat: [`intpart`] `fraction` | `intpart` "."
679-   exponentfloat: (`intpart` \| `pointfloat`) `exponent`
670+   exponentfloat: (`intpart` | `pointfloat`) `exponent`
680-   intpart: `digit`+
671+   intpart: `digit`+
681-   fraction: "." `digit`+
672+   fraction: "." `digit`+
682-   exponent: ("e" \| "E") ["+" \| "-"] `digit`+
673+   exponent: ("e" | "E") ["+" | "-"] `digit`+
683
684Note that the integer and exponent parts of floating point numbers can look like
685octal integers, but are interpreted using radix 10.  For example, ``077e010`` is
686legal, and denotes the same number as ``77e10``. The allowed range of floating
687point literals is implementation-dependent. Some examples of floating point
688literals::
689
690   3.14    10.    .001    1e100    3.14e-10    0e0
697.. _imaginary:
698
699Imaginary literals
700------------------
701
702Imaginary literals are described by the following lexical definitions:
703
704.. productionlist::
n705-   imagnumber: (`floatnumber` \| `intpart`) ("j" \| "J")
n696+   imagnumber: (`floatnumber` | `intpart`) ("j" | "J")
706
707An imaginary literal yields a complex number with a real part of 0.0.  Complex
708numbers are represented as a pair of floating point numbers and have the same
709restrictions on their range.  To create a complex number with a nonzero real
710part, add a floating point number to it, e.g., ``(3+4j)``.  Some examples of
711imaginary literals::
712
t713-   3.14j   10.j    10j     .001j   1e100j  3.14e-10j 
t704+   3.14j   10.j    10j     .001j   1e100j  3.14e-10j
714
715
716.. _operators:
717
718Operators
719=========
720
721.. index:: single: operators
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op