Deploy preview for PR 1231 🛫

Author: pydoc-zh-tw[bot]

pr-preview/pr-1231/_sources/library/argparse.rst.txt

@@ -442,9 +442,8 @@ is considered equivalent to the expression ``['-f', 'foo', '-f', 'bar']``.
 
 .. note::
 
-   Empty lines are treated as empty strings (``''``), which are allowed as values but
-   not as arguments. Empty lines that are read as arguments will result in an
-   "unrecognized arguments" error.
+   Each line is treated as a single argument, so an empty line is read as an
+   empty string (``''``).
 
 :class:`ArgumentParser` uses :term:`filesystem encoding and error handler`
 to read the file containing arguments.
@@ -1048,6 +1047,10 @@ is used when no command-line argument was present::
    >>> parser.parse_args([])
    Namespace(foo=42)
 
+Because ``nargs='*'`` gathers any supplied values into a list, an absent
+positional argument yields an empty list (``[]``). Only a non-``None``
+*default* overrides this (so ``default=None`` still gives ``[]``).
+
 For required_ arguments, the ``default`` value is ignored. For example, this
 applies to positional arguments with nargs_ values other than ``?`` or ``*``,
 or optional arguments marked as ``required=True``.
@@ -1360,6 +1363,10 @@ behavior::
    >>> parser.parse_args('--foo XXX'.split())
    Namespace(bar='XXX')
 
+Multiple arguments may share the same ``dest``.  By default, the value from the
+last such argument given on the command line wins.  Use ``action='append'`` to
+collect values from all of them into a list instead.  For conflicting *option
+strings* rather than ``dest`` names, see conflict_handler_.
 
 .. _deprecated:
 
@@ -1755,6 +1762,11 @@ Subcommands
    present, and when the ``b`` command is specified, only the ``foo`` and
    ``baz`` attributes are present.
 
