Re: Release 0.20

Dear Adam,

I am glad to hear from you again.

On 2023-03-24, Adam Turner wrote:

...

> For interest, Sphinx has a policy__ to support:
> "all minor versions of Python released in the past 42 months from the ...
> release date with a minimum of 3 minor versions of Python"

> __ https://www.sphinx-doc.org/en/master/internals/release-process.html#python-version-support-policy

Thank you for the pointer. 
I'd like to keep support for the default Python version of Debian/stable
(even if this is longer than 42 months old).


>>> * Future of ``core.publish_string()`` API function:

>>>   a) Keep current behaviour ::

>>>       def publish_string(source: Union[bytes, str],
>>>                          [...]
>>>                          enable_exit_status=False) -> Union[bytes, str]

>>>      as "wart", just improve documentation?

>>>   b) Deprecate ``publish_string()`` and provide new ``publish_str()``
>>>      and ``publish_bytes()`` functions?

>>>   c) Return a sub-class of ``str`` with ``__bytes__()`` method that
>>>      encodes with ``encoding`` and ``encoding_errors`` set to the
>>>      "output_encoding" and "output_encoding_errors" setting values?

>>>      - as "subtly" changed behaviour, or
>>>      - with a new function replacing ``publish_string()``
>>>        (find a good name!)?

>>>   Proposal [GM]
>>>     - explore c)
>>>     - remove ``core.publish_bytes()`` before releasing 0.20.

>> I prepared a patch for option c) with a new function attribute
>> 'auto_encode for `core.publish_string()`. This would allow to keep the
>> name and switch to a behaviour matching it (returning a string, not
>> bytes) gradually (by switching the default value and eventually
>> removing the option later). See below.

> I am content to go with option (c), but I would want to simultaneously announce
> the version where the default would change to ``auto_encode=False`` and the
> version where ``publish_string()`` would only support returning ``str``
> instances.

I suggest to do the default switch 2 versions after announcement, i.e. 0.22
or 1.0 (announce as 0.22 or later).
I would not announce removal of the option now (shold not be earlier than
3.0, maybe never).

> I think that it might be possible to implement the new ``auto_encode``
> parameter without a custom ``str`` subclass,

The problem with exporting an output document as `str` instance
(auto_encode=False) is that

* The output document by default contains an "encoding indicator" (at least
  in HTML and LaTeX) which is determined by the "output_encoding" setting
  (depending on a set of configuration files or command line input which may
  be "programatically overwritten").
  
* A `str` instance has no meta-data storing the "intended encoding".

  The application calling `publish_string()` would have to re-enact the
  configuration parsing or to grep in the string to find out the
  right encoding.

The old approach is to use publish_parts() and from the returned dictionary
use the "document" and "encoding" items.

I am open for other suggestions to solve this problem.  

> I think we should keep the ``publish_bytes()`` function in either case.

I don't see a convincing use case for ``publish_bytes()`` and would
prefer to keep the "core" interface as small as sensible.

Thanks,
Günter



_______________________________________________
Docutils-develop mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-develop

Please use "Reply All" to reply to the list.