Coverage for apio/commands/apio.py: 100%

1"""Apio top level click command.""" 

2 

3# -*- coding: utf-8 -*- 

4# -- This file is part of the Apio project 

5# -- (C) 2016-2019 FPGAwars 

6# -- Author Jesús Arroyo 

7# -- License GPLv2 

8 

9 

10import click 

11from click.exceptions import NoArgsIsHelpError 

12from apio.utils.cmd_util import ApioSubgroup, ApioGroup 

13from apio.utils import util 

14 

15# -- Import sub commands. 

16from apio.commands import ( 

17 apio_api, 

18 apio_boards, 

19 apio_build, 

20 apio_clean, 

21 apio_create, 

22 apio_devices, 

23 apio_drivers, 

24 apio_examples, 

25 apio_format, 

26 apio_fpgas, 

27 apio_graph, 

28 apio_info, 

29 apio_lint, 

30 apio_packages, 

31 apio_preferences, 

32 apio_raw, 

33 apio_report, 

34 apio_sim, 

35 apio_test, 

36 apio_upgrade, 

37 apio_upload, 

38) 

39 

40 

41# -- The subcommands of this command, grouped by category. 

42SUBGROUPS = [ 

43 ApioSubgroup( 

44 "Build commands", 

45 [ 

46 apio_build.cli, 

47 apio_upload.cli, 

48 apio_clean.cli, 

49 ], 

50 ), 

51 ApioSubgroup( 

52 "Verification commands", 

53 [ 

54 apio_lint.cli, 

55 apio_format.cli, 

56 apio_sim.cli, 

57 apio_test.cli, 

58 apio_report.cli, 

59 apio_graph.cli, 

60 ], 

61 ), 

62 ApioSubgroup( 

63 "Setup commands", 

64 [ 

65 apio_create.cli, 

66 apio_preferences.cli, 

67 apio_packages.cli, 

68 apio_drivers.cli, 

69 apio_devices.cli, 

70 ], 

71 ), 

72 ApioSubgroup( 

73 "Utility commands", 

74 [ 

75 apio_boards.cli, 

76 apio_fpgas.cli, 

77 apio_examples.cli, 

78 apio_info.cli, 

79 apio_raw.cli, 

80 apio_api.cli, 

81 apio_upgrade.cli, 

82 ], 

83 ), 

84] 

85 

86 

87def context_settings(): 

88 """Return a common Click command settings that adds 

89 the alias -h to --help. This applies also to all the sub 

90 commands such as apio build. 

91 """ 

92 

93 # -- This causes no args help commands such as 'apio' to return 

94 # -- error code 0 instead of 2. 

95 # -- Per https://tinyurl.com/click-help-no-args-error 

96 NoArgsIsHelpError.exit_code = 0 

97 

98 # Per https://click.palletsprojects.com/en/8.1.x/documentation/ 

99 # #help-parameter-customization 

100 return {"help_option_names": ["-h", "--help"]} 

101 

102 

103# --------------------------- 

104# -- Top click command node. 

105# --------------------------- 

106 

107# -- Text in the rich-text format of the python rich library. 

108APIO_HELP = """ 

109[b]WORK WITH FPGAs WITH EASE.[/b] 

110 

111Apio is an easy to use and open-source command-line suite designed to \ 

112streamline FPGA programming. It supports a wide range of tasks, including \ 

113linting, building, simulation, unit testing, and programming FPGA boards. 

114 

115An Apio project consists of a directory containing a configuration file \ 

116named 'apio.ini', along with FPGA source files, testbenches, and pin \ 

117definition files. 

118 

119Apio commands are intuitive and perform their intended functionalities right \ 

120out of the box. For example, the command apio upload automatically compiles \ 

121the design in the current directory and uploads it to the FPGA board. 

122 

123For detailed information about any Apio command, append the -h flag to view \ 

124its help text. For example: 

125 

126[code]apio build -h 

127apio drivers ftdi install -h[/code] 

128 

129To check the apio version type: 

130[code] 

131apio --version[/code] 

132 

133For more information about the Apio project, visit the official Apio Wiki \ 

134https://github.com/FPGAwars/apio/wiki/Apio 

135""" 

136 

137 

138@click.group( 

139 name="apio", 

140 cls=ApioGroup, 

141 subgroups=SUBGROUPS, 

142 help=APIO_HELP, 

143 short_help="Work with FPGAs with ease", 

144 context_settings=context_settings(), 

145) 

146# NOTE: Without this explicit version value, click has difficulty 

147# determining the version when running under pyinstaller. 

148@click.version_option(util.get_apio_version(), "-v", "--version") 

149def apio_top_cli(): 

150 """The top level command group of apio commands""" 

151 

152 # pass