Modernise code in `Tools/clinic/` #104683

AlexWaygood · 2023-05-20T10:22:31Z

Feature or enhancement

Modernise some Python anachronisms in Tools/clinic/, to make the code more readable and maintainable. Some things that can be easily done:

Use dict instead of OrderedDict (gh-104683: Argument clinic: use dict over OrderedDict #104647)

Simplify code like this by using the str.removesuffix and str.removeprefix methods, both new in Python 3.9:

cpython/Tools/clinic/clinic.py

Lines 2572 to 2575 in 06eeee9

    
           name = f.__name__ 
        
           if not name.endswith('_converter'): 
        
               return f 
        
           name = name[:-len('_converter')]

(gh-104683: Modernise clinic.py using str.removeprefix and str.removesuffix #104685)

Pyupgrade (run using the --py310-plus setting) also finds various things that can be modernised (gh-104683: Modernise Tools/clinic/ using pyupgrade #104684)
Refactor CLanguage.output_templates (see Modernise code in Tools/clinic/ #104683 (comment))
Put templating in a separate .py file, kind of like Tools/clinic/cpp.py
Rework Argument Clinic error handling #107468
Restructure Argument Clinic CLI #107467

Cc. @erlend-aasland

Linked PRs

The text was updated successfully, but these errors were encountered:

For code readability. Instances of `builtins.dict` have been ordered since 3.6, and have been guaranteed by the language to be ordered since Python 3.7. Argument Clinic now requires Python 3.10+.

…movesuffix` (#104685) Both methods were new in Python 3.9.

erlend-aasland · 2023-05-20T20:13:28Z

⚠️ Refactoring is a useful tool, but it is also risky business. We must make sure we've got good test coverage for all touched code. If we're touching uncovered branches, we must add new tests in a separate PR first ⚠️

- Make some string interpolations more readable using f-strings or explicit parametrisation - Remove unneeded open() mode specifiers Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

…thod (#104729)

…er` method (python#104729)

…ching (#104696)

…ter` method (#104729) (#104730)

erlend-aasland · 2023-07-03T09:48:37Z

The parameter_state state machine could be made slightly more readable by using enums, for example:

cpython/Tools/clinic/clinic.py

Lines 4711 to 4726 in 35963da

    
           # These rules are enforced with a single state variable: 
        
           # "parameter_state".  (Previously the code was a miasma of ifs and 
        
           # separate boolean state variables.)  The states are: 
        
           # 
        
           #  [ [ a, b, ] c, ] d, e, f=3, [ g, h, [ i ] ]   <- line 
        
           # 01   2          3       4    5           6     <- state transitions 
        
           # 
        
           # 0: ps_start.  before we've seen anything.  legal transitions are to 1 or 3. 
        
           # 1: ps_left_square_before.  left square brackets before required parameters. 
        
           # 2: ps_group_before.  in a group, before required parameters. 
        
           # 3: ps_required.  required parameters, positional-or-keyword or positional-only 
        
           #     (we don't know yet).  (renumber left groups!) 
        
           # 4: ps_optional.  positional-or-keyword or positional-only parameters that 
        
           #    now must have default values. 
        
           # 5: ps_group_after.  in a group, after required parameters. 
        
           # 6: ps_right_square_after.  right square brackets after required parameters.

Use enums and pattern matching to make the code more readable. Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

…6443)

pythonGH-106443) (cherry picked from commit a941bd6) Co-authored-by: Erlend E. Aasland <erlend@python.org>

….c (GH-106443) (#106444) gh-104683: Rename Lib/test/clinic.test as Lib/test/clinic.test.c (GH-106443) (cherry picked from commit a941bd6) Co-authored-by: Erlend E. Aasland <erlend@python.org>

….c (GH-106443) (#106445) gh-104683: Rename Lib/test/clinic.test as Lib/test/clinic.test.c (GH-106443) (cherry picked from commit a941bd6) Co-authored-by: Erlend E. Aasland <erlend@python.org>

* main: (39 commits) pythongh-102542 Remove unused bytes object and bytes slicing (python#106433) Clarify state of CancelledError in doc (python#106453) pythongh-64595: Fix regression in file write logic in Argument Clinic (python#106449) pythongh-104683: Rename Lib/test/clinic.test as Lib/test/clinic.test.c (python#106443) tp_flags docs: fix indentation (python#106420) pythongh-104050: Partially annotate Argument Clinic CLanguage class (python#106437) pythongh-106368: Add tests for formatting helpers in Argument Clinic (python#106415) pythongh-104050: Annotate Argument Clinic parameter permutation helpers (python#106431) pythongh-104050: Annotate toplevel functions in clinic.py (python#106435) pythongh-106320: Fix specialize.c compilation by including pycore_pylifecycle.h (python#106434) Add some codeowners for `Tools/clinic/` (python#106430) pythongh-106217: Truncate the issue body size of `new-bugs-announce-notifier` (python#106423) pythongh-61215: Rename `wait_until_any_call` to `wait_until_any_call_with` (python#106414) pythongh-106162: array: suppress warning in test_array (python#106404) pythongh-106320: Remove _PyInterpreterState_HasFeature() (python#106425) pythonGH-106360: Support very basic superblock introspection (python#106422) pythongh-106406: Fix _Py_IsInterpreterFinalizing() in _winapi.c (python#106408) pythongh-106396: Special-case empty format spec to gen empty JoinedStr node (python#106401) pythongh-106368: Add tests for permutation helpers in Argument Clinic (python#106407) pythonGH-106008: Fix refleak when peepholing `None` comparisons (python#106367) ...

…ssible Also make it a property.

…#107638) Also make it a cached property. Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

…__repr__` functions (#107667)

Explicitly exclude Lib/test/clinic.test.c when running make clinic.

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

Extract helper methods for formatting the signature and parameter sections, and clean up the remaining function body. Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

…`Tools/clinic` (#107771)

…107790) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

Reduce duplicate code in state_modulename_name()

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

…e_and_class() The hasattr(parent, "classes") check is unneeded, since 'parent' is an instance of either the Module, Class, or Clinic classes, and all of them has a "classes" attribute.

…class() (#108092) 'not hasattr(parent, "classes")' is always false, since 'parent' is an instance of either the Module, Class, or Clinic classes, and all of them has a "classes" attribute.

…108552)

erlend-aasland · 2023-08-30T07:47:13Z

Argument Clinic is now slightly more readable, thanks to the applied refactors. I suggest we continue to improve and modernise Argument Clinic, but now through more targeted issues; this issue has served its purpose. Thanks to everyone involved.

…ython/cpython#107770) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

AlexWaygood added type-feature A feature request or enhancement topic-argument-clinic labels May 20, 2023

bedevere-bot mentioned this issue May 20, 2023

gh-104683: Argument clinic: use dict over OrderedDict #104647

Merged

This was referenced May 20, 2023

gh-104683: Modernise Tools/clinic/ using pyupgrade #104684

Merged

gh-104683: Modernise clinic.py using str.removeprefix and str.removesuffix #104685

Merged

AlexWaygood added a commit that referenced this issue May 20, 2023

gh-104683: Modernise clinic.py using str.removeprefix and `str.re…

663c049

…movesuffix` (#104685) Both methods were new in Python 3.9.

bedevere-bot mentioned this issue May 20, 2023

gh-104683: clinic.py: Modernise parse_converter() using pattern-matching #104696

Merged

bedevere-bot mentioned this issue May 21, 2023

gh-104683: clinic.py: Improve coverage for the parse_converter method #104729

Merged

AlexWaygood added a commit that referenced this issue May 21, 2023

gh-104683: clinic.py: Improve coverage for the parse_converter me…

64d1b44

…thod (#104729)

bedevere-bot mentioned this issue May 21, 2023

[3.11] gh-104683: clinic.py: Improve coverage for the parse_converter method (#104729) #104730

Merged

AlexWaygood added a commit to AlexWaygood/cpython that referenced this issue May 21, 2023

pythongh-104683: clinic.py: Improve coverage for the `parse_convert…

b59fb65

…er` method (python#104729)

AlexWaygood added a commit that referenced this issue May 21, 2023

gh-104683: clinic.py: Modernise parse_converter() using pattern-mat…

4b107d8

…ching (#104696)

AlexWaygood added a commit that referenced this issue May 21, 2023

[3.11] gh-104683: clinic.py: Improve coverage for the `parse_conver…

d691de1

…ter` method (#104729) (#104730)

bedevere-bot mentioned this issue Jul 3, 2023

gh-104683: Modernise Argument Clinic parameter state machine #106362

Merged

erlend-aasland added a commit that referenced this issue Jul 3, 2023

gh-104683: Modernise Argument Clinic parameter state machine (#106362)

71b4044

Use enums and pattern matching to make the code more readable. Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

erlend-aasland mentioned this issue Jul 4, 2023

gh-104050: Annotate toplevel functions in clinic.py #106435

Merged

bedevere-bot mentioned this issue Jul 5, 2023

gh-104683: Rename clinic.test => clinic.test.c #106443

Merged

erlend-aasland added a commit to erlend-aasland/cpython that referenced this issue Jul 5, 2023

pythongh-104683: Rename clinic.test => clinic.test.c

c6cedd0

erlend-aasland added a commit that referenced this issue Jul 5, 2023

gh-104683: Rename Lib/test/clinic.test as Lib/test/clinic.test.c (#10…

a941bd6

…6443)

bedevere-bot mentioned this issue Jul 5, 2023

[3.12] gh-104683: Rename Lib/test/clinic.test as Lib/test/clinic.test.c (GH-106443) #106444

Merged

miss-islington pushed a commit to miss-islington/cpython that referenced this issue Jul 5, 2023

pythongh-104683: Rename Lib/test/clinic.test as Lib/test/clinic.test.c (

e83dc5b

pythonGH-106443) (cherry picked from commit a941bd6) Co-authored-by: Erlend E. Aasland <erlend@python.org>

miss-islington pushed a commit to miss-islington/cpython that referenced this issue Jul 5, 2023

pythongh-104683: Rename Lib/test/clinic.test as Lib/test/clinic.test.c (

aa3a921

pythonGH-106443) (cherry picked from commit a941bd6) Co-authored-by: Erlend E. Aasland <erlend@python.org>

bedevere-bot mentioned this issue Jul 5, 2023

[3.11] gh-104683: Rename Lib/test/clinic.test as Lib/test/clinic.test.c (GH-106443) #106445

Merged

bedevere-bot mentioned this issue Aug 4, 2023

gh-104683: Argument Clinic: Use CConverter.length_name where possible #107638

Merged

erlend-aasland added a commit to erlend-aasland/cpython that referenced this issue Aug 4, 2023

pythongh-104683: Argument Clinic: Use CConverter.length_name where po…

ce1066e

…ssible Also make it a property.

erlend-aasland added a commit that referenced this issue Aug 4, 2023

gh-104683: Argument Clinic: Use CConverter.length_name where possible (…

321f0f7

…#107638) Also make it a cached property. Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

bedevere-bot mentioned this issue Aug 5, 2023

gh-104683: Improve consistency and test coverage of argument-clinic __repr__ functions #107667

Merged

AlexWaygood added a commit that referenced this issue Aug 5, 2023

gh-104683: Improve consistency and test coverage of argument-clinic `…

6996b40

…__repr__` functions (#107667)

erlend-aasland added a commit to erlend-aasland/cpython that referenced this issue Aug 8, 2023

pythongh-104683: Add --exclude option to Argument Clinic CLI

bb701b7

Explicitly exclude Lib/test/clinic.test.c when running make clinic.

This was referenced Aug 8, 2023

gh-104683: Add --exclude option to Argument Clinic CLI #107770

Merged

gh-104683: Remove unused variables from Tools/clinic and tests for Tools/clinic #107771

Merged

erlend-aasland added a commit that referenced this issue Aug 8, 2023

gh-104683: Add --exclude option to Argument Clinic CLI (#107770)

0be3743

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

bedevere-bot mentioned this issue Aug 8, 2023

gh-104683: Argument Clinic: Params now render their own docstrings #107790

Merged

erlend-aasland added a commit to erlend-aasland/cpython that referenced this issue Aug 8, 2023

pythongh-104683: Argument Clinic: Params now render their own docstrings

b36eda9

AlexWaygood added a commit that referenced this issue Aug 9, 2023

gh-104683: Remove unused variables from Tools/clinic and tests for …

65ce365

…`Tools/clinic` (#107771)

erlend-aasland added a commit that referenced this issue Aug 9, 2023

gh-104683: Argument Clinic: Params now render their own docstrings (#…

1b3f5f2

…107790) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

This was referenced Aug 10, 2023

gh-104683: Argument clinic: make format_docstring() a method on Function objects #107840

Closed

gh-104683: Argument Clinic: Extract parse_function_names() helper #107964

Merged

erlend-aasland added a commit to erlend-aasland/cpython that referenced this issue Aug 15, 2023

pythongh-104683: Argument Clinic: Extract parse_names() helper

2f53112

Reduce duplicate code in state_modulename_name()

erlend-aasland added a commit that referenced this issue Aug 16, 2023

gh-104683: Argument Clinic: Extract parse function name helper (#107964)

42429d3

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

bedevere-bot mentioned this issue Aug 17, 2023

gh-104683: Argument Clinic: Remove unreachable code from _module_and_class() #108092

Merged

erlend-aasland added a commit to erlend-aasland/cpython that referenced this issue Aug 27, 2023

pythongh-104683: Argument Clinic: Refactor the module and class resolver

74a7029

bedevere-bot mentioned this issue Aug 27, 2023

gh-104683: Argument Clinic: Refactor the module and class resolver #108552

Merged

erlend-aasland added a commit that referenced this issue Aug 28, 2023

gh-104683: Argument Clinic: Refactor the module and class resolver (#…

d909733

…108552)

erlend-aasland closed this as completed Aug 30, 2023

AA-Turner pushed a commit to AA-Turner/devguide that referenced this issue Sep 13, 2023

python/cpython#104683: Add --exclude option to Argument Clinic CLI (p…

8dd6936

…ython/cpython#107770) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

erlend-aasland added a commit to python/devguide that referenced this issue Sep 26, 2023

python/cpython#104683: Add --exclude option to Argument Clinic CLI (p…

2d0204d

…ython/cpython#107770) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

erlend-aasland mentioned this issue Oct 12, 2023

Rework Argument Clinic error handling #107468

Closed

2 tasks

erlend-aasland mentioned this issue Dec 20, 2023

Refactor Argument Clinic support code into libclinic #113299

Closed

Apr	MAY	Jun
	03
2023	2024	2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Modernise code in `Tools/clinic/` #104683

Modernise code in `Tools/clinic/` #104683

AlexWaygood commented May 20, 2023 •

edited by bedevere-bot

erlend-aasland commented May 20, 2023 •

edited

erlend-aasland commented Jul 3, 2023

erlend-aasland commented Aug 30, 2023

Modernise code in Tools/clinic/ #104683

Modernise code in Tools/clinic/ #104683

Comments

AlexWaygood commented May 20, 2023 • edited by bedevere-bot

Feature or enhancement

Linked PRs

erlend-aasland commented May 20, 2023 • edited

erlend-aasland commented Jul 3, 2023

erlend-aasland commented Aug 30, 2023

Modernise code in `Tools/clinic/` #104683

Modernise code in `Tools/clinic/` #104683

AlexWaygood commented May 20, 2023 •

edited by bedevere-bot

erlend-aasland commented May 20, 2023 •

edited