diff --git a/Doc/conf.py b/Doc/conf.py index c768e6fd676a5a3..4083001d218c93b 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -359,7 +359,13 @@ # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, document class [howto/manual]). latex_documents = [ - ('c-api/index', 'c-api.tex', 'The Python/C API', _doc_authors, 'manual'), + ( + 'c-api/index', + 'c-api.tex', + 'The Python/C API', + _doc_authors, + 'manual', + ), ( 'extending/index', 'extending.tex', @@ -374,6 +380,13 @@ _doc_authors, 'manual', ), + ( + 'library/builtin-index', + 'builtin.tex', + 'Built-in Functions and Classes', + _doc_authors, + 'manual', + ), ( 'library/index', 'library.tex', diff --git a/Doc/contents.rst b/Doc/contents.rst index b57f4b09a5dcb6a..132330e27d2286a 100644 --- a/Doc/contents.rst +++ b/Doc/contents.rst @@ -8,6 +8,7 @@ tutorial/index.rst using/index.rst reference/index.rst + library/builtin-index.rst library/index.rst extending/index.rst c-api/index.rst diff --git a/Doc/extending/index.rst b/Doc/extending/index.rst index c0c494c3059d99c..90a35c9cb9e3b29 100644 --- a/Doc/extending/index.rst +++ b/Doc/extending/index.rst @@ -16,9 +16,10 @@ underlying operating system supports this feature. This document assumes basic knowledge about C and Python. For an informal introduction to Python, see :ref:`tutorial-index`. :ref:`reference-index` -gives a more formal definition of the language. :ref:`library-index` documents -the existing object types, functions and modules (both built-in and written in -Python) that give the language its wide application range. +gives a more formal definition of the language. :ref:`builtin-index` documents +the built-in functions and object types, and :ref:`library-index` documents the +modules (both built-in and written in Python) that give the language its wide +application range. For a detailed description of the whole Python/C API, see the separate :ref:`c-api-index`. diff --git a/Doc/library/builtin-index.rst b/Doc/library/builtin-index.rst new file mode 100644 index 000000000000000..b72598c9fea6ee3 --- /dev/null +++ b/Doc/library/builtin-index.rst @@ -0,0 +1,30 @@ +.. _builtin-index: + +####################### + Built-ins reference +####################### + +Python comes with a number of built-in functions and classes. + +The built-in classes include data types that would normally be considered part +of the "core" of a language, such as numbers and lists. For these types, the +Python language core defines the form of literals and places some constraints +on their semantics, but does not fully define the semantics. + +The built-ins also include functions and exceptions --- objects that can +be used by all Python code without the need of an :keyword:`import` statement. +Some of these are defined by the core language, but many are not essential for +the core semantics and are only described here. + +.. We don't use :numbered: option for the TOC below as it enforces + numbered sections for the entire builtin docs. If desired, + :numbered: can be enabled on a per-page basis. +.. toctree:: + :maxdepth: 2 + + stdtypes.rst + constants.rst + functions.rst + exceptions.rst + threadsafety.rst + time-complexity.rst diff --git a/Doc/library/index.rst b/Doc/library/index.rst index f28c03e2fae092f..f7905bf0830dad9 100644 --- a/Doc/library/index.rst +++ b/Doc/library/index.rst @@ -1,11 +1,12 @@ .. _library-index: ############################### - The Python Standard Library + The Python standard library ############################### While :ref:`reference-index` describes the exact syntax and -semantics of the Python language, this library reference manual +semantics of the Python language, and :ref:`builtin-index` describes +the built-ins, this library reference manual describes the standard library that is distributed with Python. It also describes some of the optional components that are commonly included in Python distributions. @@ -39,12 +40,6 @@ the `Python Package Index `_. :maxdepth: 2 intro.rst - functions.rst - constants.rst - stdtypes.rst - exceptions.rst - threadsafety.rst - time-complexity.rst text.rst binary.rst diff --git a/Doc/library/intro.rst b/Doc/library/intro.rst index 8f76044be488cda..56330f0275c7207 100644 --- a/Doc/library/intro.rst +++ b/Doc/library/intro.rst @@ -4,46 +4,32 @@ Introduction ************ -The "Python library" contains several different kinds of components. - -It contains data types that would normally be considered part of the "core" of a -language, such as numbers and lists. For these types, the Python language core -defines the form of literals and places some constraints on their semantics, but -does not fully define the semantics. (On the other hand, the language core does -define syntactic properties like the spelling and priorities of operators.) - -The library also contains built-in functions and exceptions --- objects that can -be used by all Python code without the need of an :keyword:`import` statement. -Some of these are defined by the core language, but many are not essential for -the core semantics and are only described here. - -The bulk of the library, however, consists of a collection of modules. There are -many ways to dissect this collection. Some modules are written in C and built -in to the Python interpreter; others are written in Python and imported in +Note: the built-in functions and classes (which can be used without an +:keyword:`import` statement) are described in :ref:`builtin-index`. + +The Python standard library consists of a collection of modules. There are +many ways to dissect this collection. Some modules are written in C and compiled +into the Python interpreter; others are written in Python and imported in source form. Some modules provide interfaces that are highly specific to Python, like printing a stack trace; some provide interfaces that are specific to particular operating systems, such as access to specific hardware; others provide interfaces that are specific to a particular application domain, like -the World Wide Web. Some modules are available in all versions and ports of +web development. Some modules are available in all versions and ports of Python; others are only available when the underlying system supports or requires them; yet others are available only when a particular configuration option was chosen at the time when Python was compiled and installed. -This manual is organized "from the inside out:" it first describes the built-in -functions, data types and exceptions, and finally the modules, grouped in -chapters of related modules. - -This means that if you start reading this manual from the start, and skip to the +If you start reading this manual from the start, and skip to the next chapter when you get bored, you will get a reasonable overview of the available modules and application areas that are supported by the Python library. Of course, you don't *have* to read it like a novel --- you can also browse the table of contents (in front of the manual), or look for a specific function, module or term in the index (in the back). And finally, if you enjoy -learning about random subjects, you choose a random page number (see module -:mod:`random`) and read a section or two. Regardless of the order in which you -read the sections of this manual, it helps to start with chapter -:ref:`built-in-funcs`, as the remainder of the manual assumes familiarity with -this material. +learning about random subjects, you choose a random page +and read a section or two. Regardless of the order in which you +read the sections of this manual, it helps to first read +:ref:`built-in-funcs` in :ref:`builtin-index`, as the remainder of this section +assumes familiarity with this material. Let the show begin! diff --git a/Doc/reference/index.rst b/Doc/reference/index.rst index a66673b17246d7b..a29c2d91b95b328 100644 --- a/Doc/reference/index.rst +++ b/Doc/reference/index.rst @@ -4,10 +4,11 @@ The Python Language Reference ################################# -This reference manual describes the syntax and "core semantics" of the +This reference manual describes the syntax and core semantics of the language. It is terse, but attempts to be exact and complete. The semantics of -non-essential built-in object types and of the built-in functions and modules -are described in :ref:`library-index`. For an informal introduction to the +built-in object types and of the built-in functions and modules +are described in :ref:`builtin-index` and :ref:`library-index`. +For an informal introduction to the language, see :ref:`tutorial-index`. For C or C++ programmers, two additional manuals exist: :ref:`extending-index` describes the high-level picture of how to write a Python extension module, and the :ref:`c-api-index` describes the diff --git a/Doc/tools/templates/indexcontent.html b/Doc/tools/templates/indexcontent.html index 4366da69d1b2d09..3766dfe6c5cb7e6 100644 --- a/Doc/tools/templates/indexcontent.html +++ b/Doc/tools/templates/indexcontent.html @@ -56,16 +56,18 @@

{{ docstitle|e }}

{% trans whatsnew_index=pathto("whatsnew/index") %}Or all "What's new" documents since Python 2.0{% endtrans %}
  • {% trans %}Tutorial{% endtrans %}
    {% trans %}Start here: a tour of Python's syntax and features{% endtrans %}
    • +
  • {% trans %}Built-ins reference{% endtrans %}
    + {% trans %}Built-in functions and classes{% endtrans %}
  • {% trans %}Library reference{% endtrans %}
    - {% trans %}Standard library and builtins{% endtrans %}
    • + {% trans %}Standard library modules{% endtrans %}
  • {% trans %}Language reference{% endtrans %}
    {% trans %}Syntax and language elements{% endtrans %}
  • {% trans %}Python setup and usage{% endtrans %}
    {% trans %}How to install, configure, and use Python{% endtrans %}
    • -
  • {% trans %}Python HOWTOs{% endtrans %}
    - {% trans %}In-depth topic manuals{% endtrans %}