Debian Codegraph @

scripts/generate_git_example.py

raw
1 import random
2 from pathlib import Path
3
4 random.seed(12345)
5
6 EXAMPLE_FILE_PATH = Path(__file__).parent.parent / 'examples/git_sections.py'
7 MAX_SECTION_COUNT = 3
8 MAX_COMMANDS_PER_SECTION = 3
9
10 GIT_HELP = """
11 start a working area (see also: git help tutorial)
12 clone Clone a repository into a new directory
13 init Create an empty Git repository or reinitialize an existing one
14
15 work on the current change (see also: git help everyday)
16 add Add file contents to the index
17 mv Move or rename a file, a directory, or a symlink
18 restore Restore working tree files
19 rm Remove files from the working tree and from the index
20 sparse-checkout Initialize and modify the sparse-checkout
21
22 examine the history and state (see also: git help revisions)
23 bisect Use binary search to find the commit that introduced a bug
24 diff Show changes between commits, commit and working tree, etc
25 grep Print lines matching a pattern
26 log Show commit logs
27 show Show various types of objects
28 status Show the working tree status
29
30 grow, mark and tweak your common history
31 branch List, create, or delete branches
32 commit Record changes to the repository
33 merge Join two or more development histories together
34 rebase Reapply commits on top of another base tip
35 reset Reset current HEAD to the specified state
36 switch Switch branches
37 tag Create, list, delete or verify a tag object signed with GPG
38 """.strip()
39
40 CODE_TEMPLATE = """
41 \"\"\"
42 This example shows how to use ``cloup.Section`` to organize the subcommands of
43 a multi-command in many ``--help`` sections.
44
45 The code was generated by parsing "git --help" and taking
46 - the first {max_section_count} sections
47 - for each section, the first {max_commands_per_section} commands after shuffling them.
48 \"\"\"
49 import cloup
50
51
52 def f(**kwargs):
53 \"\"\" Dummy command callback \"\"\"
54 print(**kwargs)
55
56
57 # In a real big application, you would import the following commands from separate modules =========
58 {command_list}
59 # ==================================================================================================
60
61 \"\"\"
62 If "align_sections=True" (default), the help column of all sections will
63 be aligned; otherwise, each section will be formatted independently.
64 \"\"\"
65 @cloup.group('git', align_sections=True)
66 def git():
67 return 0
68
69 \"\"\"
70 git.section() creates a new Section object, adds it to git and returns it.
71
72 In the help, sections are shown in the same order they are added.
73 Commands in each sections are shown in the same order they are listed, unless
74 you pass the argument "sorted_=True".
75 \"\"\"
76 {section_list}
77
78 \"\"\"
79 In alternative, you can either:
80 - pass a list of Section objects as argument "sections" to cloup.Group or @cloup.group
81 - use git.add_section(section) to add an existing Section object
82 - use git.add_command(cmd, name, section, ...); the section must NOT contain the command
83 - use @git.command(cmd, name, section, ...)
84
85 Individual commands don't store the section they belong to.
86 Also, cloup.command doesn't accept a "section" argument.
87 \"\"\"
88
89 # The following commands will be added to the "default section" (a sorted Section)
90 git.add_command(cloup.command('fake-2', help='Fake command #2')(f))
91 git.add_command(cloup.command('fake-1', help='Fake command #1')(f))
92
93
94 if __name__ == '__main__':
95 git()
96 """.lstrip()
97
98
99 def parse_help(help_text):
100 sections = []
101 for text in help_text.split('\n\n'):
102 title, *rows = map(str.strip, text.split('\n'))
103 title = title.strip().capitalize()
104 commands = []
105 for row in rows:
106 cmd, desc = map(str.strip, row.split(' ', 1))
107 commands.append((cmd, desc))
108 random.shuffle(commands)
109 sections.append([title, commands])
110 return sections
111
112
113 def get_command_var_name(cmd_name):
114 return 'git_' + cmd_name.replace('-', '_')
115
116
117 def generate(out_path=EXAMPLE_FILE_PATH,
118 max_section_count=MAX_SECTION_COUNT,
119 max_commands_per_section=MAX_COMMANDS_PER_SECTION):
120 sections = parse_help(GIT_HELP)[:max_section_count]
121 for s in sections:
122 s[1] = s[1][:max_commands_per_section]
123
124 # Subcommand definitions
125 commands_buffer = []
126 for _, commands in sections:
127 for cmd_name, desc in commands:
128 var_name = get_command_var_name(cmd_name)
129 commands_buffer.append(
130 f'{var_name} = cloup.command({cmd_name!r}, help={desc!r})(f)')
131 commands_buffer.append('')
132 commands_list = '\n'.join(commands_buffer).strip()
133
134 # Section list
135 sections_buffer = []
136 for title, commands in sections:
137 sections_buffer.append("git.section(")
138 sections_buffer.append(f" {title!r},")
139 for cmd_name, _ in commands:
140 var_name = get_command_var_name(cmd_name)
141 sections_buffer.append(f" {var_name},")
142 sections_buffer.append(')')
143 section_list = '\n'.join(sections_buffer)
144
145 code = CODE_TEMPLATE.format(max_section_count=max_section_count,
146 max_commands_per_section=max_commands_per_section,
147 command_list=commands_list,
148 section_list=section_list)
149
150 print(code)
151 with open(out_path, 'w', encoding='utf-8') as out_file:
152 out_file.write(code)
153
154
155 if __name__ == '__main__':
156 generate()