They are alternate constructors which only accept numbers
(including objects with special methods __float__, __complex__
and __index__), but not strings.
It is our general practice to make new optional parameters keyword-only,
even if the existing parameters are all positional-or-keyword. Passing
this parameter as positional would look confusing and could be error-prone
if additional parameters are added in the future.
Add *preserve_metadata* keyword-only argument to `pathlib.Path.copy()`, defaulting to false. When set to true, we copy timestamps, permissions, extended attributes and flags where available, like `shutil.copystat()`. The argument has no effect on Windows, where metadata is always copied.
Internally (in the pathlib ABCs), path types gain `_readable_metadata` and `_writable_metadata` attributes. These sets of strings describe what kinds of metadata can be retrieved and stored. We take an intersection of `source._readable_metadata` and `target._writable_metadata` to minimise reads/writes. A new `_read_metadata()` method accepts a set of metadata keys and returns a dict with those keys, and a new `_write_metadata()` method accepts a dict of metadata. We *might* make these public in future, but it's hard to justify while the ABCs are still private.
In `{str,bytes}.strip(chars)`, multiple characters are not treated as a
prefix/suffix, but as individual characters. This may make users confuse
whether `split` has similar behavior.
Users may incorrectly expect that
`'Good morning, John.'.split(', .') == ['Good', 'morning', 'John']`
Adding a bit of clarification in the doc.
Co-authored-by: Yuxin Wu <ppwwyyxx@users.noreply.github.com>
This amends 6988ff02a5: memory allocation for
stginfo->ffi_type_pointer.elements in PyCSimpleType_init() should be
more generic (perhaps someday fmt->pffi_type->elements will be not a
two-elements array).
It should finally resolve#61103.
Co-authored-by: Victor Stinner <vstinner@python.org>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
Check for `ERROR_INVALID_PARAMETER` when calling `_winapi.CopyFile2()` and
raise `UnsupportedOperation`. In `Path.copy()`, handle this exception and
fall back to the `PathBase.copy()` implementation.
Add dedicated subsection for `home()`, `expanduser()`, `cwd()`,
`absolute()`, `resolve()` and `readlink()`. The position of this section
keeps all the `Path` constructors (`Path()`, `Path.from_uri()`,
`Path.home()` and `Path.cwd()`) near the top. Within the section, closely
related methods are kept adjacent. Specifically:
-.`home()` and `expanduser()` (the former calls the latter)
- `cwd()` and `absolute()` (the former calls the latter)
- `absolute()` and `resolve()` (both make paths absolute)
- `resolve()` and `readlink()` (both read symlink targets)
- Ditto `cwd()` and `absolute()`
- Ditto `absolute()` and `resolve()`
The "Other methods" section is removed.
* Move pprinter parameters description to the table
The change improves readability.
Suggested in the GH#116085 PR discussion.
* Make pprint doc with params markup
* Fix formatting
Indentation of code blocks made them nested
"Version changed" is better placed after the code block
* Fix formatting for tests
* fix code indentation for autotests
* Fix identation for autotests
* Remove duplication of the parameters' description
* Rearrange parameters description in a correct order
---------
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Add dedicated subsection for `pathlib.owner()`, `group()`, `chmod()` and
`lchmod()`.
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
PyDict_Next no longer locks the dictionary in the free-threaded build. Locking
around individual PyDict_Next calls is not sufficient because the function
returns borrowed references and because it allows concurrent modifications
during the iteraiton loop.
The internal locking also interferes with correct external synchronization
because it may suspend outer critical sections created by the caller.
Add `pathlib.Path.copytree()` method, which recursively copies one
directory to another.
This differs from `shutil.copytree()` in the following respects:
1. Our method has a *follow_symlinks* argument, whereas shutil's has a
*symlinks* argument with an inverted meaning.
2. Our method lacks something like a *copy_function* argument. It always
uses `Path.copy()` to copy files.
3. Our method lacks something like a *ignore_dangling_symlinks* argument.
Instead, users can filter out danging symlinks with *ignore*, or
ignore exceptions with *on_error*
4. Our *ignore* argument is a callable that accepts a single path object,
whereas shutil's accepts a path and a list of child filenames.
5. We add an *on_error* argument, which is a callable that accepts
an `OSError` instance. (`Path.walk()` also accepts such a callable).
Co-authored-by: Nice Zombies <nineteendo19d0@gmail.com>
This makes the following macros public as part of the non-limited C-API for
locking a single object or two objects at once.
* `Py_BEGIN_CRITICAL_SECTION(op)` / `Py_END_CRITICAL_SECTION()`
* `Py_BEGIN_CRITICAL_SECTION2(a, b)` / `Py_END_CRITICAL_SECTION2()`
The supporting functions and structs used by the macros are also exposed for
cases where C macros are not available.
Add support for not following symlinks in `pathlib.Path.copy()`.
On Windows we add the `COPY_FILE_COPY_SYMLINK` flag is following symlinks is disabled. If the source is symlink to a directory, this call will fail with `ERROR_ACCESS_DENIED`. In this case we add `COPY_FILE_DIRECTORY` to the flags and retry. This can fail on old Windowses, which we note in the docs.
No news as `copy()` was only just added.
This exposes `PyUnstable_Object_ClearWeakRefsNoCallbacks` as an unstable
C-API function to provide a thread-safe mechanism for clearing weakrefs
without executing callbacks.
Some C-API extensions need to clear weakrefs without calling callbacks,
such as after running finalizers like we do in subtype_dealloc.
Previously they could use `_PyWeakref_ClearRef` on each weakref, but
that's not thread-safe in the free-threaded build.
Co-authored-by: Petr Viktorin <encukou@gmail.com>
The `inspect.ismethoddescriptor()` function did not check for the lack of
`__delete__()` and, consequently, erroneously returned True when applied
to *data* descriptors with only `__get__()` and `__delete__()` defined.
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
Co-authored-by: Alyssa Coghlan <ncoghlan@gmail.com>
Add thread-safety clarifications to the SSLContext documentation. Per the issue:
This issue has also come up [here](https://github.com/psf/requests/pull/6667) where the matter was clarified by @tiran in [this comment](https://github.com/psf/requests/pull/6667):
> `SSLContext` is designed to be shared and used for multiple connections. It is thread safe as long as you don't reconfigure it once it is used by a connection. Adding new certs to the internal trust store is fine, but changing ciphers, verification settings, or mTLS certs can lead to surprising behavior. The problem is unrelated to threads and can even occur in a single-threaded program.
This matches the output behavior in 3.10 and earlier; the optimization in 3.11 allowed the zlib library's "os" value to be filled in instead in the circumstance when mtime was 0. this keeps things consistent.
Add a `Path.copy()` method that copies the content of one file to another.
This method is similar to `shutil.copyfile()` but differs in the following ways:
- Uses `fcntl.FICLONE` where available (see GH-81338)
- Uses `os.copy_file_range` where available (see GH-81340)
- Uses `_winapi.CopyFile2` where available, even though this copies more metadata than the other implementations. This makes `WindowsPath.copy()` more similar to `shutil.copy2()`.
The method is presently _less_ specified than the `shutil` functions to allow OS-specific optimizations that might copy more or less metadata.
Incorporates code from GH-81338 and GH-93152.
Co-authored-by: Eryk Sun <eryksun@gmail.com>
Add dedicated subsection for `pathlib.Path.touch()`, `mkdir()`,
`symlink_to()` and `hardlink_to()`. Also note that `open()`, `write_text()`
and `write_bytes()` are often used to create files.
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Adjust DeprecationWarning when testing element truth values in ElementTree, we're planning to go with the more natural True return rather than a disruptive harder to code around exception raise, and are deferring the behavior change for a few more releases.
- Explicit list of what it does that is different from
"just return __annotations__"
- Remove reference to PEP 563; adding the future import doesn't
do anything to type aliases, and in general it will never make
get_type_hints() less likely to fail.
- Remove example, as the Annotated docs already have a similar
example, and it's unbalanced to have one example about this
one edge case but not about other behaviors of the function.
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Remove the delegation of `int` to the `__trunc__` special method: `int` will now only delegate to `__int__` and `__index__` (in that order). `__trunc__` continues to exist, but its sole purpose is to support `math.trunc`.
---------
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
PEP 667's description of the planned changes to PyEval_GetLocals
was internally inconsistent when accepted, so the docs added for
gh-74929 didn't match either the current behaviour or the intended
behaviour once gh-118934 is fixed.
This PR updates the documentation and 3.13 What's New to match the
intended behaviour (once gh-118934 is fixed).
It also tidies up lingering references to `f_locals` always being a
dictionary (this hasn't been true since at least when custom
namespace support for class statement execution was added)
* Add docs for new APIs
* Add soft-deprecation notices
* Add What's New porting entries
* Update comments referencing `PyFrame_LocalsToFast()` to mention the proxy instead
* Other related cleanups found when looking for refs to the deprecated APIs
* Passing a string as the "real" keyword argument is now an error;
it should only be passed as a single positional argument.
* Passing a complex number as the "real" or "imag" argument is now deprecated;
it should only be passed as a single positional argument.
* Remove the equivalence with real+imag*1j which can be incorrect in corner
cases (non-finite numbers, the sign of zeroes).
* Separately document the three roles of the constructor: parsing a string,
converting a number, and constructing a complex from components.
* Document positional-only parameters of complex(), float(), int() and bool()
as positional-only.
* Add examples for complex() and int().
* Specify the grammar of the string for complex().
* Improve the grammar of the string for float().
* Describe more explicitly the behavior when real and/or imag arguments are
complex numbers. (This will be deprecated in future.)
The Full Grammar specification in the docs omits rule actions, so grammar rules that raise a syntax error looked like valid syntax.
This was solved in ef940de by hiding those rules in the custom syntax highlighter.
This moves all syntax-error alternatives to invalid rules, adds a validator that ensures that actions containing RAISE_SYNTAX_ERROR are in invalid rules, and reverts the syntax highlighter hack.
GH-25416 accidentally replaced a reference to the *stderr* argument of
`subprocess.run` with a reference to the *stdin* argument. *stdin* is
not affected by the `check_output` option.
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
Structure layout, and especially bitfields, sometimes resulted in clearly
wrong behaviour like overlapping fields. This fixes
Co-authored-by: Gregory P. Smith <gps@python.org>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
pathlib now treats "`.`" as a valid file extension (suffix). This brings
it in line with `os.path.splitext()`.
In the (private) pathlib ABCs, we add a new `ParserBase.splitext()` method
that splits a path into a `(root, ext)` pair, like `os.path.splitext()`.
This method is called by `PurePathBase.stem`, `suffix`, etc. In a future
version of pathlib, we might make these base classes public, and so users
will be able to define their own `splitext()` method to control file
extension splitting.
In `pathlib.PurePath` we add optimised `stem`, `suffix` and `suffixes`
properties that don't use `splitext()`, which avoids computing the path
base name twice.
Attempted to simultaneously reduce verbosity, while more descriptively
describing behavior.
Fix links (RLock acquire/release previously linking to Lock
acquire/release, seems like bad copy pasta).
Add a seealso for with-locks.
Switch section to use bullet points.
---------
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
When updating the new exec note added in gh-119235 as part of the
PEP 667 general docs PR, I suggested a workaround that isn't valid.
The first half of the note is still reasonable, so just omit the invalid text.
* bpo-15987: Implement ast.compare
Add a compare() function that compares two ASTs for structural equality. There are two set of attributes on AST node objects, fields and attributes. The fields are always compared, since they represent the actual structure of the code. The attributes can be optionally be included in the comparison. Attributes capture things like line numbers of column offsets, so comparing them involves test whether the layout of the program text is the same. Since whitespace seems inessential for comparing ASTs, the default is to compare fields but not attributes.
ASTs are just Python objects that can be modified in arbitrary ways. The API for ASTs is under-specified in the presence of user modifications to objects. The comparison respects modifications to fields and attributes, and to _fields and _attributes attributes. A user could create obviously malformed objects, and the code will probably fail with an AttributeError when that happens. (For example, adding "spam" to _fields but not adding a "spam" attribute to the object.)
Co-authored-by: Jeremy Hylton <jeremy@alum.mit.edu>
The PEP 649 implementation will require a way to load NotImplementedError
from the bytecode. @markshannon suggested implementing this by converting
LOAD_ASSERTION_ERROR into a more general mechanism for loading constants.
This PR adds this new opcode. I will work on the rest of the implementation
of the PEP separately.
Co-authored-by: Irit Katriel <1055913+iritkatriel@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Erlend E. Aasland <erlend@python.org>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
* expand on What's New entry for PEP 667 (including porting notes)
* define 'optimized scope' as a glossary term
* cover comprehensions and generator expressions in locals() docs
* review all mentions of "locals" in documentation (updating if needed)
* review all mentions of "f_locals" in documentation (updating if needed)
* Remove description of issue fixed in 3.5 from autospeccing guide
* Make autospeccing note text more succint and lint whitespace
* Add linting changes (missed in last commit)
---------
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
Many users think they want a locals argument for various reasons but they do not
understand that it makes code be treated as a class definition. They do not want
their code treated as a class definition and get surprised. The reason not
to pass locals specifically is that the following code raises a `NameError`:
```py
exec("""
def f():
print("hi")
f()
def g():
f()
g()
""", {}, {})
```
The reason not to leave out globals is as follows:
```py
def t():
exec("""
def f():
print("hi")
f()
def g():
f()
g()
""")
```
Nobody has been using a Sun machine for a long time. When I saw
this sentence in a lightning talk just now, I thought it was talking
about sending Python code on a spacecraft.
I honestly forgot this slipped into 3.13, but I think it's worth highlighting more, as it is a PEP-sized change that makes the type system significantly more powerful.
@Yhg1s I think it's also worth mentioning in your release announcements.
Suppress all `OSError` exceptions from `pathlib.Path.exists()` and `is_*()`
rather than a selection of more common errors as we do presently. Also
adjust the implementations to call `os.path.exists()` etc, which are much
faster on Windows thanks to GH-101196.
Follow-up of gh-101693. The previous DeprecationWarning is replaced with
raising sqlite3.ProgrammingError.
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Remove support for supplying additional positional arguments to
`PurePath.relative_to()` and `is_relative_to()`. This has been deprecated
since Python 3.12.
Make a rough editorial pass over Python 3.13's What's New document. Add the
release highlights, remove or merge some duplicated entries, and reorder
some of the sections (removals should really go before future deprecations).
Callbacks registered in the tkinter module now take arguments as
various Python objects (int, float, bytes, tuple), not just str.
To restore the previous behavior set tkinter module global wantobject to 1
before creating the Tk object or call the wantobject() method of the Tk object
with argument 1.
Calling it with argument 2 restores the current default behavior.
The provided example was incorrect:
- The example enum was missing the `int` mixin as implied by the context
- The value of `int('1a', 16)` was incorrectly given as 17
(should be 26)
Ned Deily
edson duarte
Russell Keith-Magee
Donghee Na
Serhiy Storchaka
Dominic H
Jelle Zijlstra
Jan Musílek
Ulrik Södergren
Bénédikt Tran
mirelagrigoras
Timon Viola
sobolevn
Tian Gao
Rafael Fontenelle
AN Long
Hugo van Kemenade
CBerJun
Kirill Podoprigora
Barney Gale
Yuxin Wu
Sergey B Kirpichev
Ali Tavallaie
Jongbum Won
Vinay Sajip
Amin Alaee
da-woods
Danny Yang
Victor Stinner
Wim Jeantine-Glenn
Steve Dower
Kumar Aditya
Alexander Bessman
Kerim Kabirov
chaen
Sam Gross
Christian Clauss
Pablo Galindo Salgado
Alek Kowalczyk
Nyakku Shigure
Nice Zombies
Eric Snow
blhsing
Mark Shannon
Awbert
Petr Viktorin
Jan Kaliszewski
Saul Pwanson
Carol Willing
Frank Dana
Gregory P. Smith
mm-matthias
Nyuan Zhang
Ruben Vorderman
Owain Davies
naglis
Clinton
Erlend E. Aasland
Aditya Borikar
Jacob Walls
David Lowry-Duda
Irit Katriel
shurj0
Paulo Freitas
Trey Hunner
Jason R. Coombs
Solomon Himelbloom
Mark Dickinson
Alyssa Coghlan
Raymond Hettinger
Zachary Ware
Dino Viehland
Bradley Reynolds
Lincoln
Matthias Görgens
Justin Kunimune
Savannah Ostrowski
Alex Waygood
Wulian233
Ned Batchelder
Carlos Meza
uıɐɾ ʞ ʇɐɯɐs
Mathijs Mortimer
Batuhan Taskaya
Landon Wood
Brett Simmers
Josh Cannon
Blaise Pabon
Daniel Williams
Melanie Arbor
Shauna
Tialo
Hood Chatham
Sebastian Rittau
David Foster
Lysandros Nikolaou
Shantanu
pochmann3
Adam Dangoor
Inada Naoki
Dobatymo
Xie Yanbo
Thomas Wouters
trag1c
chrysn
Momo Eissenhauer