3. References

damona.common	Image and Binary handlers.
damona.config	The Damona configuration

3.1. admin module

3.2. builders module

3.3. common module

Image and Binary handlers. Provide also a Damona manager

class BinaryReader(filename)

Manage a single binary

>>> from damona.common import BinaryReader
>>> br = BinaryReader("~/.config/damona/envs/base/bin/fastqc")
>>> br.get_image()
'fastqc:0.11.9'
>>> br.is_image_available()
True

constructor

Parameters:

filename (str) -- the input name of the binary file

Can be use to check whether the binary is not orphan and its image is still available.

get_image()

Return the container used by the binary

is_image_available()

Return True if the image used by the binary does exist

class Damona

Global manager to get information about environments, binaries, images.

property config_path

Get the Damona config file location

damona_path

This attribute stored the path where images and environments are stored

property environments_path

Get the Damona environments directory location

find_orphan_binaries()

Find binaries in all environments that are orphans

By orphans, we mean that their image is not present anymore for some reasons (e.g., users delete it manually).

find_orphan_images()

Get images that have no binaries in any environments

get_all_binaries()

Return list of all binaries in all environments

get_all_images()

Return list of all images

get_environments()

return the list of environments names

property images_directory

Get the Damona images directory location

is_image_used(name)

Return True if this image is used

The image name has no ".img" extension and uses _ instead of : character

# get images used
from damona import Damona
d = Damona()
d.get_all_images()

# Note that names are encoded as NAME_X.Y.Z

d.is_image_used("fastqc_0.11.9")

class DamonaInit

Class to create images/bin directory for DAMONA

This is called each time damona is started to make sure the required config file are present.

This class simply create the ~/.config/damona/envs and images directories. It also checks whether DAMONA_PATH and DAMONA_SINGULARITY_OPTIONS variables are defined in the environment.

SHELL_CONFIGS = {'bash': {'manual_cmd': 'echo "source ~/.config/damona/damona.sh" >> ~/.bashrc', 'rc_file': '~/.bashrc', 'source_line': 'source ~/.config/damona/damona.sh'}, 'fish': {'manual_cmd': 'echo "source ~/.config/damona/damona.fish" >> ~/.config/fish/config.fish', 'rc_file': '~/.config/fish/config.fish', 'source_line': 'source ~/.config/damona/damona.fish'}, 'zsh': {'manual_cmd': 'echo "source ~/.config/damona/damona.zsh" >> ~/.zshrc', 'rc_file': '~/.zshrc', 'source_line': 'source ~/.config/damona/damona.zsh'}}

class ImageReader(name)

Manage a single Singularity image

Constructor

Parameters:

name -- the input name of the image (fullpath)

>>> from damona.common import ImageReader
>>> ir = ImageReader("~/.config/damona/images/fastqc_0.11.9.img")
>>> ir.md5
>>> ir.is_orphan()
>>> ir.name
>>> print(ir.shortname)
'fastqc_0.11.9.img'
>>> print(ir.version)
'0.11.9'

delete()

Delete the image file from disk if it is no longer used by any environment.

If the image is still referenced by at least one binary alias the deletion is skipped and a warning is logged instead.

property guessed_executable

Guess the executable from the filename

is_installed()

Return True is the file exists in the DAMONA_PATH

is_orphan()

Return True if no environment binary currently points to this image.

An image is considered an orphan when it exists in the images directory but no binary alias in any environment references it.

Returns:

True when no binary uses this image, False otherwise.

Return type:

bool

is_valid_name()

Check whether the name is valid.

Must be in the form NAME_X.Y.Z.img

property md5

compute and return the md5 of the file

property shortname

Get the filename (NAME_X.Y.Z.img)

property version

Get the version

get_container_cmd()

Return the available container command (singularity or apptainer).

singularity is preferred for backward compatibility. When only apptainer is present on the system that command is returned instead.

Returns:

"singularity" or "apptainer", or None when neither is found.

Return type:

str or None

3.4. config module

The Damona configuration

class Config(name='damona', urls={'damona': 'https://biomics.pasteur.fr/salsa/damona/registry.txt'})

A place holder to store our configuration file and shell scripts

This class is called each time damona is started. The config file, if not present is created, otherwise nothing happens. Same for the bash and fish shell configuration files

The damona configuration file looks like:

[general]
quiet=False

[zenodo]
token=APmm6p....
orcid=0000-0001
name='Cokelaer, Thomas'
affiliation='Institut Pasteur'

[sandbox.zenodo]
token=FFmbAEhQbb...
orcid=0000-0001
name='Cokelaer, Thomas'
affiliation='Institut Pasteur'

Where the urls section can be used to store aliases to external registry. When installing software using:

damona install example --url damona

if the alias damona is in the [urls] section, it is replaced by its real value (https://...) the URL must end with the expected registry name registry.txt

The zenodo section is not save by default since it is for developpers only.

Constructor

Creates ~/.config/damona/damona.cfg and the shell initialisation scripts the first time it is called; subsequent calls are no-ops for files that already exist and are up-to-date.

Parameters:

• name (str) -- Config name used as the sub-directory under the OS config dir (default "damona"). Override in tests to avoid touching the user's real config.

• urls (dict) -- Mapping of alias → URL to pre-populate the [urls] section of a freshly created config file.

add_bash()

Copy the Bash shell init script to the user config directory.

Returns:

True if the file was created or updated, False otherwise.

Return type:

bool

add_fish()

Copy the Fish shell init script to the user config directory.

Returns:

True if the file was created or updated, False otherwise.

Return type:

bool

add_zsh()

Copy the Zsh shell init script to the user config directory.

Returns:

True if the file was created or updated, False otherwise.

Return type:

bool

read()

Reads the config file

get_damona_commands()

Print commands available in Damona if not hidden.

This function is used for the fish completion

3.5. environ module

3.6. install module

3.7. registry module

3.8. zenodo module

3.9. DAMONA standalone (script module)