Collaboration

In order to make it easier for different people to use your RAIMAD designs, you can organize them into a package. RAIMAD packages are nothing more the standard Python packages. That means you can install them with tools like pip.

Using a RAIMAD package

If you would just like to make use of a RAIMAD package within your designs, you can install it using pip. For example, if you wanted to install the sample rai_smiley package, you could do it like so

pip install git+https://github.com/tifuun/rai_smiley

Working on other people's repos

If you want to not only use a package, but also change its code (for example, if you want to contribute new components to an existing package), you should first clone the repository using git, and then install it using pip editable mode, like so:

git clone https://github.com/tifuun/rai_smiley
pip install -e ./rai_smiley

Installing a package in editable mode means that any changes that you make in your local copy of the package will be reflected from within Python when you import it.

The screencast below demonstrates these steps by making a simple change in the sample rai_smiley package.

Adding new components to an existing package

Python is very permissive in regards to where you put your code within a package. Indeed, some ^{1, 2, 3} prolific packages put all or almost all of their code within one file.

In RAIMAD, however, to keep things manageable, we follow the following rule of thumb:

• Any classes (e.g. components) that are useful on their own deserve their own separate file.
• Any supporting functions and classes (e.g. subcomponents) should share the file with the class that they support.

We also use src layout for RAIMAD packages, which means that Python source code files go into src/package_name/.

With regards to naming classes and files, we also adhere to PEP8. In short, files should be in snake_case, while classes should be in UpperCamelCase.

So, if a package called rai_filters contains a component called IShapedFilter, you should expect to find its source code under src/rai_filters/i_shaped_filter.py, which might also contain supporting classes/components like IShapedFilterCoupler.

Finally, we use the __init__.py files (which are required to be present in every package directory by Python) to perform namespace flattening. Continuing with the rai_filters example above, src/rai_filters/__init__.py might include lines like from rai_filters.i_shaped_filder import IShapedFilter so that users of the package can access the component as rai_filters.IShapedFilter, as opposed to the needlessly verbose rai_filters.i_shaped_filter.IShapedFilter.

The screencast below demonstrates how you can add a sample IShapedFilter component to the rai_smiley package and update the __init__.py file to include the newly added component.

A note on raimad export syntax

In Python, you use the . operator to access child modules of a module as well as objects within a module. The raimad export command, however, uses the . to access child modules, and the : to access a component class within a module.

In other words, the last separator is always a ':' and not a '.'.

So, while you may access the IShapedFilter class as rai_smiley.i_shaped_filter.IShapedFilter or rai_smiley.IShapedFilter from Python, when using the raimad export command you would write rai_smiley.i_shaped_filter:IShapedFilter or rai_smiley:IShapedFilter.

Making your own package

You can also make your own package from scratch. Make sure to choose a short and informative name that complies with PEP8, and starts with rai_.

After that, by using the sample rai_smiley as a reference, set up the file structure of your package and upload it to a git repository.