2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
.. _introduction:
|
|
|
|
|
|
|
|
************
|
|
|
|
Introduction
|
|
|
|
************
|
|
|
|
|
|
|
|
This reference manual describes the Python programming language. It is not
|
|
|
|
intended as a tutorial.
|
|
|
|
|
|
|
|
While I am trying to be as precise as possible, I chose to use English rather
|
|
|
|
than formal specifications for everything except syntax and lexical analysis.
|
|
|
|
This should make the document more understandable to the average reader, but
|
|
|
|
will leave room for ambiguities. Consequently, if you were coming from Mars and
|
|
|
|
tried to re-implement Python from this document alone, you might have to guess
|
|
|
|
things and in fact you would probably end up implementing quite a different
|
|
|
|
language. On the other hand, if you are using Python and wonder what the precise
|
|
|
|
rules about a particular area of the language are, you should definitely be able
|
|
|
|
to find them here. If you would like to see a more formal definition of the
|
|
|
|
language, maybe you could volunteer your time --- or invent a cloning machine
|
|
|
|
:-).
|
|
|
|
|
|
|
|
It is dangerous to add too many implementation details to a language reference
|
|
|
|
document --- the implementation may change, and other implementations of the
|
2007-08-31 05:07:45 -03:00
|
|
|
same language may work differently. On the other hand, CPython is the one
|
|
|
|
Python implementation in widespread use (although alternate implementations
|
|
|
|
continue to gain support), and its particular quirks are sometimes worth being
|
|
|
|
mentioned, especially where the implementation imposes additional limitations.
|
|
|
|
Therefore, you'll find short "implementation notes" sprinkled throughout the
|
|
|
|
text.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
Every Python implementation comes with a number of built-in and standard
|
|
|
|
modules. These are documented in :ref:`library-index`. A few built-in modules
|
|
|
|
are mentioned when they interact in a significant way with the language
|
|
|
|
definition.
|
|
|
|
|
|
|
|
|
|
|
|
.. _implementations:
|
|
|
|
|
|
|
|
Alternate Implementations
|
|
|
|
=========================
|
|
|
|
|
|
|
|
Though there is one Python implementation which is by far the most popular,
|
|
|
|
there are some alternate implementations which are of particular interest to
|
|
|
|
different audiences.
|
|
|
|
|
|
|
|
Known implementations include:
|
|
|
|
|
|
|
|
CPython
|
|
|
|
This is the original and most-maintained implementation of Python, written in C.
|
|
|
|
New language features generally appear here first.
|
|
|
|
|
|
|
|
Jython
|
|
|
|
Python implemented in Java. This implementation can be used as a scripting
|
|
|
|
language for Java applications, or can be used to create applications using the
|
|
|
|
Java class libraries. It is also often used to create tests for Java libraries.
|
|
|
|
More information can be found at `the Jython website <http://www.jython.org/>`_.
|
|
|
|
|
|
|
|
Python for .NET
|
|
|
|
This implementation actually uses the CPython implementation, but is a managed
|
2007-11-11 21:32:03 -04:00
|
|
|
.NET application and makes .NET libraries available. It was created by Brian
|
2007-08-15 11:28:22 -03:00
|
|
|
Lloyd. For more information, see the `Python for .NET home page
|
2016-02-04 00:05:46 -04:00
|
|
|
<https://pythonnet.github.io/>`_.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
IronPython
|
|
|
|
An alternate Python for .NET. Unlike Python.NET, this is a complete Python
|
|
|
|
implementation that generates IL, and compiles Python code directly to .NET
|
|
|
|
assemblies. It was created by Jim Hugunin, the original creator of Jython. For
|
2014-10-29 06:26:56 -03:00
|
|
|
more information, see `the IronPython website <http://ironpython.net/>`_.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
PyPy
|
Merged revisions 80605-80609,80642-80646,80651-80652,80674,80684-80686,80748,80852,80854,80870,80872-80873,80907,80915-80916,80951-80952,80976-80977,80985,81038-81040,81042,81053,81070,81104-81105,81114,81125,81245,81285,81402,81463,81516,81562-81563,81567,81593,81635,81680-81681,81684,81801,81888,81931-81933,81939-81942,81963,81984,81991,82120,82188,82264-82267 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r80605 | andrew.kuchling | 2010-04-28 19:22:16 -0500 (Wed, 28 Apr 2010) | 1 line
Add various items
........
r80606 | andrew.kuchling | 2010-04-28 20:44:30 -0500 (Wed, 28 Apr 2010) | 6 lines
Fix doubled 'the'.
Markup fixes to use :exc:, :option: in a few places.
(Glitch: unittest.main's -c ends up a link to the Python
interpreter's -c option. Should we skip using :option: for that
switch, or disable the auto-linking somehow?)
........
r80607 | andrew.kuchling | 2010-04-28 20:45:41 -0500 (Wed, 28 Apr 2010) | 1 line
Add various unittest items
........
r80608 | benjamin.peterson | 2010-04-28 22:18:05 -0500 (Wed, 28 Apr 2010) | 1 line
update pypy description
........
r80609 | benjamin.peterson | 2010-04-28 22:30:59 -0500 (Wed, 28 Apr 2010) | 1 line
update pypy url
........
r80642 | andrew.kuchling | 2010-04-29 19:49:09 -0500 (Thu, 29 Apr 2010) | 1 line
Always add space after RFC; reword paragraph
........
r80643 | andrew.kuchling | 2010-04-29 19:52:31 -0500 (Thu, 29 Apr 2010) | 6 lines
Reword paragraph to make its meaning clearer.
Antoine Pitrou: is my version of the paragraph still correct?
R. David Murray: is this more understandable than the previous version?
........
r80644 | andrew.kuchling | 2010-04-29 20:02:15 -0500 (Thu, 29 Apr 2010) | 1 line
Fix typos
........
r80645 | andrew.kuchling | 2010-04-29 20:32:47 -0500 (Thu, 29 Apr 2010) | 1 line
Markup fix; clarify by adding 'in that order'
........
r80646 | andrew.kuchling | 2010-04-29 20:33:40 -0500 (Thu, 29 Apr 2010) | 1 line
Add various items; rearrange unittest section a bit
........
r80651 | andrew.kuchling | 2010-04-30 08:46:55 -0500 (Fri, 30 Apr 2010) | 1 line
Minor grammar re-wording
........
r80652 | andrew.kuchling | 2010-04-30 08:47:34 -0500 (Fri, 30 Apr 2010) | 1 line
Add item
........
r80674 | andrew.kuchling | 2010-04-30 20:19:16 -0500 (Fri, 30 Apr 2010) | 1 line
Add various items
........
r80684 | andrew.kuchling | 2010-05-01 07:05:52 -0500 (Sat, 01 May 2010) | 1 line
Minor grammar fix
........
r80685 | andrew.kuchling | 2010-05-01 07:06:51 -0500 (Sat, 01 May 2010) | 1 line
Describe memoryview
........
r80686 | antoine.pitrou | 2010-05-01 07:16:39 -0500 (Sat, 01 May 2010) | 4 lines
Fix attribution. Travis didn't do much and he did a bad work.
(yes, this is a sensitive subject, sorry)
........
r80748 | andrew.kuchling | 2010-05-03 20:24:22 -0500 (Mon, 03 May 2010) | 1 line
Add some more items; the urlparse change is added twice
........
r80852 | andrew.kuchling | 2010-05-05 20:09:47 -0500 (Wed, 05 May 2010) | 1 line
Reword paragraph; fix filename, which should be pyconfig.h
........
r80854 | andrew.kuchling | 2010-05-05 20:10:56 -0500 (Wed, 05 May 2010) | 1 line
Add various items
........
r80870 | andrew.kuchling | 2010-05-06 09:14:09 -0500 (Thu, 06 May 2010) | 1 line
Describe ElementTree 1.3; rearrange new-module sections; describe dict views as sets; small edits and items
........
r80872 | andrew.kuchling | 2010-05-06 12:21:59 -0500 (Thu, 06 May 2010) | 1 line
Add 2 items; record ideas for two initial sections; clarify wording
........
r80873 | andrew.kuchling | 2010-05-06 12:27:57 -0500 (Thu, 06 May 2010) | 1 line
Change section title; point to unittest2
........
r80907 | andrew.kuchling | 2010-05-06 20:45:14 -0500 (Thu, 06 May 2010) | 1 line
Add a new section on the development plan; add an item
........
r80915 | antoine.pitrou | 2010-05-07 05:15:51 -0500 (Fri, 07 May 2010) | 3 lines
Fix some markup and a class name. Also, wrap a long line.
........
r80916 | andrew.kuchling | 2010-05-07 06:30:47 -0500 (Fri, 07 May 2010) | 1 line
Re-word text
........
r80951 | andrew.kuchling | 2010-05-07 20:15:26 -0500 (Fri, 07 May 2010) | 1 line
Add two items
........
r80952 | andrew.kuchling | 2010-05-07 20:35:55 -0500 (Fri, 07 May 2010) | 1 line
Get accents correct
........
r80976 | andrew.kuchling | 2010-05-08 08:28:03 -0500 (Sat, 08 May 2010) | 1 line
Add logging.dictConfig example; give up on writing a Ttk example
........
r80977 | andrew.kuchling | 2010-05-08 08:29:46 -0500 (Sat, 08 May 2010) | 1 line
Markup fixes
........
r80985 | andrew.kuchling | 2010-05-08 10:39:46 -0500 (Sat, 08 May 2010) | 7 lines
Write summary of the 2.7 release; rewrite the future section some more;
mention PYTHONWARNINGS env. var; tweak some examples for readability.
And with this commit, the "What's New" is done... except for a
complete read-through to polish the text, and fixing any reported errors,
but those tasks can easily wait until after beta2.
........
r81038 | benjamin.peterson | 2010-05-09 16:09:40 -0500 (Sun, 09 May 2010) | 1 line
finish clause
........
r81039 | andrew.kuchling | 2010-05-10 09:18:27 -0500 (Mon, 10 May 2010) | 1 line
Markup fix; re-word a sentence
........
r81040 | andrew.kuchling | 2010-05-10 09:20:12 -0500 (Mon, 10 May 2010) | 1 line
Use title case
........
r81042 | andrew.kuchling | 2010-05-10 10:03:35 -0500 (Mon, 10 May 2010) | 1 line
Link to unittest2 article
........
r81053 | florent.xicluna | 2010-05-10 14:59:22 -0500 (Mon, 10 May 2010) | 2 lines
Add a link on maketrans().
........
r81070 | andrew.kuchling | 2010-05-10 18:13:41 -0500 (Mon, 10 May 2010) | 1 line
Fix typo
........
r81104 | andrew.kuchling | 2010-05-11 19:38:44 -0500 (Tue, 11 May 2010) | 1 line
Revision pass: lots of edits, typo fixes, rearrangements
........
r81105 | andrew.kuchling | 2010-05-11 19:40:47 -0500 (Tue, 11 May 2010) | 1 line
Let's call this done
........
r81114 | andrew.kuchling | 2010-05-12 08:56:07 -0500 (Wed, 12 May 2010) | 1 line
Grammar fix
........
r81125 | andrew.kuchling | 2010-05-12 13:56:48 -0500 (Wed, 12 May 2010) | 1 line
#8696: add documentation for logging.config.dictConfig (PEP 391)
........
r81245 | andrew.kuchling | 2010-05-16 18:31:16 -0500 (Sun, 16 May 2010) | 1 line
Add cross-reference to later section
........
r81285 | vinay.sajip | 2010-05-18 03:16:27 -0500 (Tue, 18 May 2010) | 1 line
Fixed minor typo in ReST markup.
........
r81402 | vinay.sajip | 2010-05-21 12:41:34 -0500 (Fri, 21 May 2010) | 1 line
Updated logging documentation with more dictConfig information.
........
r81463 | georg.brandl | 2010-05-22 03:17:23 -0500 (Sat, 22 May 2010) | 1 line
#8785: less confusing description of regex.find*.
........
r81516 | andrew.kuchling | 2010-05-25 08:34:08 -0500 (Tue, 25 May 2010) | 1 line
Add three items
........
r81562 | andrew.kuchling | 2010-05-27 08:22:53 -0500 (Thu, 27 May 2010) | 1 line
Rewrite wxWidgets section
........
r81563 | andrew.kuchling | 2010-05-27 08:30:09 -0500 (Thu, 27 May 2010) | 1 line
Remove top-level 'General Questions' section, pushing up the questions it contains
........
r81567 | andrew.kuchling | 2010-05-27 16:29:59 -0500 (Thu, 27 May 2010) | 1 line
Add item
........
r81593 | georg.brandl | 2010-05-29 03:46:18 -0500 (Sat, 29 May 2010) | 1 line
#8616: add new turtle demo "nim".
........
r81635 | georg.brandl | 2010-06-01 02:25:23 -0500 (Tue, 01 Jun 2010) | 1 line
Put docs for RegexObject.search() before RegexObject.match() to mirror re.search() and re.match() order.
........
r81680 | vinay.sajip | 2010-06-03 17:34:42 -0500 (Thu, 03 Jun 2010) | 1 line
Issue #8890: Documentation changed to avoid reference to temporary files.
........
r81681 | sean.reifschneider | 2010-06-03 20:51:26 -0500 (Thu, 03 Jun 2010) | 2 lines
Issue8810: Clearing up docstring for tzinfo.utcoffset.
........
r81684 | vinay.sajip | 2010-06-04 08:41:02 -0500 (Fri, 04 Jun 2010) | 1 line
Issue #8890: Documentation changed to avoid reference to temporary files - other cases covered.
........
r81801 | andrew.kuchling | 2010-06-07 08:38:40 -0500 (Mon, 07 Jun 2010) | 1 line
#8875: Remove duplicated paragraph
........
r81888 | andrew.kuchling | 2010-06-10 20:54:58 -0500 (Thu, 10 Jun 2010) | 1 line
Add a few more items
........
r81931 | georg.brandl | 2010-06-12 01:26:54 -0500 (Sat, 12 Jun 2010) | 1 line
Fix punctuation.
........
r81932 | georg.brandl | 2010-06-12 01:28:58 -0500 (Sat, 12 Jun 2010) | 1 line
Document that an existing directory raises in mkdir().
........
r81933 | georg.brandl | 2010-06-12 01:45:33 -0500 (Sat, 12 Jun 2010) | 1 line
Update version in README.
........
r81939 | georg.brandl | 2010-06-12 04:45:01 -0500 (Sat, 12 Jun 2010) | 1 line
Use newer toctree syntax.
........
r81940 | georg.brandl | 2010-06-12 04:45:28 -0500 (Sat, 12 Jun 2010) | 1 line
Add document on how to build.
........
r81941 | georg.brandl | 2010-06-12 04:45:58 -0500 (Sat, 12 Jun 2010) | 1 line
Fix gratuitous indentation.
........
r81942 | georg.brandl | 2010-06-12 04:46:03 -0500 (Sat, 12 Jun 2010) | 1 line
Update README.
........
r81963 | andrew.kuchling | 2010-06-12 15:00:55 -0500 (Sat, 12 Jun 2010) | 1 line
Grammar fix
........
r81984 | georg.brandl | 2010-06-14 10:58:39 -0500 (Mon, 14 Jun 2010) | 1 line
#8993: fix reference.
........
r81991 | andrew.kuchling | 2010-06-14 19:38:58 -0500 (Mon, 14 Jun 2010) | 1 line
Add another bunch of items
........
r82120 | andrew.kuchling | 2010-06-20 16:45:45 -0500 (Sun, 20 Jun 2010) | 1 line
Note that Python 3.x isn't covered; add forward ref. for UTF-8; note error in 2.5 and up
........
r82188 | benjamin.peterson | 2010-06-23 19:02:46 -0500 (Wed, 23 Jun 2010) | 1 line
remove reverted changed
........
r82264 | georg.brandl | 2010-06-27 05:47:47 -0500 (Sun, 27 Jun 2010) | 1 line
Confusing punctuation.
........
r82265 | georg.brandl | 2010-06-27 05:49:23 -0500 (Sun, 27 Jun 2010) | 1 line
Use designated syntax for optional grammar element.
........
r82266 | georg.brandl | 2010-06-27 05:51:44 -0500 (Sun, 27 Jun 2010) | 1 line
Fix URL.
........
r82267 | georg.brandl | 2010-06-27 05:55:38 -0500 (Sun, 27 Jun 2010) | 1 line
Two typos.
........
2010-06-27 19:32:30 -03:00
|
|
|
An implementation of Python written completely in Python. It supports several
|
|
|
|
advanced features not found in other implementations like stackless support
|
|
|
|
and a Just in Time compiler. One of the goals of the project is to encourage
|
|
|
|
experimentation with the language itself by making it easier to modify the
|
|
|
|
interpreter (since it is written in Python). Additional information is
|
|
|
|
available on `the PyPy project's home page <http://pypy.org/>`_.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
Each of these implementations varies in some way from the language as documented
|
|
|
|
in this manual, or introduces specific information beyond what's covered in the
|
|
|
|
standard Python documentation. Please refer to the implementation-specific
|
|
|
|
documentation to determine what else you need to know about the specific
|
|
|
|
implementation you're using.
|
|
|
|
|
|
|
|
|
|
|
|
.. _notation:
|
|
|
|
|
|
|
|
Notation
|
|
|
|
========
|
|
|
|
|
2007-08-31 05:07:45 -03:00
|
|
|
.. index:: BNF, grammar, syntax, notation
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
The descriptions of lexical analysis and syntax use a modified BNF grammar
|
|
|
|
notation. This uses the following style of definition:
|
|
|
|
|
[3.9] bpo-40204: Allow pre-Sphinx 3 syntax in the doc (GH-21844) (GH-21901)
* bpo-40204: Allow pre-Sphinx 3 syntax in the doc (GH-21844)
Enable Sphinx 3.2 "c_allow_pre_v3" option and disable the
c_warn_on_allowed_pre_v3 option to make the documentation compatible
with Sphinx 2 and Sphinx 3.
(cherry picked from commit 423e77d6de497931585d1883805a9e3fa4096b0b)
* bpo-40204: Fix Sphinx sytanx in howto/instrumentation.rst (GH-21858)
Use generic '.. object::' to declare markers, rather than abusing
'.. c:function::' which fails on Sphinx 3.
(cherry picked from commit 43577c01a2ab49122db696e9eaec6cb31d11cc81)
* bpo-40204: Fix duplicates in the documentation (GH-21857)
Fix two Sphinx 3 issues:
Doc/c-api/buffer.rst:304: WARNING: Duplicate C declaration, also defined in 'c-api/buffer'.
Declaration is 'PyBUF_ND'.
Doc/c-api/unicode.rst:1603: WARNING: Duplicate C declaration, also defined in 'c-api/unicode'.
Declaration is 'PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)'.
(cherry picked from commit 46d10b1237c67ff8347f533eda6a5468d098f7eb)
* bpo-40204: Add :noindex: in the documentation (GH-21859)
Add :noindex: to duplicated documentation to fix "duplicate object
description" errors.
For example, fix this Sphinx 3 issue:
Doc/library/configparser.rst:1146: WARNING: duplicate object
description of configparser.ConfigParser.optionxform, other instance
in library/configparser, use :noindex: for one of them
(cherry picked from commit d3ded080482beae578faa704b13534a62d066f9f)
* bpo-40204, doc: Fix syntax of C variables (GH-21846)
For example, fix the following Sphinx 3 errors:
Doc/c-api/buffer.rst:102: WARNING: Error in declarator or parameters
Invalid C declaration: Expected identifier in nested name. [error at 5]
void \*obj
-----^
Doc/c-api/arg.rst:130: WARNING: Unparseable C cross-reference: 'PyObject*'
Invalid C declaration: Expected end of definition. [error at 8]
PyObject*
--------^
The modified documentation is compatible with Sphinx 2 and Sphinx 3.
(cherry picked from commit 474652fe9346382dbf793f20b671eb74668bebde)
* bpo-40204: Fix reference to terms in the doc (GH-21865)
Sphinx 3 requires to refer to terms with the exact case.
For example, fix the Sphinx 3 warning:
Doc/library/pkgutil.rst:71: WARNING: term Loader not found in case
sensitive match.made a reference to loader instead.
(cherry picked from commit bb0b08540cc93e56f3f1bde1b39ce086d9e35fe1)
* bpo-40204: Fix duplicated productionlist names in the doc (GH-21900)
Sphinx 3 disallows having more than one productionlist markup with
the same name. Simply remove names in this case, since names are not
shown anyway. For example, fix the Sphinx 3 warning:
Doc/reference/introduction.rst:96: duplicate token description
of *:name, other instance in reference/expressions
(cherry picked from commit 1abeda80f760134b4233608e2c288790f955b95a)
2020-08-19 14:25:22 -03:00
|
|
|
.. productionlist::
|
2007-08-15 11:28:22 -03:00
|
|
|
name: `lc_letter` (`lc_letter` | "_")*
|
|
|
|
lc_letter: "a"..."z"
|
|
|
|
|
|
|
|
The first line says that a ``name`` is an ``lc_letter`` followed by a sequence
|
|
|
|
of zero or more ``lc_letter``\ s and underscores. An ``lc_letter`` in turn is
|
|
|
|
any of the single characters ``'a'`` through ``'z'``. (This rule is actually
|
|
|
|
adhered to for the names defined in lexical and grammar rules in this document.)
|
|
|
|
|
|
|
|
Each rule begins with a name (which is the name defined by the rule) and
|
|
|
|
``::=``. A vertical bar (``|``) is used to separate alternatives; it is the
|
|
|
|
least binding operator in this notation. A star (``*``) means zero or more
|
|
|
|
repetitions of the preceding item; likewise, a plus (``+``) means one or more
|
|
|
|
repetitions, and a phrase enclosed in square brackets (``[ ]``) means zero or
|
|
|
|
one occurrences (in other words, the enclosed phrase is optional). The ``*``
|
|
|
|
and ``+`` operators bind as tightly as possible; parentheses are used for
|
|
|
|
grouping. Literal strings are enclosed in quotes. White space is only
|
|
|
|
meaningful to separate tokens. Rules are normally contained on a single line;
|
|
|
|
rules with many alternatives may be formatted alternatively with each line after
|
|
|
|
the first beginning with a vertical bar.
|
|
|
|
|
2007-08-31 05:07:45 -03:00
|
|
|
.. index:: lexical definitions, ASCII
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
In lexical definitions (as the example above), two more conventions are used:
|
|
|
|
Two literal characters separated by three dots mean a choice of any single
|
|
|
|
character in the given (inclusive) range of ASCII characters. A phrase between
|
|
|
|
angular brackets (``<...>``) gives an informal description of the symbol
|
|
|
|
defined; e.g., this could be used to describe the notion of 'control character'
|
|
|
|
if needed.
|
|
|
|
|
|
|
|
Even though the notation used is almost the same, there is a big difference
|
|
|
|
between the meaning of lexical and syntactic definitions: a lexical definition
|
|
|
|
operates on the individual characters of the input source, while a syntax
|
|
|
|
definition operates on the stream of tokens generated by the lexical analysis.
|
|
|
|
All uses of BNF in the next chapter ("Lexical Analysis") are lexical
|
|
|
|
definitions; uses in subsequent chapters are syntactic definitions.
|
|
|
|
|