Stage Docstring
The final part to developing a clean stage is writing the docstring. The docstring is used in the clean stage browser to let users know what the stage does, what arguments are available, and what the arguments default to. It also provides an example of using the stage in the clean YAML file.
The docstring should adhere to this general format:
"""<description>
Stage Schema
------------
<schema>
Example
-------
<example>
"""
This a complete example of a docstring for the stage we wrote in the previous sections. Be mindful of the indentation as multiline strings will contain leading whitespace if they exist which will then be rendered in the stage browser (which we dont want). Please use the same formatting for the schema.
1from genie.metaparser.util.schemaengine import Optional
2from genie.libs.clean import BaseStage
3
4class ChangeBootVariable(BaseStage):
5 """This stage configures boot variables of the device using the following steps:
6
7 - Delete existing boot variables.
8 - Configure boot variables using the provided 'images'.
9 - Set the configuration-register using the provided 'config_register'.
10 - Write memory.
11 - Verify the boot variables are as expected.
12 - Verify the configuration-register is as expected.
13
14Stage Schema
15------------
16change_boot_variable:
17
18 images (list): Image files to use when configuring the boot variables.
19
20 timeout (int, optional): Execute timeout in seconds. Defaults to 300.
21
22 config_register (str, optional): Value to set config-register for
23 reload. Defaults to 0x2102.
24
25 current_running_image (bool, optional): Set the boot variable to the currently
26 running image from the show version command instead of the image provided.
27 Defaults to False.
28
29Example
30-------
31change_boot_variable:
32 images:
33 - harddisk:/image.bin
34 timeout: 150
35"""
36
37 # ============
38 # Stage Schema
39 # ============
40 schema = {
41 Optional('images'): list,
42 Optional('timeout'): int,
43 Optional('config_register'): str,
44 Optional('current_running_image'): bool,
45 }
46
47 # =================
48 # Argument Defaults
49 # =================
50 TIMEOUT = 300
51 CONFIG_REGISTER = '0x2102'
52 CURRENT_RUNNING_IMAGE = False
53
54 # ==============================
55 # Execution order of Stage steps
56 # ==============================
57 exec_order = [
58 'delete_boot_variable',
59 'configure_boot_variable',
60 'set_configuration_register',
61 'write_memory',
62 'verify_boot_variable',
63 'verify_configuration_register'
64 ]
65
66 def delete_boot_variable(self, steps, device):
67
68 with steps.start("Delete any configure boot variables") as step:
69
70 try:
71 device.configure("no boot system")
72 except Exception as e:
73 step.failed("Failed to delete configured boot variables",
74 from_exception=e)
75
76 step.passed("Successfully deleted configured boot variables")
77
78 def configure_boot_variable(self, steps, device, images, timeout=TIMEOUT,
79 current_running_image=CURRENT_RUNNING_IMAGE):
80
81 with steps.start("Set boot variable to images provided for {}".format(
82 device.name)) as step:
83
84 if current_running_image:
85 log.info("Retrieving and using the running image due to "
86 "'current_running_image: True'")
87
88 try:
89 output = device.parse('show version')
90 images = [output['version']['system_image']]
91 except Exception as e:
92 step.failed("Failed to retrieve the running image. Cannot "
93 "set boot variables",
94 from_exception=e)
95
96 try:
97 device.api.execute_set_boot_variable(
98 boot_images=images, timeout=timeout)
99 except Exception as e:
100 step.failed("Failed to set boot variables to images provided",
101 from_exception=e)
102 else:
103 step.passed("Successfully set boot variables to images provided")
104
105 def set_configuration_register(self, steps, device,
106 config_register=CONFIG_REGISTER, timeout=TIMEOUT):
107 with steps.start("Set config register to boot new image on {}".format(
108 device.name)) as step:
109
110 try:
111 device.api.execute_set_config_register(
112 config_register=config_register, timeout=timeout)
113 except Exception as e:
114 step.failed("Failed to set config-register",
115 from_exception=e)
116 else:
117 step.passed("Successfully set config register")
118
119 def write_memory(self, steps, device, timeout=TIMEOUT):
120 with steps.start("Execute 'write memory' on {}".format(device.name)) as step:
121 try:
122 device.api.execute_write_memory(timeout=timeout)
123 except Exception as e:
124 step.failed("Failed to execute 'write memory'",
125 from_exception=e)
126 else:
127 step.passed("Successfully executed 'write memory'")
128
129 def verify_boot_variable(self, steps, device, images):
130 with steps.start("Verify next reload boot variables are correctly set "
131 "on {}".format(device.name)) as step:
132
133 if not device.api.verify_boot_variable(boot_images=images):
134 step.failed("Boot variables are NOT correctly set")
135 else:
136 step.passed("Boot variables are correctly set")
137
138 def verify_configuration_register(self, steps, device,
139 config_register=CONFIG_REGISTER):
140 with steps.start("Verify config-register is as expected on {}".format(
141 device.name)) as step:
142
143 if not device.api.verify_config_register(
144 config_register=config_register, next_reload=True):
145 step.failed("Config-register is not as expected")
146 else:
147 step.passed("Config-register is as expected")