cots.core – Product Handler Core Module

This module defines core functions and classes for product handlers.

Product handlers are derived classes from BaseProduct class.

Public Classes

This module has has several public class listed below in alphabetical order.

BaseProduct

DownloadHandler

Public Functions

This module has a number of functions listed below in alphabetical order.

get_handler

get_file_hash

Objects reference

This section details the objects defined in this module.

class cots.core.BaseProduct

Bases: object

Common base class for all product handlers.

name

The name of the product. It is used in report mail, log file and as filename for the installer (see fetch)

Type

str

display_name

The name of the product as it appears in the ‘Programs and Features’ control panel (see Uninstall Registry Key).

Type

str

version

The current version of the product using the editor versioning rules.

Type

str

published

The date of the installer’s publication expressed in the RFC 3339 format.

Type

str

target

The target architecture type (the Windows’ one) for the product. This argument must be one of the following values: TARGET_X86, TARGET_X64 or TARGET_UNIFIED. The “build target” of the application to retrieve. This part must contain one of the following values:

  • win: Windows 32 bits

  • win64: Windows 64 bits

  • osx: MacOS X

  • linux64: Linux x86 64 bits

  • linux: Linux i686

Type

str

description

Short description of the product (~250 characters).

Type

str

editor

The name of the editor of the product.

Type

str

web_site_location

The location of the editor ou product web site.

Type

str

location

The location of the current version of the installer.

Type

str

icon

The name of the icon file (in the same directory than the installer)

Type

str

announce_location

The location of the page announcing the product releases.

Type

str

feed_location

The location of the RSS feed announcing the product releases.

Type

str

release_note_location

The location of the release note for the detailed history change of the product.

Type

str

change_summary

The changelog of the product since the deployed product.

Type

str

installer

The filename of the installer (local full path).

Type

str

file_size

The size of the product installer expressed in bytes.

Type

int

secure_hash

The secure_hash value of the product installer. It’s a 2-tuple containing, in this order, the name of secure_hash algorithm (see hashlib.algorithms_guaranteed) and the secure_hash value in hexadecimal notation.

Type

2-tuple

std_inst_args

Arguments to use with the installer for a standard installation.

Type

str

silent_inst_args

Arguments to use with the installer for a silent installation (i.e. without any user’s interaction, typically while an automated deployment using lappdeploy script).

Type

str

Public Methods

This class has a number of public methods listed below in alphabetical order.

dump

get_origin

fetch

is_update

load

get_name
Methods to Override

This class is a base class, so a number of public methods must be overridden. They are listed below in alphabetical order.

get_origin

is_update
Using BaseProduct…

This class is the base class for product handler used by lapptrack.LAppTrack and this one only use the public methods.

After created a class instance, the get_origin method populate the attributes with the most up-to-date information from the editor’s site. An alternative way, is to call the load method to populate attributes with a set of data previously saved on disk.

Then calling fetch method retrieves the current version (i.e. the one described in the attributes) of the installer and store it on the local disk.

Then you can save the updated instances by calling the dump method.

dump()

Dump a product class.

Returns

Contain a copy of the instance variables values.

Return type

dict

fetch(dirpath)

Download the product installer.

Parameters

dirpath (str) – The directory path name where to store the installer package.

Returns

True if the download of the file went well. In case of failure, the members are not modified and an error log is written.

Return type

bool

Raises

TypeError – Parameters type mismatch.

get_name()

Return a comprehensive name of the product

Returns

a human readable string with the handler attributes.

Return type

str

get_origin()

Get product information from the remote repository.

The latest catalog of the product is downloaded and parsed.

Returns

True if the download of the file went well. In case of failure, the members are not modified and an error log is written.

Return type

bool

Raises

TypeError – Parameters type mismatch.

is_update(product)

Return if this instance is an update of the product

This method compare the version of the two product, and return the comparison result.

Parameters

product (BaseProduct) – The reference product (i.e. the deployed one)

Returns

True if this instance is an update of the product specified by the product parameter.

Return type

bool

load(attributes)

Load a product class.

Parameters

attributes (dict) – The instance variables values to set. Previous value of the instance variables kept if this argument value is None. The key value pairs which don’t exist in the instance variables dictionary are ignored.

Raises

TypeError – Parameters type mismatch.

class cots.core.DownloadHandler(url, path=None, type=None, length=None, hash=None, progress=None)

Bases: object

File Download Handler

This class is a handler to download files available on a HTTP or FTP server. It fully manages the download process and the retrieved file may be stored in a regular or a temporary file.

