[Python-Dev] Pathlib enhancements - acceptable inputs and outputs for __fspath__ and os.fspath()

[Nick Coghlan]

On 14 April 2016 at 12:49, Nick Coghlan <ncoghlan at gmail.com> wrote:
> The API could be something like:
>
> - os.fspath -> str-or-bytes
> - os.fsencode -> bytes (with coercion from str)
> - os.fsdecode -> str (with coercion from bytes)
> - os.strpath -> str (no coercion)

There seems to be fairly broad opposition to the idea of defining the
public API in terms of what os and os.path are likely to need, which
reminded me of Koos's suggestion of using a private API for the
str-or-bytes variant. That approach would give us something like:

- os.fspath -> str (no coercion)
- os.fsdecode -> str (with coercion from bytes)
- os.fsencode -> bytes (with coercion from str)
- os._raw_fspath -> str-or-bytes (no coercion)

(with "coercion" referring to how the result of __fspath__ and any
directly passed in str or bytes objects are handled)

The leading underscore on _raw_fspath would be of the "this is a
documented and stable API, but you probably don't want to use it
unless you really know what you're doing" variety, rather than the
"this is an undocumented and potentially unstable private API"
variety.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia