Re: [Docutils-develop] Release 0.20

[Guenter M. <mi...@us...>]

Dear Adam,

On 2023-04-06, Adam Turner wrote:

>>> The main use(s) here would be for publishing binary formats (e.g. ODT)
>>> to a ``bytes`` object in memory rather than writing to disk, or for
>>> when call-sites use a non-unicode ``output_encoding`` setting. 

>> IMV, the extended ``publish_string()`` providing

>>    publish_string(..., auto_encode=False) --> OutString
>>    publish_string(..., auto_encode=True) --> bytes
>     
>> with `OutString` beeing 100% compatible with `str` and easily convertible
>> to bytes via ``bytes(result)`` can cater for such needs. 

>> (Also, is should not be too surprising that `publish_string` returns a
>> `bytes` instance if the user tells it to "auto_encode".)

> Fair enough, though I suppose I had seen ``auto_encode`` as part of
> moving to a position where (eventually) ``publish_string`` always
> returns an instance of Python's ``str`` class, rather than the current
> overloaded return type. 

While I favour keeping "auto_encode" over a seprate `publish_bytes()`
function, I left the decision about the end state of this transition open...

> In the scenario I was imagining, users of
> Docutils who know that they want ``bytes`` output could change to using
> ``publish_bytes`` in Docutils 0.20, and not need to worry about the
> future of ``publish_string`` or the ``auto_encode`` argument. (There
> is also an argument for self-documenting code, in that if you know that
> you want ``bytes``, using the function with ``bytes`` in the name helps
> a non-expert reader to understand what is going on.)

I imagine that in absence of `publish_bytes` users knowing they need an
"encoded string" (i.e. `bytes`) will find `publish_string` and either
just use ``bytes(publish_string(...))`` or read the help string or docs and
use ``publish_string(..., auto_encode=True)``.
This will become easier with type annotations in the source.

(How about starting with annotating "core.py". I only postponed this because
I don't know whether a partially type-hinted module will interfere with the
present 3rd-party type hint stubs.)

> If you have time, perhaps you could commit your patch (or the latest
> version thereof), and we could make progress from there? As far as I
> can tell, the only unresolved point at the moment ahead of releasing
> Docutils 0.20 is the future of ``publish_bytes``.

This is now [r9336].
A patch removing `publish_bytes` waits in a branch in my local Git repo.

Thanks,
Günter