Should shutil functions support bytes paths?

[JelleZijlstra]

BPO	46727
Nosy	@serhiy-storchaka, @JelleZijlstra, @AlexWaygood

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2022-02-12.01:43:24.033>
labels = ['type-bug', 'library', '3.11']
title = 'Should shutil functions support bytes paths?'
updated_at = <Date 2022-02-12.01:43:24.033>
user = 'https://github.com/JelleZijlstra'

bugs.python.org fields:

activity = <Date 2022-02-12.01:43:24.033>
actor = 'JelleZijlstra'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation = <Date 2022-02-12.01:43:24.033>
creator = 'JelleZijlstra'
dependencies = []
files = []
hgrepos = []
issue_num = 46727
keywords = []
message_count = 1.0
messages = ['413113']
nosy_count = 3.0
nosy_names = ['serhiy.storchaka', 'JelleZijlstra', 'AlexWaygood']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue46727'
versions = ['Python 3.11']

[JelleZijlstra]

The shutil documentation doesn't say anything about bytes paths, and the CPython unit tests don't test them. But some functions do work with bytes paths in practice, and on typeshed we've received some requests to add support for them in the type stubs.

Links:

• Fix shutil.unpack_archive stub typeshed#6869 (shutil.unpack_archive works with bytes paths, but only sometimes)
• Fix shutil.make_archive stub typeshed#6868 (shutil.make_archive)
• Adjust shutil.move stubs to allow bytes/Pathlike[bytes] args typeshed#6832 (shutil.move accepts bytes paths, except when moving into an existing directory)

My overall impression is that bytes paths sometimes work by accident because they happen to not hit any code paths where we do os.path.join or string concatenation, but relying on them is risky because minor changes in the call site or in the file system can cause the call to break.

Here's three possible proposals:

(1) We document in the shutil docs that only str paths are officially supported. Bytes paths may sometimes work, but do it at your own risk.

(2) We add this documentation, but also make code changes to deprecate or even remove any support for bytes paths.

(3) We decide that bytes paths are officially supported, and we add tests for them and fix any cases where they don't work.

My preference is for (1). (2) feels like gratuitously breaking backward compatibility, and (3) is more work and there is little indication that bytes path support is a desired feature.