[Docutils-develop] [docutils:bugs] Re: #441 Move from "optparse" to "argparse".

[Günter M. <mi...@us...>]

On 2022-01-25, Adam Turner wrote:

>> I am just working on a way to disentangle frontend.OptionParser and frontend.ConfigParser but this is a topic for bug:#441

> Sounds good -- happy to review a proposed design. 

My major sticking point is the cross-referencing: OptionParser uses a
ConfigParser instance and passes "self" to config_parser.read() because
ConfigParser requires an instance of OptionParser!

The reason is that some settings have side-effects (overwriting other
settings) that need to be resolved for each config file before reading the
next to keep the settings priority as expected. (cf. the attached
documentation)

My idea is to scale back `frontend.ConfigParser` to provide backwards
compatibility and the custom `optionxform()` while moving the
setting_validation() to `frontend.OptionParser`.

The `OptionParser` would then loop over the config_files,
read them one-by-one with `config_parser(read(file))`, 
select settings from the "active" config file sections, and
"validate" them (including the overwriting of affected settings).

If you agree that this is a step in the right direction, I would try to
prepare a patch.

> I'd propose making the `--config` flag simply store the path to the
> file, and then add it to the list of config files to be read.

Mind, that the list of config files to read is processed before 
parsing the command line. 
An option parser based on "argparse" can use the `parse_known_args()` method
to pre-parse the command line, append additional config files and proceed.
...

> Ideally, we would construct a single `ArgumentParser` object and add
> arguments "normally" through `parser.add_argument`. 
> The problem here is  that subclasses can filter settings_spec (through  filter_settings_spec). 
...
> if settings_spec tuples were treated as immutable, then things would be much simpler. 

Actually, both `SettingsSpec` instances and `SettingsSpec.settings_spec`
tuples do not "mutate" in Docutils. 
`filter_settings_spec()` is only used in *creating* a settings spec tuple 
from the settings specification of a base or "sister" class in the class definitions of the "xetex", "html4" and "html5" writers.
Other components ('pep_html", "s5_html")  overwrite just some default values with `SettingsSpec.setting_default_overrides` and keep the  parent's  `setting_spec`.)

The Sphix "html" writer loops over the base class' settings_spec tuple
 in order to set a default value in writers/html.py:59
https://github.com/sphinx-doc/sphinx/blob/4.x/sphinx/writers/html.py
This should be changed (before retiring the old format)
to use `settings_default_overrides` instead.

> We could also move to a model (a la stdlib `dataclasses` where we
> simply specify the setting name, type and default within the Component
> itself.

This sounds like what I have in mind with a new data format to replace the
tuple `SettingsSpec.settings_spec` (mind, that `Component` inherits
`SettingsSpec`).

> The front-end tools could then use that information (or a
> mapping of settings to command line options or similar) to create the
> CLI arguments. 

I would keep the processing of settings specifications in the "frontend"
module with front-ends deploying them via the `core.Publisher` class.

> I think this would be cleanest, but this cannot be done overnight.

But, maybe we should discuss more about a clean end state before
(or in parallel) with a step-by step review of the optparse-argparse switch.



Attachments:

- [runtime-settings-detailled.txt](https://sourceforge.net/p/docutils/bugs/_discuss/thread/c76f9a2618/18f5/7f0c/attachment/runtime-settings-detailled.txt) (13.2 kB; text/plain)


---

** [bugs:#441] Move from "optparse" to "argparse".**

**Status:** open
**Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde
**Last Updated:** Mon Jan 31, 2022 09:43 PM UTC
**Owner:** Günter Milde


The optparse documentation says:
> Deprecated since version 3.2: The optparse module is deprecated and will not be developed further; development will continue with the argparse module.

We are currently suppressing related deprecation warnings in the test suite.
After raising the Python dependency to >=3.7, now may be the right time to make the move.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.