- `.
-To create a heap, use a list initialized to ``[]``, or you can transform a
-populated list into a heap via function :func:`heapify`.
+These two aspects make it possible to view the heap as a regular Python list
+without surprises: ``heap[0]`` is the smallest item, and ``heap.sort()``
+maintains the heap invariant!
-The following functions are provided:
+Like :meth:`list.sort`, this implementation uses only the ``<`` operator
+for comparisons, for both min-heaps and max-heaps.
+
+In the API below, and in this documentation, the unqualified term *heap*
+generally refers to a min-heap.
+The API for max-heaps is named using a ``_max`` suffix.
+
+To create a heap, use a list initialized as ``[]``, or transform an existing list
+into a min-heap or max-heap using the :func:`heapify` or :func:`heapify_max`
+functions, respectively.
+
+The following functions are provided for min-heaps:
.. function:: heappush(heap, item)
- Push the value *item* onto the *heap*, maintaining the heap invariant.
+ Push the value *item* onto the *heap*, maintaining the min-heap invariant.
.. function:: heappop(heap)
- Pop and return the smallest item from the *heap*, maintaining the heap
+ Pop and return the smallest item from the *heap*, maintaining the min-heap
invariant. If the heap is empty, :exc:`IndexError` is raised. To access the
smallest item without popping it, use ``heap[0]``.
@@ -63,7 +79,7 @@ The following functions are provided:
.. function:: heapify(x)
- Transform list *x* into a heap, in-place, in linear time.
+ Transform list *x* into a min-heap, in-place, in linear time.
.. function:: heapreplace(heap, item)
@@ -82,6 +98,56 @@ The following functions are provided:
on the heap.
+For max-heaps, the following functions are provided:
+
+
+.. function:: heapify_max(x)
+
+ Transform list *x* into a max-heap, in-place, in linear time.
+
+ .. versionadded:: 3.14
+
+
+.. function:: heappush_max(heap, item)
+
+ Push the value *item* onto the max-heap *heap*, maintaining the max-heap
+ invariant.
+
+ .. versionadded:: 3.14
+
+
+.. function:: heappop_max(heap)
+
+ Pop and return the largest item from the max-heap *heap*, maintaining the
+ max-heap invariant. If the max-heap is empty, :exc:`IndexError` is raised.
+ To access the largest item without popping it, use ``maxheap[0]``.
+
+ .. versionadded:: 3.14
+
+
+.. function:: heappushpop_max(heap, item)
+
+ Push *item* on the max-heap *heap*, then pop and return the largest item
+ from *heap*.
+ The combined action runs more efficiently than :func:`heappush_max`
+ followed by a separate call to :func:`heappop_max`.
+
+ .. versionadded:: 3.14
+
+
+.. function:: heapreplace_max(heap, item)
+
+ Pop and return the largest item from the max-heap *heap* and also push the
+ new *item*.
+ The max-heap size doesn't change. If the max-heap is empty,
+ :exc:`IndexError` is raised.
+
+ The value returned may be smaller than the *item* added. Refer to the
+ analogous function :func:`heapreplace` for detailed usage notes.
+
+ .. versionadded:: 3.14
+
+
The module also offers three general purpose functions based on heaps.
@@ -246,17 +312,12 @@ elements are considered to be infinite. The interesting property of a heap is
that ``a[0]`` is always its smallest element.
The strange invariant above is meant to be an efficient memory representation
-for a tournament. The numbers below are *k*, not ``a[k]``::
+for a tournament. The numbers below are *k*, not ``a[k]``:
- 0
-
- 1 2
-
- 3 4 5 6
-
- 7 8 9 10 11 12 13 14
-
- 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
+.. figure:: heapq-binary-tree.svg
+ :class: invert-in-dark-mode
+ :align: center
+ :alt: Example (min-heap) binary tree.
In the tree above, each cell *k* is topping ``2*k+1`` and ``2*k+2``. In a usual
binary tournament we see in sports, each cell is the winner over the two cells
diff --git a/Doc/library/html.parser.rst b/Doc/library/html.parser.rst
index 6d433b5a04f..dd67fc34e85 100644
--- a/Doc/library/html.parser.rst
+++ b/Doc/library/html.parser.rst
@@ -43,7 +43,9 @@ Example HTML Parser Application
As a basic example, below is a simple HTML parser that uses the
:class:`HTMLParser` class to print out start tags, end tags, and data
-as they are encountered::
+as they are encountered:
+
+.. testcode::
from html.parser import HTMLParser
@@ -63,7 +65,7 @@ as they are encountered::
The output will then be:
-.. code-block:: none
+.. testoutput::
Encountered a start tag: html
Encountered a start tag: head
@@ -230,7 +232,9 @@ Examples
--------
The following class implements a parser that will be used to illustrate more
-examples::
+examples:
+
+.. testcode::
from html.parser import HTMLParser
from html.entities import name2codepoint
@@ -266,13 +270,17 @@ examples::
parser = MyHTMLParser()
-Parsing a doctype::
+Parsing a doctype:
+
+.. doctest::
>>> parser.feed('')
Decl : DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"
-Parsing an element with a few attributes and a title::
+Parsing an element with a few attributes and a title:
+
+.. doctest::
>>> parser.feed('
- {% trans %}Stable{% endtrans %} -
- {% trans %}In development{% endtrans %} + {# _docs_by_version.html is overwritten by build_docs.py for non-EOL versions #} + {% include "_docs_by_version.html" without context %}
- {% trans %}All versions{% endtrans %}
- {% trans %}PEP Index{% endtrans %} -
- {% trans %}Beginner's Guide{% endtrans %} -
- {% trans %}Book List{% endtrans %} -
- {% trans %}Audio/Visual Talks{% endtrans %} -
- {% trans %}Python Developer’s Guide{% endtrans %} +
- {% trans %}PEP index{% endtrans %} +
- {% trans %}Beginner's guide{% endtrans %} +
- {% trans %}Book list{% endtrans %} +
- {% trans %}Audio/visual talks{% endtrans %} +
- {% trans %}Python developer’s guide{% endtrans %}
')
Start tag: img
@@ -285,7 +293,9 @@ Parsing an element with a few attributes and a title::
End tag : h1
The content of ``script`` and ``style`` elements is returned as is, without
-further parsing::
+further parsing:
+
+.. doctest::
>>> parser.feed('')
Start tag: style
@@ -300,16 +310,25 @@ further parsing::
Data : alert("hello!");
End tag : script
-Parsing comments::
+Parsing comments:
- >>> parser.feed(''
+.. doctest::
+
+ >>> parser.feed(''
... '')
- Comment : a comment
+ Comment : a comment
Comment : [if IE 9]>IE-specific content'``)::
+correct char (note: these 3 references are all equivalent to ``'>'``):
+.. doctest::
+
+ >>> parser = MyHTMLParser()
+ >>> parser.feed('>>>')
+ Data : >>>
+
+ >>> parser = MyHTMLParser(convert_charrefs=False)
>>> parser.feed('>>>')
Named ent: >
Num ent : >
@@ -317,18 +336,22 @@ correct char (note: these 3 references are all equivalent to ``'>'``)::
Feeding incomplete chunks to :meth:`~HTMLParser.feed` works, but
:meth:`~HTMLParser.handle_data` might be called more than once
-(unless *convert_charrefs* is set to ``True``)::
+(unless *convert_charrefs* is set to ``True``):
- >>> for chunk in ['
-
{{ _('This Page') }}
+{{ _('This page') }}
diff --git a/Doc/tools/templates/download.html b/Doc/tools/templates/download.html index 4645f7d394e..47a57eb111b 100644 --- a/Doc/tools/templates/download.html +++ b/Doc/tools/templates/download.html @@ -27,7 +27,7 @@ {%- endblock -%} {% block body %} -{% trans %}Download Python {{ dl_version }} Documentation{% endtrans %}
+{% trans %}Download Python {{ dl_version }} documentation{% endtrans %}
{% if last_updated %}{% trans %}Last updated on: {{ last_updated }}.{% endtrans %}
{% endif %} diff --git a/Doc/tools/templates/indexcontent.html b/Doc/tools/templates/indexcontent.html index 06a4223643a..544cc4234f4 100644 --- a/Doc/tools/templates/indexcontent.html +++ b/Doc/tools/templates/indexcontent.html @@ -72,7 +72,7 @@{{ docstitle|e }}
|
{% trans %}Reporting issues{% endtrans %} -{% trans %}Contributing to Docs{% endtrans %} + |
{% trans %}History and license of Python{% endtrans %} diff --git a/Doc/tools/templates/indexsidebar.html b/Doc/tools/templates/indexsidebar.html index 5986204256f..086f15662cf 100644 --- a/Doc/tools/templates/indexsidebar.html +++ b/Doc/tools/templates/indexsidebar.html @@ -2,17 +2,16 @@{% trans %}Download{% endtrans %}{% trans %}Download these documents{% endtrans %} {% trans %}Docs by version{% endtrans %}
{% trans %}Other resources{% endtrans %}
{evil} " + assert html(template) == "<script>alert('evil')</script> " + +As another example, generating HTML attributes from data: + +.. code-block:: python + + attributes = {"src": "shrubbery.jpg", "alt": "looks nice"} + template = t" '
+
+Compared to using an f-string, the ``html`` function has access to template attributes
+containing the original information: static strings, interpolations, and values
+from the original scope. Unlike existing templating approaches, t-strings build
+from the well-known f-string syntax and rules. Template systems thus benefit
+from Python tooling as they are much closer to the Python language, syntax,
+scoping, and more.
+
+Writing template handlers is straightforward:
+
+.. code-block:: python
+
+ from string.templatelib import Template, Interpolation
+
+ def lower_upper(template: Template) -> str:
+ """Render static parts lowercased and interpolations uppercased."""
+ parts: list[str] = []
+ for item in template:
+ if isinstance(item, Interpolation):
+ parts.append(str(item.value).upper())
+ else:
+ parts.append(item.lower())
+ return "".join(parts)
+
+ name = "world"
+ assert lower_upper(t"HELLO {name}") == "hello WORLD"
+
+With this in place, developers can write template systems to sanitize SQL, make
+safe shell operations, improve logging, tackle modern ideas in web development
+(HTML, CSS, and so on), and implement lightweight, custom business DSLs.
+
+(Contributed by Jim Baker, Guido van Rossum, Paul Everitt, Koudai Aono,
+Lysandros Nikolaou, Dave Peck, Adam Turner, Jelle Zijlstra, Bénédikt Tran,
+and Pablo Galindo Salgado in :gh:`132661`.)
+
+.. seealso::
+ :pep:`750`.
+
+
.. _whatsnew314-pep768:
PEP 768: Safe external debugger interface for CPython
@@ -99,7 +202,9 @@ PEP 768: Safe external debugger interface for CPython
:pep:`768` introduces a zero-overhead debugging interface that allows debuggers and profilers
to safely attach to running Python processes. This is a significant enhancement to Python's
-debugging capabilities allowing debuggers to forego unsafe alternatives.
+debugging capabilities allowing debuggers to forego unsafe alternatives. See
+:ref:`below |