Menu
▾
▴
docutils-develop
|
From: Günter M. <mi...@us...> - 2022-01-06 15:02:46
|
--- ** [bugs:#441] Move from "optparse" to "argparse".** **Status:** open **Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde **Last Updated:** Thu Jan 06, 2022 03:02 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. |
|
From: Günter M. <mi...@us...> - 2022-01-06 15:08:00
|
Intended steps:
* Fully backwards compatible change of "settings spec" processing.
* Remove the DeprecationWarning filter in the test suite.
* Consider moving to a new settings-spec format based on ordered dicts.
* Converter class for the current format.
* Use the new format in Docutils component.
* Deprecate the old format and related helpers/hacks in "utils".
Help welcome.
---
** [bugs:#441] Move from "optparse" to "argparse".**
**Status:** open
**Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde
**Last Updated:** Thu Jan 06, 2022 03:02 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. |
|
From: Chris S. <chr...@us...> - 2022-01-06 15:16:13
|
sounds good > Consider moving to a new settings-spec format based on ordered dicts Minor note, since python 3.7 standard dicts are guaranteed to be ordered: https://docs.python.org/3/whatsnew/3.7.html --- ** [bugs:#441] Move from "optparse" to "argparse".** **Status:** open **Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde **Last Updated:** Thu Jan 06, 2022 03:08 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. |
|
From: Adam T. <aa-...@us...> - 2022-01-12 16:16:37
|
Sorry for the radio silence! I've made some progress in this branch ( https://github.com/AA-Turner/docutils/tree/argparse ) -- currently fixing the last few failing tests and then will clean up the commit history and propose as a patch. The work does lead me to ask about how pace of deprecations / removal (partly to help my chances of getting the patch accepted, and partly for 'nicer' code). Can I remove the "old" config parsing logic? It was deprecated in 2003 in R1643 ( https://sourceforge.net/p/docutils/code/1643/ ). Equally, when deprecating features that would be obsoleted by my changes, would you suggest announcing removal in v0.20.0, v1.0.0, etc? (I have seen the proposed deprecation policy -- my personal feedback would be that it should go along with a versioning policy. Python itself is special in that they can't really bump the major version. If Docutils adopted semantic versioning, then removals would simply trigger a major version bump -- we could add additional language on at least X minor releases with deprecations before removal, for example). A --- ** [bugs:#441] Move from "optparse" to "argparse".** **Status:** open **Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde **Last Updated:** Thu Jan 06, 2022 03:16 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. |
|
From: Günter M. <mi...@us...> - 2022-01-12 23:15:54
|
On 2022-01-12, Adam Turner wrote: > Sorry for the radio silence! No need to apologise. Docutils development is slow and there is real life, too. > I've made some progress in this branch Looks promising, thank you. I would not add as many leading underscores, though, to keep consistency with the existing code base. Exceptions are new additions that are bound to go/change in near future or minor auxiliary objects that are only locally used. Before the move to dict based arguments_spec, give us a pause to plan/discuss/document what the specs shall look like. > The work does lead me to ask about how pace of deprecations / removal That is a tricky question. I like clean code but I got burned several times after removing obscure parts only to find out that this broke applications with indirect dependency on Docutils and maintainers not knowing about the project lest reading our RELEASE-NOTES :( > Can I remove the "old" config parsing logic? It was deprecated in 2003 > in R1643 ( https://sourceforge.net/p/docutils/code/1643/ ). Not yet, I am afraid. I changed the "may be removed" to "will be removed" two months ago in [r8880]. Next step would be to add a removal version... > Equally, when deprecating features that would be obsoleted by my > changes, would you suggest announcing removal in v0.20.0, v1.0.0, etc? I don't know whether there will be v0.20 at all. The idea is to reconcile the reality (Docutils is used as if it were mature) and the version number (<1) once the API sufficiently defined a deprecation policy is agreed. Alternatively, 1.0.0 could be pushed off a while and be a clean start (including removals currently scheduled for 1.2). This would require re-wording the DeprecationWarnings to say 0.21 or later. > (I have seen the proposed deprecation policy -- my personal feedback > would be that it should go along with a versioning policy. This discussion deserves a separate thread/ticket. Thanks, Günter --- ** [bugs:#441] Move from "optparse" to "argparse".** **Status:** open **Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde **Last Updated:** Wed Jan 12, 2022 04:16 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. |
|
From: Adam T. <aa-...@us...> - 2022-01-12 23:43:52
|
> leading underscores OK. My intention was to not expand the module's public API any further, on the underscored-names-are-private convention. However I do remember the discussion about more clearly defining Docutils' public API -- perhaps that work should happen first. (My suggestion would be a single document listing the modules/classes that form the public API, and then reinforcing that in the code with `__all__` and use of underscores, etc.) > Before the move to dict based arguments_spec Fair enough -- I have proposed the simplest possible change, which is just replicating `kwargs` of `ArgumentParser.add_argument`. I'd probably suggest sticking with this (similarly to how settings_spec delegates much to `OptionParser.add_option`), although of course other designs could be used. > this broke applications :( > Not yet, I am afraid Fair enough! A > once the API sufficiently defined a deprecation policy is agreed OK, seems this is a blocker to a few of my proposed changes. I can open a ticket to start a discussion if there's not one already? I think the API, versioning, and deprecation conversations do probably link to each other quite a bit. --- ** [bugs:#441] Move from "optparse" to "argparse".** **Status:** open **Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde **Last Updated:** Wed Jan 12, 2022 04:16 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. |
|
From: Günter M. <mi...@us...> - 2022-01-14 12:51:58
|
On 2022-01-12, Adam Turner wrote: >> ... move to dict based arguments_spec > Fair enough -- I have proposed the simplest possible change, which is > just replicating `kwargs` of `ArgumentParser.add_argument`. We need to keep compatibility the current "settings spec" specification as this is part of the "drop-in" extension API (used by, e.g., "myst-docutils"). After deciding on a new interface (maybe just an add_argument `kwargs` dict), we can use this in Docutils and deprecate the old interface. ... >> once the API sufficiently defined a deprecation policy is agreed > OK, seems this is a blocker to a few of my proposed changes. I can open > a ticket to start a discussion if there's not one already? Yes, this may help. For the time beeing, we may follow the [Python rules](https://www.python.org/dev/peps/pep-0387/#backwards-compatibility-rules): incompatible changes require an advance warning at least 2 minor version before implentation. The change from 0.x to 1.x, although increasing the major number should signify a major changes in commitment rather than API. (cf. https://docutils.sourceforge.io/docs/dev/policies.html#version-identification) Thanks, Günter --- ** [bugs:#441] Move from "optparse" to "argparse".** **Status:** open **Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde **Last Updated:** Wed Jan 12, 2022 11: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. |
|
From: Adam T. <aa-...@us...> - 2022-01-15 04:02:11
|
> We need to keep compatibility the current "settings spec" specification Yes of course. I should have maybe explained a little -- I added a transparent conversion function from `arguments_spec` to `settings_spec` and vice versa. If you access `.settings_spec` on any component just with `arguments_spec` defined, you will get a valid `settings_spec` tuple returned (as if by magic!) > Yes, this may help. OK, will do. A --- ** [bugs:#441] Move from "optparse" to "argparse".** **Status:** open **Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde **Last Updated:** Wed Jan 12, 2022 11: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. |
|
From: Guenter M. <mi...@us...> - 2022-01-16 22:17:45
|
On 2022-01-15, Adam Turner via Docutils-develop wrote: >> We need to keep compatibility the current "settings spec" specification > Yes of course. I should have maybe explained a little -- I added a > transparent conversion function from `arguments_spec` to > `settings_spec` and vice versa. Yes, this is important. My point was that we cannot remove this little gem even if all settings specs in the Docutils code were changed to use a dict. Thanks for the clarification and thanks for your work. Günter |
|
From: Adam T. <aa-...@us...> - 2022-01-17 00:42:23
|
Hi, as promised please find the patch at https://github.com/AA-Turner/docutils/pull/8 // https://github.com/AA-Turner/docutils/pull/8.patch It will likely be easiest to review commit-by-commit. Note as discussed earlier, all code expecting a `settings_spec` tuple will can get one (see https://github.com/AA-Turner/docutils/pull/8/files#r785578670 ). Would appreciate any feedback or reviews! A --- ** [bugs:#441] Move from "optparse" to "argparse".** **Status:** open **Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde **Last Updated:** Sat Jan 15, 2022 04:02 AM 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. |
|
From: Günter M. <mi...@us...> - 2022-01-19 00:21:17
|
Thank you for the reworked patch set! > It will likely be easiest to review commit-by-commit. Lets start with 1/4 I do not see the benefit in the new helper functions outweighting the refactoring effort: Usage (after all 4 commits): ========================================= === ===== ========= new function lib tests dev-tools ========================================= === ===== ========= frontend.read_config_files 2 frontend.config_files_settings 1 1 frontend.get_default_settings 1 7 1 frontend.get_settings_with_defaults 1 frontend.parse_args 1 Publisher.config_section_to_settings_spec 3 ========================================= === ===== ========= Making OptionParser.get_standard_config_files() a class method could be combined with the removal of the mod_python hack. The commit message or should note the reason (mod_python beeing no longer developed and too old) with a link to, e.g., https://en.wikipedia.org/wiki/Mod_python. I see that after all 4 commits, frontend.OptionParser is still present (is it also fully backwards compatible?) Would it be feasible to have a minimal change where only the Values, Option, and OptionParser classes were based on "argparse" instead of "optparse" Then we can start moving to frontend.ArgumentParser and using "argparse" features step by step. --- ** [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 17, 2022 12:42 AM 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. |
|
From: Adam T. <aa-...@us...> - 2022-01-20 02:57:30
|
> I do not see the benefit in the new helper functions outweighting the refactoring effort:
The functions are of most use to downstream developers, I'd argue. It provides a higher level abstraction which means you don't need to know about the internals of how `OptionParser` &c work.
`get_settings_with_defaults` is tenuous, but I was trying to move to a point where the `OptionParser` and `ConfigParser` classes are only used in `docutils.frontend` -- providing a cleaner seperation of concerns and making any future refactorings easier.
> could be combined with the removal of the mod_python hack.
Done and pushed
> frontend.OptionParser is still present (is it also fully backwards compatible?)
I didn't remove it or change the name as many downstream consumers rely on it. It is fully backwards compatible, yes -- mostly due to the `settings_spec` <--> `arguments_spec` converters. It is deprecated, though (through the module level `__getattr__`).
> Would it be feasible to have a minimal change where only the Values, Option, and OptionParser classes were based on "argparse" instead of "optparse"
It would be very difficult. optparse makes fundamentally different assumptions than argparse, which took a while to sort out and convert. E.g. the parsing of config files, the "validator" behaviour -- there is a hack at the moment to intercept validators that downstream users have used and wrap them with an argparse `Action`.
Broadly though, commit 2 ("Update to use argparse") can be made standalone if you want it to be -- I would be disapointed not to have the helper functions, but strictly they are not required.
I think that is probably as minimal as it gets -- it was difficult enough to rewrite everything keeping 100% backwards compatability -- and I can't make any assumptions about which names are "safe" to remove -- e.g. I had to keep a no-op definition for `Option` as downstream users *might* use it.
A
---
** [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 17, 2022 12:42 AM 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. |
|
From: Adam T. <aa-...@us...> - 2022-01-25 23:50:36
|
From FR# 88 > 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. 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. `get_config_file_settings` should also probably be removed from `OptionParser` -- instead a dict should be returned by `ConfigParser` and merged in. > I didn't go into detail intentionally so as not to spark a debate about these parts, but I do think (eventually) simplifying these interactions can lead to a cleaner codebase. > Docutils has an elaborated configuration framework which actually predates the "optparse" module. Later development of "Optik" into "optparse" and then "argparse" implemented some of the abstractions and enhancements offered by Docutils in a different way. 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). I've never seen this implemented in the way Docutils does it before -- if settings_spec tuples were treated as immutable, then things would be much simpler. ________ 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. 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 think this would be cleanest, but this cannot be done overnight. _____ Did you have a chance to review my comments above in the previous post? It would be good to get some of this merged, or know what is blocking it // needs changing. A --- ** [bugs:#441] Move from "optparse" to "argparse".** **Status:** open **Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde **Last Updated:** Thu Jan 20, 2022 02:57 AM 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. |
|
From: Günter M. <mi...@us...> - 2022-01-31 22:39:20
|
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. |
|
From: Adam T. <aa-...@us...> - 2022-01-27 00:11:14
|
I just rebased the branch onto the latest master https://github.com/AA-Turner/docutils/pull/8 A --- ** [bugs:#441] Move from "optparse" to "argparse".** **Status:** open **Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde **Last Updated:** Tue Jan 25, 2022 11:50 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. |
|
From: Adam T. <aa-...@us...> - 2022-01-27 17:43:35
|
Re-rebased A --- ** [bugs:#441] Move from "optparse" to "argparse".** **Status:** open **Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde **Last Updated:** Thu Jan 27, 2022 12:11 AM 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. |
|
From: Adam T. <aa-...@us...> - 2022-01-29 23:29:07
|
Re-re-rebased. It is a not-insignficant amount of work each time to rebase the changes, so please may I ask for a review, or to know what is blocking a review? ( @milde @grubert ) I would like to progress these changes -- I've been holding off on other potential suggestions so as not to have merge conflicts with myself. A --- ** [bugs:#441] Move from "optparse" to "argparse".** **Status:** open **Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde **Last Updated:** Thu Jan 27, 2022 05: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. |
|
From: Günter M. <mi...@us...> - 2022-01-31 21:37:59
|
Sorry for the long delay. Here my update on patch 1/6. On 2022-01-20, Adam Turner wrote: > The functions are of most use to downstream developers, I'd argue. It > provides a higher level abstraction which means you don't need to know > about the internals of how `OptionParser` &c work. You don't need to know these details, when using the intended entry points: * the framework provided in `docutils.core` for front-end tools and applications deploying docutils * the `readers.Reader`, `parsers.Parser`, `writers.Writer`, and `transforms.Transforms` base classes for drop-in components. For concrete use-cases where this interface is insufficient, we can work on enhancement and improvement, but I don't want to start a parallel, undocumented framework of "access functions". > ... I was trying to move to a point where the `OptionParser` and > `ConfigParser` classes are only used in `docutils.frontend` -- > providing a cleaner seperation of concerns and making any future > refactorings easier. The `frontend.ConfigParser` is only used in `frontend.OptionParser` already. Use of `frontend.OptionParser` will drop significantly with just one helper function: `frontend.get_default_settings()`. Remaining cases can be handled later (before deprecating the old OptionParser). ... > I think that is probably as minimal as it gets -- it was difficult > enough to rewrite everything keeping 100% backwards compatability -- > and I can't make any assumptions about which names are "safe" to remove We can check for usage in Sphinx and myst, this gives at least an indication. I'll attach my proposal for a pre-conversion cleanup. --- ** [bugs:#441] Move from "optparse" to "argparse".** **Status:** open **Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde **Last Updated:** Sat Jan 29, 2022 11:29 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. |
|
From: Adam T. <aa-...@us...> - 2022-01-31 21:43:22
|
> For concrete use-cases where this interface is insufficient, we can work on enhancement and improvement, but I don't want to start a parallel, undocumented framework of "access functions". Fair enough. From the comment below "Use of frontend.OptionParser will drop significantly with just one helper function" are you happy to keep `frontend.get_default_settings()`? I'll review the patch you attached, thanks! A --- ** [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:28 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. |
|
From: Günter M. <mi...@us...> - 2022-01-31 22:41:03
|
On 2022-01-31, Adam Turner wrote: > From the comment below "Use of frontend.OptionParser will drop > significantly with just one helper function" are you happy to keep > `frontend.get_default_settings()`? I am fine with this one. It needs a docstring and a mentioning in the module docstring, though. Thanks, Günter Milde --- ** [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 10:35 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. |
|
From: Adam T. <aa-...@us...> - 2022-01-31 23:28:35
|
Perfect, thanks! A --- ** [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 10:35 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. |
|
From: Günter M. <mi...@us...> - 2022-02-03 14:45:04
|
First draft on the OptionParser/ConfigParser separation:
Clear separation of duties for OptionParser and ConfigParser.
The ConfigParser:
* Reads and parses the sequence of configuration files passed to its
`read()` method.
* Stores the extracted setting values as stings.
* Collects settings from "active sections" in an "ACTIVE" section.
The OptionParser:
* Validates the settings and converts the values to the expected data type.
* Eventually updates the settings from command line arguments.
TODO: Validate configuration file settings in the ConfigParser?
+1 Collecting "appending_settings" becomes easier.
-1 Requires inheriting configparser.RawConfigParser to allow storing values other than strings.
(Alternative: collect in a ``dict`` instance instead of ACTIVE section.)
-1 Requires knowledge of all validation functions and converters in the ConfigParser.
The attached files provide a working implementation and minimal test script for this approach.
Attachments:
- [cf_parser.py](https://sourceforge.net/p/docutils/bugs/_discuss/thread/c76f9a2618/6a1c/attachment/cf_parser.py) (7.0 kB; text/x-python)
- [config_list.txt](https://sourceforge.net/p/docutils/bugs/_discuss/thread/c76f9a2618/6a1c/attachment/config_list.txt) (342 Bytes; text/plain)
- [config_list_2.txt](https://sourceforge.net/p/docutils/bugs/_discuss/thread/c76f9a2618/6a1c/attachment/config_list_2.txt) (359 Bytes; text/plain)
- [test.conf](https://sourceforge.net/p/docutils/bugs/_discuss/thread/c76f9a2618/6a1c/attachment/test.conf) (2.2 kB; application/octet-stream)
- [test2.conf](https://sourceforge.net/p/docutils/bugs/_discuss/thread/c76f9a2618/6a1c/attachment/test2.conf) (281 Bytes; application/octet-stream)
- [test3.conf](https://sourceforge.net/p/docutils/bugs/_discuss/thread/c76f9a2618/6a1c/attachment/test3.conf) (190 Bytes; application/octet-stream)
- [test_cf_parser.py](https://sourceforge.net/p/docutils/bugs/_discuss/thread/c76f9a2618/6a1c/attachment/test_cf_parser.py) (8.8 kB; text/x-python)
---
** [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 11:28 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. |
|
From: Günter M. <mi...@us...> - 2022-02-03 14:59:51
|
I am sorry for the delay and the additional work. The change turned out to be far more complicated than expected when I first proposed it. In order to have informed choices, I had to study the current state in detail first. (See [r8996] for a by-product.) I propose to start with clean up and deprecation steps to smoothe the actual OptionParser -> ArgumentParser change. (A proposal for the two first steps is attached.) Attachments: - [0001-Small-fixes-mostly-documentation-Test-more-list-settings.patch](https://sourceforge.net/p/docutils/bugs/_discuss/thread/c76f9a2618/45c6/9106/2d9c/5575/attachment/0001-Small-fixes-mostly-documentation-Test-more-list-settings.patch) (8.2 kB; text/x-patch) - [0002-Clean-up-docutilsfrontend-before-the-switch-to-arparse.patch](https://sourceforge.net/p/docutils/bugs/_discuss/thread/c76f9a2618/45c6/9106/2d9c/5575/attachment/0002-Clean-up-docutilsfrontend-before-the-switch-to-arparse.patch) (10.5 kB; text/x-patch) --- ** [bugs:#441] Move from "optparse" to "argparse".** **Status:** open **Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde **Last Updated:** Thu Feb 03, 2022 02:45 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. |
|
From: Adam T. <aa-...@us...> - 2022-02-05 01:41:02
|
These seem fine, I'd go ahead and apply them. For reference I opened https://github.com/sphinx-doc/sphinx/pull/10162 to update `sphinx.writers.html` to use `settings_default_overrides`. A --- ** [bugs:#441] Move from "optparse" to "argparse".** **Status:** open **Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde **Last Updated:** Thu Feb 03, 2022 02:59 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. |
|
From: Adam T. <aa-...@us...> - 2022-02-05 02:00:27
|
For reference "these" are the two patches 0001-Small... and 0002-Clean... -- I reviewed these locally. I assumed that these replaced the earlier "argparse-gm.patch" A --- ** [bugs:#441] Move from "optparse" to "argparse".** **Status:** open **Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde **Last Updated:** Sat Feb 05, 2022 01:40 AM 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. |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X