Modernise code in Tools/clinic/

@erlend-aasland

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

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

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

⚠️ 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 ⚠️

gh-104683: Modernise Tools/clinic/ (#104684)

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

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

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

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

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.

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

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

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

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

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

gh-104683: Argument Clinic: refactor format_docstring() (#107623)

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

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

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

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

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

pythongh-104683: Argument Clinic: Remove unreachable code from _modul…

gh-104683: Argument Clinic: Remove unreachable code from _module_and_…

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

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

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.

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

Navigation Menu

Repository navigation

Modernise code in `Tools/clinic/` #104683

Feature or enhancement

Linked PRs

33 remaining items

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

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

	# 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.

Modernise code in Tools/clinic/ #104683

Description

Feature or enhancement

Linked PRs

Activity

erlend-aasland commented on May 20, 2023

erlend-aasland commented on Jul 3, 2023

33 remaining items

erlend-aasland commented on Aug 30, 2023

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

Modernise code in `Tools/clinic/` #104683