| 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() |