Parameters

  • url (str) – The URL of the file to retrieve.

  • path (str) – The local pathname of the retrieved file. An empty string will force the use of a temporary file (see NamedTemporaryFile()). If the pathname is a directory, the retrieved file will be written in this directory, and the filename will be guessed from the url or HTTP response headers. [TODO]If the pathname is a valid filename, the retrieved file will use it.

  • type (str) – (optional) The expected mime type of the retrieved file. No check will be done if the value is None.

  • length (int) – (optional) The expected length of the retrieved file expressed in bytes. None means that the expected length is unknown.

  • hash (tuple) – The expected secure hash value of the retrieved file. No check will be done if the value is None. It’s a 2-tuple containing, in this order, the name of secure hash algorithm (see algorithms_guaranteed) and the secure hash value in hexadecimal notation. If the secure hash algorithm is not supported, it will be ignored.

  • progress (ProgressIndicatorWidget) – The progress widget. The None value means that no progress indicator will be displayed.

Raises

TypeError – Parameters type mismatch.

Public Methods

This class has a number of public methods listed below in alphabetical order.

fetch
Using DownloadHandler…

After created a class instance, the fetch method downloads the file and populates the attributes.

_close_container(keep=True)

Close the container and check its content.

Parameters

keep (bool) – True to indicate to keep the local copy of the retrieved file. The False value is usefull in case of error while the download process.

Returns

True if the downloading of the file went well.

Return type

bool

_get_filename_from_headers()

Get the file name from the Content-Disposition header field.

This method returns the file name specified in the Content-Disposition header field as described in the RFC 2183 if it exists.

TODO This method checks the file name compatibility with the underlying file system. If the suggested file name is not compatible, the method returns None.

Returns

a regular file name or None.

Return type

str

_get_filename_from_url()

Get the file name from the url attribute.

This method returns the file name specified in the URL.

TODO This method checks the file name compatibility with the underlying file system. If the suggested file name is not compatible, the method returns None.

Returns

a regular file name or None.

Return type

str

_open_container()

Open the container for the future retrieved file.

This method opens either a temporary file or a regular file depending on the value of the path attribute. It sets the _file and the filename attributes.

Returns

True if the opening of the file went well.

Return type

bool

_post_check_hash()

Check the secure hash of the retrieved file.

Returns

True if the computed secure hash is equal to that expected (_exp_hash). The method return True if the control must be ignored (see hash parameter)

Return type

bool

_post_check_length()

Check the length of the retrieved file.

Returns

True if the length is equal to that expected (_exp_length). The method return True if the control must be ignored (see length parameter)

Return type

bool

_pre_check_length()

Check the length of the file to retrieve.

Returns

True if the length is equal to that expected (_exp_length). The method return True if the control must be ignored (see length parameter)

Return type

bool

_pre_check_type()

Check the mime type of the file to retrieve.

Returns

True if the MIME type is equal to that expected (_exp_type). The method return True if the control must be ignored (see type parameter)

Return type

bool

_write_container()

Fill the container with the content of the retrieved files

Returns

True if the downloading of the file went well.

Return type

bool

fetch()

Download the product installer.

Returns

True if the download of the file went well. In case of failure, an error log is written.

Return type

bool

filename

The local pathname of the retrieved file.

Type

str

hash

The secure hash value of the retrieved file. A secure hash is always computed and the default algorithm is SHA-1.

Type

hashlib.hash

length

The length of the retrieved file expressed in bytes.

Type

int

type

The mime type of the retrieved file. The default value is application/octet-stream as defined by the IANA.

Type

str

url

The URL of the retrieved file. It may differs from the original url if a redirect was followed.

Type

str

Functions reference

This section details the specific functions used in this module.

cots.core.get_handler(qualname)

Retrieve an instance of a handler class.

A handler class is appointed by its qualified name (package.module.MyHandler for example). If the module part is not specified, an ImportError exception is raised.

Parameters

qualname (str) – The qualified name of the handler class.

Returns

an instance of the handler class.

Return type

BaseProduct

Raises

  • TypeError – Parameters type mismatch.

  • ImportError – Import fails to find the handler module or class.

cots.core.get_file_hash(path, hash_name)

Compute a secure hash based on the content of a file.

Parameters
Returns

A hash object instance (see hashlib). This instance contains the computed hash of the given path.

Return type

HASH

Data reference

This section details global data, including both variables and values used as ‘defined constants’.

cots.core.TARGET_X86 = 'x86'

The application works only on 32 bits architecture.

cots.core.TARGET_X64 = 'x64'

The application works only on 64 bits architecture.

cots.core.TARGET_UNIFIED = 'unified'

The application or the installation program work on both architectures.