New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Argument Clinic: split out global stateless helpers and constants from clinic.py #113317
Comments
Proof-of-concept branch for |
In #113270 (comment), the need for a refactoring of the docstring generation code arose. If we split out formatting helpers and text accumulators into a libclinic, we can also split out the docstring rendering ( |
Follow-up item: when libclinic has been established, we can start partitioning the test suite ( |
FTR, the global |
Moving the text accumulator APIs (
I did some experimenting in Argument-Clinic#30. |
…APIs Replace the internal accumulator APIs by using lists of strings and join(). Yak-shaving for separating out formatting code into a separate file.
…113402) Replace the internal accumulator APIs by using lists of strings and join(). Yak-shaving for separating out formatting code into a separate file. Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Split up clinic.py by establishing libclinic as a support package for Argument Clinic. Get rid of clinic.py globals by either making them class members, or by putting them into libclinic. - Move INCLUDE_COMMENT_COLUMN to BlockPrinter - Move NO_VARARG to CLanguage - Move formatting helpers to libclinic - Move some constants to libclinic (and annotate them as Final)
Split up clinic.py by establishing libclinic as a support package for Argument Clinic. Get rid of clinic.py globals by either making them class members, or by putting them into libclinic. - Move INCLUDE_COMMENT_COLUMN to BlockPrinter - Move NO_VARARG to CLanguage - Move formatting helpers to libclinic - Move some constants to libclinic (and annotate them as Final)
- Move strip_leading_and_trailing_blank_lines() and make it internal to libclinic - Move normalize_snippet() to libclinic - Move format_escape() to libclinic - Move wrap_declarations() to libclinic
Move the following global helpers into libclinic: - format_escape() - normalize_snippet() - wrap_declarations() Also move strip_leading_and_trailing_blank_lines() and make it internal to libclinic.
…APIs (python#113402) Replace the internal accumulator APIs by using lists of strings and join(). Yak-shaving for separating out formatting code into a separate file. Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
…3414) Split up clinic.py by establishing libclinic as a support package for Argument Clinic. Get rid of clinic.py globals by either making them class members, or by putting them into libclinic. - Move INCLUDE_COMMENT_COLUMN to BlockPrinter - Move NO_VARARG to CLanguage - Move formatting helpers to libclinic - Move some constants to libclinic (and annotate them as Final)
…113438) Move the following global helpers into libclinic: - format_escape() - normalize_snippet() - wrap_declarations() Also move strip_leading_and_trailing_blank_lines() and make it internal to libclinic.
We should put some thought into how we structure the rest of libclinic. Victor hashed out a proof-of-concept libclinic in
|
Rework error handling in the C preprocessor helper. Instead of monkey- patching the cpp.Monitor.fail() method from within clinic.py, rewrite cpp.py to use a subclass of the ClinicError exception. Yak-shaving in preparation for putting cpp.py into libclinic.
Rework error handling in the C preprocessor helper. Instead of monkey- patching the cpp.Monitor.fail() method from within clinic.py, rewrite cpp.py to use a subclass of the ClinicError exception. As a side-effect, ClinicError is moved into Tools/clinic/libclinic/errors.py. Yak-shaving in preparation for putting cpp.py into libclinic.
Feature or enhancement
clinic.py
has a lot of globals in various forms. Getting rid of the globals will make it possible to split outclinic.py
in multiple files (#113299). Combined, this will impact readability and maintainability of Argument Clinic in a positive way.Most globals can be easily dealt with. We can structure them into two groups:
It can make sense split out some of these in separate files (for example a libclinic package, as suggested in #113309). For some globals, it makes more sense to embed them into one of the existing classes (for example the global
version
variable clearly belongs inDSLParser
).Suggesting to start with the following:
Tools/clinic/libclinic/accumulators.py
fileTools/clinic/libclinic/formatters.py
fileversion
intoDSLParser
and version helper into aTools/clinic/libclinic/version.py
fileLinked PRs
The text was updated successfully, but these errors were encountered: