Developer Interface

Main Interface

Examples for the most relevant api functions can be viewed in the test file. licheck’s API uses type hints instead of assertions to check input and output types.

licheck.build_command(binary: str, license_program: str, file: str) → str

Build a command to let the license programs discover all packages.

Parameters

  • binary (str) – the path of the executable binary.

  • license_program (str) – the program name.

  • file (str) – the file name where the licenses need to be checked.

Returns

the command string

Return type

str

Raises

a built-in exception.

licheck.check_cache_structure(cache: dict) → bool

Check the cache data structure.

Parameters

cache – an object containing the cache.

Typecache

dict

Returns

True if the cache is valid, False otherwise.

Return type

bool

Raises

a built-in exception.

licheck.check_configuration_structure(configuration: dict, local: bool = True) → bool

Check the configuration file data structure.

Parameters

  • configuration – an object containing the configuration.

  • local (bool) – if True assert local configurations.

Returns

True if the configuration is valid, False otherwise.

Return type

bool

Raises

a built-in exception.

licheck.check_data_object_structure(data: list) → bool

Check the common data structure.

Parameters

data (list) – a list with a common structure in this program.

Returns

True if the cache is valid, False otherwise.

Return type

list

Raises

a built-in exception.

licheck.check_dependencies_files_data_structure(dependencies_files: dict)

Check that the data structure is a dict of filenames and checksums.

Parameters

dependencies_files (dict) – the data structure.

Raises

TypeError, NotAChecksum or a built-in exception.

licheck.check_licenses(packages: list, licenses_allowed: list, include_empty_as_errors: bool = True) → list

Filter packages to include only the ones with errors.

Parameters

  • packages (list) – an object with a common structure in this program.

  • licenses_allowed (list) – the file name.

  • include_empty_as_errors (bool) – if set to True add a package to the error list if the license_long attribute is empty. Defaults to True.

Returns

a sublist of packages containing the invalid packages.

Return type

list

Raises

a built-in exception.

licheck.create_cache_output(packages: list, file_checksum: str, table: dict)

Populate an object with relevant data.

Parameters

  • packages (list) – an object with a common structure in this program.

  • file_checksum (str) – the SHA-512 checksum of the file content.

  • table (dict) – the object to be populated.

Raises

InvalidCommonDataStructure or a built-in exception.

licheck.create_data_object(input: list, license_program: str, file: str) → list

Create a data structure common to all outputs.

Parameters

  • input (list) – a list of objects containing the dependencies.

  • license_program (str) – the program name.

  • file (str) – the file name where the licenses need to be checked.

Returns

a list of objects with a common structure in this program.

Return type

list

Raises

a built-in exception.

licheck.create_dependencies_files_data_structure(dependencies_files: list) → dict

Create an object that couples file names and their checksums.

Parameters

dependencies_files – a list of files containing the dependencies to be checked.

Returns

an object with keys the file names and values their checksum.

Return type

dict

Raises

a built-in exception.

licheck.get_binary_and_program(language: str) → tuple

Get the license binary path and the program name.

Parameters

language (str) – the name of a programming language.

Returns

a tuple containing the binary and the program name of the license program.

Return type

tuple

Raises

a BinaryDoesNotExist or a built-in exception.

licheck.get_data(command: str, license_program: str) → dict

Run a command to gen an object with the output of the licenses.

Parameters

  • command – the command string executed by the shell.

  • license_program (str) – the program name.

Returns

an object with a specific structure depending from license_program.

Return type

dict

Raises

InvalidOutput or a built-in exception.

licheck.is_sha512_checksum(string: str) → bool

Check that a string is a valid hex representation of an SHA512 checksum.

Parameters

string (str) – a string.

Returns

True if the string is a valid hexadecimal representation of a SHA512 checksum, False otherwise.

Return type

bool

Raises

a built-in exception.

licheck.pipeline(configuration_file: str = '.allowed_licenses.yml', clear_cache: bool = False, cut_table_output: bool = False)

Run the pipeline.

Parameters

  • configuration_file (str) – the path of the configuration file.

  • clear_cache (bool) – if set to True remove the cache directory. Defaults to True.

  • cut_table_output (bool) – if set to True license colums are cut. Defaults to True.

Raises

a built-in exception.

licheck.prepare_print(packages: list, cut_output: bool = False) → list

Re-format the output.

Parameters

  • packages (list) – an object with a common structure in this program.

  • cut_output (bool) – if set to True license colums are cut. Defaults to True.

Returns

an edited copy packages.

Return type

list

Raises

a built-in exception.

licheck.print_errors(packages: list)

Print the packages with errors.

Parameters

packages (list) – an object with a common structure in this program.

Raises

a built-in exception.

licheck.read_cache_file(file: str) → dict

Read the cache file.

Parameters

file (str) – the path of the cache file.

Returns

an object containing the cache.

Return type

dict

Raises

InvalidCache or a built-in exception.

licheck.read_configuration_file(file: str, local: bool = True) → tuple

Read the configuration file.

Parameters

  • file (str) – the file name of the configuration file.

  • local (bool) – the file name.

Returns

a tuple with the data fields.

Return type

tuple

Raises

InvalidConfiguration or a built-in exception.

licheck.read_remote_files(include_files: list, cache_dir: str) → list

Get the list of allowed licenses from remote files.

Parameters

  • include_files (list) – a list of URLs of configuration files.

  • cache_dir (str) – the directory where all the cache files lie.

Returns

a list of allowed licenses.

Return type

list

Raises

IncoherentProgrammingLanguageValue or a built-in exception.

licheck.read_yaml_file(file: str) → dict

Read a YAML file and load the object.

Parameters

file (str) – the file name.

Returns

an object.

Return type

dict

Raises

a PyYAML or a built-in exception.

licheck.save_cache(data: list, existing_cache: dict, files_struct: dict, cache_file: str)

Save exising and new cache.

Parameters

  • data (list) – an object containing the data formatted for this program.

  • existing_cache (dict) – pre-existing data before running this program.

  • files_struct (dict) – an object with file names and their checksums.

  • cache_file (str) – the file where to write the output.

Raises

a built-in exception.

licheck.transform_cache_to_data_object(cache: dict, file: str, file_checksum: str) → list

Given the cache data structure, transform it into the one used in this program.

Parameters

  • cache (dict) – an object representing the cache.

  • file (str) – the file name.

  • file_checksum (str) – the SHA-512 checksum of the file content.

Returns

a list of objects with a common structure in this program.

Return type

dict

Raises

a built-in exception.

licheck.write_cache(table: dict, cache_file: str)

Write an object as a YAML file.

Parameters

  • table (dict) – an object with the cache.

  • cache_file (str) – the file where to write the output.

Raises

a PyYAML or a built-in exception.

Exceptions

exception licheck.BinaryDoesNotExist

Binary Does Not Exist.

exception licheck.IncoherentData

Input data is not what expected.

exception licheck.IncoherentProgrammingLanguageValue

The programming language value is not uniform.

exception licheck.InvalidCache

Invalid Cache.

exception licheck.InvalidCommonDataStructure

Invalid Common Data Structure.

exception licheck.InvalidConfiguration

Invalid Configuration.

exception licheck.InvalidOutput

The output from an external process in unexpected.

exception licheck.NotAChecksum

String is not a valid SHA512 checksum.