+   If a subparser defines an argument with the same ``dest`` as the parent
+   parser, the two share a single namespace attribute, so the parent's value
+   won't be retained. Users should give them  distinct ``dest`` values to
+   keep both.
+
    Similarly, when a help message is requested from a subparser, only the help
    for that particular parser will be printed.  The help message will not
    include parent parser or sibling parser messages.  (A help message for each
@@ -2199,6 +2211,9 @@ Customizing file parsing
         def convert_arg_line_to_args(self, arg_line):
             return arg_line.split()
 
+   Note that with this override an argument can no longer contain spaces, since
+   each space-separated word becomes a separate argument.
+
 
 Exiting methods
 ^^^^^^^^^^^^^^^

pr-preview/pr-1231/_sources/library/pyexpat.rst.txt

@@ -238,16 +238,71 @@ XMLParser Objects
    .. versionadded:: 3.13
 
 
-:class:`!xmlparser` objects have the following methods to mitigate some
-common XML vulnerabilities.
+:class:`!xmlparser` objects have the following methods to tune protections
+against some common XML vulnerabilities.
+
+.. method:: xmlparser.SetBillionLaughsAttackProtectionActivationThreshold(threshold, /)
+
+   Sets the number of output bytes needed to activate protection against
+   `billion laughs`_ attacks.
+
+   The number of output bytes includes amplification from entity expansion
+   and reading DTD files.
+
+   Parser objects usually have a protection activation threshold of 8 MiB,
+   but the actual default value depends on the underlying Expat library.
+
+   An :exc:`ExpatError` is raised if this method is called on a
+   |xml-non-root-parser| parser.
+   The corresponding :attr:`~ExpatError.lineno` and :attr:`~ExpatError.offset`
+   should not be used as they may have no special meaning.
+
+   .. note::
+
+      Activation thresholds below 4 MiB are known to break support for DITA 1.3
+      payload and are hence not recommended.
+
+   .. versionadded:: next
+
+.. method:: xmlparser.SetBillionLaughsAttackProtectionMaximumAmplification(max_factor, /)
+
+   Sets the maximum tolerated amplification factor for protection against
+   `billion laughs`_ attacks.
+
+   The amplification factor is calculated as ``(direct + indirect) / direct``
+   while parsing, where ``direct`` is the number of bytes read from
+   the primary document in parsing and ``indirect`` is the number of
+   bytes added by expanding entities and reading of external DTD files.
+
+   The *max_factor* value must be a non-NaN :class:`float` value greater than
+   or equal to 1.0. Peak amplifications of factor 15,000 for the entire payload
+   and of factor 30,000 in the middle of parsing have been observed with small
+   benign files in practice. In particular, the activation threshold should be
+   carefully chosen to avoid false positives.
+
+   Parser objects usually have a maximum amplification factor of 100,
+   but the actual default value depends on the underlying Expat library.
+
+   An :exc:`ExpatError` is raised if this method is called on a
+   |xml-non-root-parser| parser or if *max_factor* is outside the valid range.
+   The corresponding :attr:`~ExpatError.lineno` and :attr:`~ExpatError.offset`
+   should not be used as they may have no special meaning.
+
+   .. note::
+
+      The maximum amplification factor is only considered if the threshold
+      that can be adjusted by :meth:`.SetBillionLaughsAttackProtectionActivationThreshold`
+      is exceeded.
+
+   .. versionadded:: next
 
 .. method:: xmlparser.SetAllocTrackerActivationThreshold(threshold, /)
 
    Sets the number of allocated bytes of dynamic memory needed to activate
    protection against disproportionate use of RAM.
 
-   By default, parser objects have an allocation activation threshold of 64 MiB,
-   or equivalently 67,108,864 bytes.
+   Parser objects usually have an allocation activation threshold of 64 MiB,
+   but the actual default value depends on the underlying Expat library.
 
    An :exc:`ExpatError` is raised if this method is called on a
    |xml-non-root-parser| parser.
@@ -271,7 +326,8 @@ common XML vulnerabilities.
    near the start of parsing even with benign files in practice. In particular,
    the activation threshold should be carefully chosen to avoid false positives.
 
-   By default, parser objects have a maximum amplification factor of 100.0.
+   Parser objects usually have a maximum amplification factor of 100,
+   but the actual default value depends on the underlying Expat library.
 
    An :exc:`ExpatError` is raised if this method is called on a
    |xml-non-root-parser| parser or if *max_factor* is outside the valid range.
@@ -1019,4 +1075,6 @@ The ``errors`` module has the following attributes:
    not. See https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl
    and https://www.iana.org/assignments/character-sets/character-sets.xhtml.
 
+
+.. _billion laughs: https://en.wikipedia.org/wiki/Billion_laughs_attack
 .. |xml-non-root-parser| replace:: :ref:`non-root <xmlparser-non-root>`

pr-preview/pr-1231/_sources/library/shutil.rst.txt

@@ -388,10 +388,14 @@ Directory and files operations
    If *dst* already exists but is not a directory, it may be overwritten
    depending on :func:`os.rename` semantics.
 
-   If the destination is on the current filesystem, then :func:`os.rename` is
-   used. Otherwise, *src* is copied to the destination using *copy_function*
-   and then removed.  In case of symlinks, a new symlink pointing to the target
-   of *src* will be created as the destination and *src* will be removed.
+   :func:`os.rename` is preferably used internally when *src* and the destination are on
+   the same filesystem. In case :func:`os.rename` fails due to :exc:`OSError`
+   (e.g. the user has write permission to the destination file but not to its parent
+   directory), this method falls back to using *copy_function*, in which case
+   *src* is copied to the destination using *copy_function* and then removed.
+
+   In case of symlinks, a new symlink pointing to the target of *src* will be
+   created in or as the destination, and *src* will be removed.
 
    If *copy_function* is given, it must be a callable that takes two arguments,
    *src* and the destination, and will be used to copy *src* to the destination

pr-preview/pr-1231/about.html

@@ -356,7 +356,7 @@ <h3>導航</h3>
 <a href="https://www.python.org/psf/donations/">敬請捐贈。</a>
 <br>
     <br>
-      最後更新於 6月 09, 2026 (00:43 UTC)。
+      最後更新於 6月 10, 2026 (00:49 UTC)。
 
       <a href="/bugs.html">發現 bug</a>？
 

pr-preview/pr-1231/bugs.html

@@ -250,7 +250,7 @@ <h2>說明文件的錯誤<a class="headerlink" href="#documentation-bugs" title=
 </section>
 <section id="getting-started-contributing-to-python-yourself">
 <span id="contributing-to-python"></span><h2>開始讓自己貢獻 Python<a class="headerlink" href="#getting-started-contributing-to-python-yourself" title="連結到這個標頭">¶</a></h2>
-<p>除了只是回報你所發現的錯誤之外，同樣也歡迎你提交修正它們的修補程式 (patch)。你可以在 <a class="reference external" href="https://mail.python.org/mailman3/lists/core-mentorship.python.org/">Python 開發者指南</a>中找到如何開始修補 Python 的更多資訊。如果你有任何問題，<a class="reference external" href="https://devguide.python.org/">核心導師郵寄清單</a>是一個友善的地方，你可以在那裡得到，關於 Python 修正錯誤的過程中，所有問題的答案。</p>
+<p>除了只是回報你所發現的錯誤之外，同樣也歡迎你提交修正它們的修補程式 (patch)。你可以在 <a class="reference external" href="https://devguide.python.org/">Python 開發者指南</a>中找到如何開始修補 Python 的更多資訊。如果你有任何問題，<a class="reference external" href="https://mail.python.org/mailman3/lists/core-mentorship.python.org/">核心導師郵寄清單</a>是一個友善的地方，你可以在那裡得到，關於 Python 修正錯誤的過程中，所有問題的答案。</p>
 </section>
 </section>
 
@@ -393,7 +393,7 @@ <h3>導航</h3>
 <a href="https://www.python.org/psf/donations/">敬請捐贈。</a>
 <br>
     <br>
-      最後更新於 6月 09, 2026 (00:43 UTC)。
+      最後更新於 6月 10, 2026 (00:49 UTC)。
 
       <a href="/bugs.html">發現 bug</a>？
 

pr-preview/pr-1231/c-api/abstract.html

@@ -365,7 +365,7 @@ <h3>導航</h3>
 <a href="https://www.python.org/psf/donations/">敬請捐贈。</a>
 <br>
     <br>
-      最後更新於 6月 09, 2026 (00:43 UTC)。
+      最後更新於 6月 10, 2026 (00:49 UTC)。
 
       <a href="/bugs.html">發現 bug</a>？
 

pr-preview/pr-1231/c-api/allocation.html

@@ -577,7 +577,7 @@ <h3>導航</h3>
 <a href="https://www.python.org/psf/donations/">敬請捐贈。</a>
 <br>
     <br>
-      最後更新於 6月 09, 2026 (00:43 UTC)。
+      最後更新於 6月 10, 2026 (00:49 UTC)。
 
       <a href="/bugs.html">發現 bug</a>？
 

pr-preview/pr-1231/c-api/apiabiversion.html

@@ -514,7 +514,7 @@ <h3>導航</h3>
 <a href="https://www.python.org/psf/donations/">敬請捐贈。</a>
 <br>
     <br>
-      最後更新於 6月 09, 2026 (00:43 UTC)。
+      最後更新於 6月 10, 2026 (00:49 UTC)。
 
       <a href="/bugs.html">發現 bug</a>？
 

pr-preview/pr-1231/c-api/arg.html

@@ -996,7 +996,7 @@ <h3>導航</h3>
 <a href="https://www.python.org/psf/donations/">敬請捐贈。</a>
 <br>
     <br>
-      最後更新於 6月 09, 2026 (00:43 UTC)。
+      最後更新於 6月 10, 2026 (00:49 UTC)。
 
       <a href="/bugs.html">發現 bug</a>？
 

pr-preview/pr-1231/c-api/bool.html

@@ -376,7 +376,7 @@ <h3>導航</h3>
 <a href="https://www.python.org/psf/donations/">敬請捐贈。</a>
 <br>
     <br>
-      最後更新於 6月 09, 2026 (00:43 UTC)。
+      最後更新於 6月 10, 2026 (00:49 UTC)。
 
       <a href="/bugs.html">發現 bug</a>？