# cwltool.singularity

Support for executing Docker format containers using Singularity {2,3}.x or Apptainer 1.x.

## Classes

`SingularityCommandLineJob` | Commandline job using containers.

## Functions

`get_version`() | Parse the output of 'singularity --version' to determine the flavor and version.
`is_apptainer_1_or_newer`() | Check if apptainer singularity distribution is version 1.0 or higher.
`is_apptainer_1_1_or_newer`() | Check if apptainer singularity distribution is version 1.1 or higher.
`is_version_2_6`() | Check if this singularity version is exactly version 2.6.
`is_version_3_or_newer`() | Check if this version is singularity version 3 or newer or equivalent.
`is_version_3_1_or_newer`() | Check if this version is singularity version 3.1 or newer or equivalent.
`is_version_3_4_or_newer`() | Detect if Singularity v3.4+ is available.
`is_version_3_9_or_newer`() | Detect if Singularity v3.9+ is available.
`is_version_3_10_or_newer`() | Detect if Singularity v3.10+ is available.

## Module Contents

cwltool.singularity.get_version()

  Parse the output of ‘singularity –version’ to determine the flavor and version.

  Both pieces of information will be cached.

  Returns:

    A tuple containing: - A parsed Version object. - A string with the name of the singularity flavor.

  Return type:

    tuple[packaging.version.Version, str]

cwltool.singularity.is_apptainer_1_or_newer()

  Check if apptainer singularity distribution is version 1.0 or higher.

  Apptainer v1.0.0 is compatible with SingularityCE 3.9.5. See: https://github.com/apptainer/apptainer/releases

  Return type:

    bool

cwltool.singularity.is_apptainer_1_1_or_newer()

  Check if apptainer singularity distribution is version 1.1 or higher.

  Return type:

    bool

cwltool.singularity.is_version_2_6()

  Check if this singularity version is exactly version 2.6.

  Also returns False if the flavor is not singularity or singularity-ce.

  Return type:

    bool

cwltool.singularity.is_version_3_or_newer()

  Check if this version is singularity version 3 or newer or equivalent.

  Return type:

    bool

cwltool.singularity.is_version_3_1_or_newer()

  Check if this version is singularity version 3.1 or newer or equivalent.

  Return type:

    bool

cwltool.singularity.is_version_3_4_or_newer()

  Detect if Singularity v3.4+ is available.

  Return type:

    bool

cwltool.singularity.is_version_3_9_or_newer()

  Detect if Singularity v3.9+ is available.

  Return type:

    bool

cwltool.singularity.is_version_3_10_or_newer()

  Detect if Singularity v3.10+ is available.

  Return type:

    bool

class cwltool.singularity.SingularityCommandLineJob(builder, joborder, make_path_mapper, requirements, hints, name)

  Bases: `cwltool.job.ContainerCommandLineJob`

  Commandline job using containers.

  Parameters:

    - builder (cwltool.builder.Builder)

    - joborder (cwl_utils.types.CWLObjectType)

    - make_path_mapper (collections.abc.Callable[[collections.abc.MutableSequence[cwl_utils.types.CWLFileType | cwl_utils.types.CWLDirectoryType], str, cwltool.context.RuntimeContext, bool], cwltool.pathmapper.PathMapper])

    - requirements (list[cwl_utils.types.CWLObjectType])

    - hints (list[cwl_utils.types.CWLObjectType])

    - name (str)

  static get_image(dockerRequirement, pull_image, tmp_outdir_prefix, force_pull=False, sandbox_base_path=None)

    Acquire the software container image in the specified dockerRequirement.

    Uses Singularity and returns the success as a bool. Updates the provided dockerRequirement with the specific dockerImageId to the full path of the local image, if found. Likewise the dockerRequirement[‘dockerPull’] is updated to a docker:// URI if needed.

    Parameters:

      - dockerRequirement (dict[str, str])

      - pull_image (bool)

      - tmp_outdir_prefix (str)

      - force_pull (bool)

      - sandbox_base_path (str | None)

    Return type:

      bool

  get_from_requirements(r, pull_image, force_pull, tmp_outdir_prefix, image_base_path=None)

    Return the filename of the Singularity image.

    (e.g. hello-world-latest.{img,sif}).

    Parameters:

      - r (cwl_utils.types.CWLObjectType)

      - pull_image (bool)

      - force_pull (bool)

      - tmp_outdir_prefix (str)

      - image_base_path (str | None)

    Return type:

      str | None

  static append_volume(runtime, source, target, writable=False)

    Add binding arguments to the runtime list.

    Parameters:

      - runtime (list[str])

      - source (str)

      - target (str)

      - writable (bool)

    Return type:

      None

  add_file_or_directory_volume(runtime, volume, host_outdir_tgt)

    Append volume a file/dir mapping to the runtime option list.

    Parameters:

      - runtime (list[str])

      - volume (cwltool.pathmapper.MapperEnt)

      - host_outdir_tgt (str | None)

    Return type:

      None

  add_writable_file_volume(runtime, volume, host_outdir_tgt, tmpdir_prefix)

    Append a writable file mapping to the runtime option list.

    Parameters:

      - runtime (list[str])

      - volume (cwltool.pathmapper.MapperEnt)

      - host_outdir_tgt (str | None)

      - tmpdir_prefix (str)

    Return type:

      None

  add_writable_directory_volume(runtime, volume, host_outdir_tgt, tmpdir_prefix)

    Append a writable directory mapping to the runtime option list.

    Parameters:

      - runtime (list[str])

      - volume (cwltool.pathmapper.MapperEnt)

      - host_outdir_tgt (str | None)

      - tmpdir_prefix (str)

    Return type:

      None

  create_runtime(env, runtime_context)

    Return the Singularity runtime list of commands and options.

    Parameters:

      - env (collections.abc.MutableMapping[str, str])

      - runtime_context (cwltool.context.RuntimeContext)

    Return type:

      tuple[list[str], str | None]