Best Practices

Best Practices for Pyrogue Python Code

This is an attempt to capture best practice for coding style and organization when creating a pyrogue Device Tree.

File naming

If a .py file only has one Device class, name it with an underscore. Example:

_DeviceClassName.py

It is preferred to organize all Device classes this way, to make them easier to find.

Mapping to Firmware Modules

Try to write Device classes that map directly to firmware modules. This makes it easier to determine the relationship between the two. The Device class and firmware module should share the same name.

There may be cases when it makes sense to deviate from this rule. When this happens, be sure to document in the Python code which firmware modules are being mapped.

Imports

import * is Bad

Never do:

from somelibrary import *

Use import as sparingly

It usually makes it clearer to eschew import as and simply use the full package.module name in the code. Only use import as if it really saves verbosity, such as a long package path that is called multiple times in the code.

In the example below, the import as doesn't really buy much, especially if only one class from surf.axi is ever instantiated. It only creates a level of redirection for someone unfamiliar with the code would have to trace down.

Not useful

import surf.axi as axi
...
self.add(axi.AxiVersion(...))

Better

import surf.axi
...
self.add(surf.axi.AxiVersion(...))

OK to use in some cases

import some.very.long.package.path as svlpp
...
self.add(svlpp.Device1())
self.add(svlpp.Device2())
self.add(svlpp.Device3())
self.add(svlpp.Device4())