Use `time.monotonic` in OrderedDict LRU cache example (GH-150986)
(cherry picked from commit ea4c85552b)
Co-authored-by: Ilya Nikolaev <65247719+ilya-nikolaev@users.noreply.github.com>
gh-129011: Update docs for Raw I/O read, readinto, and write (GH-135328)
Update `RawIOBase` and `FileIO` documentation to match implementation
behavior around `.read`, `.readinto`, `.readall` and `.write`.
In particular:
- They may make more than one system call (PEP-475)
- Add warnings if `.write()` requires a wrapping retry loop (see: gh-126606)
- "Raw I/O" `.write`` may not write all bytes
- `buffering=0` example results in a "Raw I/O"
(cherry picked from commit e4db68b9c9)
Co-authored-by: Cody Maloney <cmaloney@users.noreply.github.com>
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
gh-132467: Document and test that generic aliases are not classes (GH-133504)
(cherry picked from commit 5915a1fb9d)
Co-authored-by: Abduaziz π <mail@ziyodov.uz>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
gh-150319: Replace all documentation which says "See PEP 585" (GH-150325)
* Replace all documentation which says "See PEP 585"
The following classes in the stdlib get simple updates:
- array.array
- asyncio.Future
- asyncio.Task
- collections.defaultdict
- collections.deque
- contextvars.ContextVar
- contextvars.Token
- ctypes.Array
- os.DirEntry
- re.Match
- re.Pattern
- string.templatelib.Interpolation
- string.templatelib.Template
- types.MappingProxyType
- queue.SimpleQueue
- weakref.ref
The following classes are documented publicly as functions, and are
therefore updated internally (`__class_getitem__.__doc__`) but not in the
public docs:
- functools.partial
- itertools.chain
The following builtin types have updates to `__class_getitem__.__doc__`
but not to any documentation pages:
- BaseExceptionGroup
- coroutines (from generators)
- dict
- enumerate
- frozendict
- frozenset
- generators (and async generators)
- list
- memoryview
- set
- slice
- tuple
Special cases:
- union objects are now documented as "supporting class-level []",
rather than anything to do with generics.
- Templates might be generic over a single type (union, in theory) or
over a TypeVarTuple. As this is not currently fully settled, it is
marked with a comment and a mild hint that it is a single type is used
(namely, "type" is singular rather than "types", plural)
* Apply suggestions from code review
* Correct several class getitem docs
And expand the text for tuples.
* Add notes on generic typing of builtins
* Fix typo in tuple.__class_getitem__ docstring
* Typo fix: malformed refs
Fix `generic` links which weren't marked as `:ref:`.
* Strike unnecessary docs on generic-ness
* Apply suggestions from code review
These are applied at both the originally indicated locations and in the
corresponding docstring definitions.
* Update Doc/library/re.rst
* Update Objects/enumobject.c
* Remove tuple generic doc in 'stdtypes' page
This is covered in more detail in the cross-linked typing documentation.
The other copy of this documentation -- in the docstring for
`tuple.__class_getitem__` -- is left in place.
* Fix whitespace around new doc of generics
Per review, do not introduce or remove whitespace such that section
breaks are altered by the introduction of doc on various generic types.
In most cases, this is a removal of an extra line.
In one case (Arrays), it is the reintroduction of a line.
Additionally, two other minor fixes are included:
- incorrect indent on 'defaultdicts'
- make `mappingproxy.__class_getitem__.__doc__` consistent with other
mapping type generic docs
* Move placement of memoryview generic note
Previous placement was at the end of the main docstring, which is
consistent with other types but places it after a section on various
methods (which makes it read somewhat inconsistently). Moving it up
helps resolve.
* Ensure sphinxdoc does not start sentences lowercase
Lowercase class names at the start of sentences are marked out with the
`class` role. In the case of `deque`, documentation already refers to
these as `Deques`, so this form is preferred.
* Apply suggestions from code review
* Fix line endings and wrap more tightly
Line endings fixed by pre-commit ; also re-wrapped the MappingProxyType
text which was too long.
* Use 'ContextVars' style in sphinx doc
---------
(cherry picked from commit 50fe49c879)
Co-authored-by: Stephen Rosen <sirosen@globus.org>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Jelle Zijlstra <906600+JelleZijlstra@users.noreply.github.com>
Co-authored-by: Alex Waygood <66076021+AlexWaygood@users.noreply.github.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
BufferedRandom does not inherit from BufferedReader and BufferedWriter
in the C implementation.
(cherry picked from commit 551bc2cb5e)
Co-authored-by: Mohsin Mehmood <55545648+mohsinm-dev@users.noreply.github.com>
gh-89554: Document _thread.LockType as a class (GH-150684)
_thread.LockType is a class (the type of lock objects), but was documented
with the ".. data::" directive, so ":class:" cross-references to it cannot
resolve against a py:class target.
Switch the entry to ".. class::", move it next to the lock methods, and
document acquire(), release() and locked() as methods of the class. Keep
the old _thread.lock.* URL fragments working with raw HTML anchors.
(cherry picked from commit e37ce56977)
Co-authored-by: Bernát Gábor <gaborjbernat@gmail.com>
gh-149738: Fix segmentation fault bug in sqllite3 (GH-149754)
Deleting the `row_factory` or `text_factory` attribute is no longer allowed.
(cherry picked from commit 60fdb3192b)
Co-authored-by: Sepehr Rasouli <sepehrrasouli06@gmail.com>
Use the directive "class" instead of "data" for ParamSpecArgs and ParamSpecKwargs.
(cherry picked from commit 35c314d2b7)
Co-authored-by: Bernát Gábor <gaborjbernat@gmail.com>
Use the directive and the role "class" instead of "data" for classes
exposed in the types module.
(cherry picked from commit bc055444e4)
Co-authored-by: Bernát Gábor <gaborjbernat@gmail.com>
Use the "class" directive instead of "data" for ReferenceType,
ProxyType and CallableProxyType.
(cherry picked from commit 10c421970b)
Co-authored-by: Bernát Gábor <gaborjbernat@gmail.com>
Always use the directive and the role "class" instead of "data" for
NoneType, NotImplementedType and EllipsisType.
(cherry picked from commit e40190e104)
Co-authored-by: Bernát Gábor <gaborjbernat@gmail.com>
gh-150228: Improve the PEP 829 batch processing APIs (GH-150542)
* gh-150228: Improve the PEP 829 batch processing APIs
As previously discussed with @ncoghlan and approved for 3.15b2 by @hugovk,
this implements the batch processing APIs for addsitedir() and friends. We
remove the `defer_processing_start_files` flag which required some implicit
module global state, and promote StartupState to the public documented API.
This also moves the bulk of the module global functions into methods of the
`StartupState` class, so it removes the awkward APIs in 3.15b1. Now, instances
of this class are an accumulator for startup state, using `StartupState.process()`
to process them. Callers can now batch up startup state themselves by using
the methods on this class. The module global functions are shims for this
which preserve the legacy APIs and semantics using the new state class.
This PR also fixes the interleaving regression identified by @ncoghlan in the
same issue. Now, .pth file sys.path extensions are added to sys.path after
the sitedir that the .pth file is found in, restoring the legacy behavior.
Along the way, I've made a lot of improvements to function docstrings,
site.rst documentation, and comments in the code explaining what's going on.
* Add a note that if known_paths is provided to StartupState.__init__(), it
will get mutated in place.
* Improve some conditional flows.
* Improve some comments.
* Improve the what's new entry.
* Make test_impl_exec_imports_suppressed_by_matching_start() more robust
Based on PR comment, we need to read both the .pth and .start files, and prove
that the .pth file's import line (which passes a bigger increment) is not
called, but the .start file's entry point (which uses the default increment)
is called.
* As per review, move some methods to the private API
_read_pth_file() and _read_start_file() are not intended to be part of the
public API surface outside of the site module, so even though they are used by
methods outside of the StartupState class, make them privately named.
* Resolve several review feedbacks
* Move a `versionadded`
* Better list comprehension formatting (use the output from
`ruff format --line-length 78`)
* Add docs for site.makepath() and point the case-normalization requirement to
this utility function.
* Note that StartupState.process() is not idempotent.
* Address another feedback comment
This time, we get rid of the legacy implementation `reset` local, which was
always difficult to understand, and just implement a return value based on the
processing mode selected.
* Changes based on gh-150228 review
The comment by @encukou that started this change:
```
I still see two red flags here though: an argument that doesn't combine with
other arguments, and (another instance of) changing the return type based on
an argument.
Did you consider adding a StartupState.addsitedir(sitedir) method, instead of
the startup_state argument?
```
As it turns out, this is an even cleaner design. By moving the bulk of the
previous module global functions into `StartupState` methods, we can get rid
of all the awkward `startup_state` keyword-only arguments which conflict
with `known_path` (Petr's first point). We can also get rid of the
return value dichotomy (Petr's second point) because now we can preserve
exactly the Python 3.14 API in the module global functions, and implement
the better APIs in the class methods. We also generally don't have to
pass around `process_known_sitedirs`.
Now the following module global functions are essentially shims around
class methods:
* site.addsitedir() -> StartupState.addsitedir()
* site.addusersitepackages() -> StartupState.addusersitepackages()
* site.addsitepackages() -> StartupState.addsitepackages()
* Additional minor changes
* Remove a now unused parameter
(cherry picked from commit 27ebd9abce)
Co-authored-by: Barry Warsaw <barry@python.org>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
0.5 <= abs(m) < 1 is only true for finite nonzero numbers
(cherry picked from commit 5b5ffce05c)
Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>
bytes.fromhex() accepts ASCII bytes and bytes-like objects as input since 3.14
(cherry picked from commit af10734907)
Co-authored-by: Joshix-1 <57299889+Joshix-1@users.noreply.github.com>
gh-149995: Update typing.py docstrings and documentation (GH-149996)
Some of these docstrings read as if they were written when typing.py was
first written, and things have evolved since then.
A few motivations:
- Call protocols protocols instead of ABCs. They are also ABCs, but the fact
they are protocols is more relevant to typing.
- Avoid recommending direct use of .__annotations__ and steer users to
annotationlib instead.
- For TypedDict, mention NotRequired before total=False since it is more
general and probably more frequently useful.
- For overloads, mention runtime use first instead of stub use. I think early on
there was talk of allowing overload only in stubs, but it is now heavily used at
runtime too and that's more likely to be relevant to users.
(cherry picked from commit f159419ae2)
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
gh-143387: Update docs to reflect the behavior and note the changed version. (GH-150095)
(cherry picked from commit 192796cfd4)
Co-authored-by: Jason R. Coombs <jaraco@jaraco.com>
gh-146581: Update docs for dangerous filenames in ZIP files (GH-149994)
(cherry picked from commit ba0aca3bff)
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
Co-authored-by: Sebastian Gassner <sebastian.gassner@gmail.com>
bpo-42367: Restore os.makedirs() and pathlib.mkdir() ability to apply *mode* recursively via a new parent_mode= keyword argument.
(cherry picked from commit 9770e32ce0)
+ Make Path.mkdir parent_mode tests umask-independent
test_mkdir_with_parent_mode, test_mkdir_parent_mode_deep_hierarchy and
test_mkdir_parent_mode_same_as_mode assert exact directory mode bits but
did not pin the process umask. On buildbots running with a restrictive
umask (e.g. 0o077) the 0o755 leaf was masked down to 0o700, failing the
assertions. Wrap them in os_helper.temp_umask(0o022), matching the
other umask-aware mkdir tests in this file.
---------
Co-authored-by: nessita <124304+nessita@users.noreply.github.com>
Co-authored-by: Zackery Spytz <zspytz@gmail.com>
Co-authored-by: Erlend E. Aasland <erlend@python.org>
Co-authored-by: Gregory P. Smith <greg@krypto.org>
gh-95816: Fix TLS version range example in docs (GH-148574)
docs(ssl): Fix TLS version range example
(cherry picked from commit dbd8985e82)
Co-authored-by: Jan Brasna <1784648+janbrasna@users.noreply.github.com>
