Re: [Docutils-develop] Release 0.20

[Adam T. <aat...@ou...>]

Dear Günter,

>> 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. 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.)

>> If it is to be removed, perhaps we could provide a recipie in the
>> documentation for how to manage publishing to an in-memory byte
>> sequence.

> This is part of the `publish_string()` docstring in my patch::

>    If `auto_encode` is True, the output is encoded according to the
>    `output_encoding`_ setting; the return value is a `bytes` instance
>    (unless `output_encoding`_ is "unicode",
>    cf. `docutils.io.StringOutput.write()`).

Sorry, I had forgotten about this part of your patch.

-----------

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``.


Thanks,
Adam