API Reference

Simple API to include filetransfer in a Python script.

This module uses a logger with the name 'filetransfer'.

Changed in version 0.7.0: There is no run() function anymore; the required function is returned by configure()

See: Configuration, examples configure() and transfer()

exception filetransfer.Error

Base error.

exception filetransfer.ConfigError

Raised when there is a problem with the configuration.

Changed in version 0.10.0: code 1 -> 3

code = 3

Status code

exception filetransfer.ConnectError

Raised when there is a problem connecting to a server.

code = 2

Status code

exception filetransfer.TransferError

Raised when there is a fatal problem during transfer.

Changed in version 0.10.0: code 3 -> 2

code = 2

Status code

exception filetransfer.SingleInstanceError

Raised when a single instance requirement is violated.

New in version 0.9.0.

Changed in version 0.10.0: code 4 -> 0

code = 0

Status code

exception filetransfer.NotReadyError

Raised when a ready file is required but not present.

New in version 0.10.0.

code = 0

Status code

exception filetransfer.Terminated

Raised when terminated with SIGTERM.

This is a subclass of BaseException.

See: filetransfer.set_sigterm_handler()

Changed in version 0.10.0: code 8 -> 5

code = 5

Status code

class filetransfer.JobResult

Class that contains job results.

This class has the following fields:

files_cnt

number of successfully transferred files

src_error_cnt

number of files that could not be read

tgt_error_cnt

number of files that could not be written

file_list
list of tuples: (path, info, tag)

  • path: path relative to source/target directory

  • info: duration of transfer or error text

  • tag: FileTags

if data collection is disabled this will be None

New in version 0.7.0.

Changed in version 0.10.0: file_list tags: string -> FileTags members

class filetransfer.FileTags(value)

Tags for file_list of JobResult.

Members:

  • TRANSF: '=' (transferred)

  • SRCERR: '>' (source error)

  • TGTERR: '<' (target error)

The string representation of an enum member is just the value of the member.

New in version 0.10.0.

filetransfer.set_sigterm_handler()

Set handler for SIGTERM.

This function sets the same handler that is used when the filetransfer script is run. It raises Terminated on receiving the SIGTERM signal. This function can only be run from the main thread (see: Signals and threads and signal.signal()).

Raises

ValueError – if not called from the main thread

New in version 0.9.0.

filetransfer.configure(cfg_file, job_id, **kwargs)

Configure the application.

This function returns a function (called run() from here on) that must be called to run the actual file transfer. run() takes one optional argument that must be an instance of a subclass of BaseException that will be reraised within run(). The intended use for this is to handle an exception from code between configure() and run() in the usual way (logging and sending an email notification). The transfer itself will not be run. See example.

filetransfer.run(exc=None)
Parameters

exc (BaseException) – exception to be reraised within this function

Returns

result and exit code (0: success, 1: with errors)

Return type

JobResult, int

Raises

Changed in version 0.7.3: Add exception parameter to run()

Changed in version 0.10.0: Return JobResult and exit code

You can put your own configuration sections in the application and job configuration files. The names of theses sections must start with x:. If you define the same name in both configuration files the sections will be merged with the keys in the job configuration file taking precedence. The prefix x: will be stripped from the section names before putting them in a newly created ConfigParser object that will be returned. See example.

The logging configuration from cfg_file will only be used if logging was not configured before the call to this function.

Parameters

  • cfg_file (path-like object) – the application configuration file

  • job_id (str) – the Job-ID

  • kwargs – ConfigParser arguments for the extra configuration

Returns

run() function and extra configuration

Return type

function(), configparser.ConfigParser

Raises

filetransfer.ConfigError – if there is a problem with the configuration

Changed in version 0.7.0: Return function for running the job

Changed in version 0.10.0: Does not raise configparser.Error and OSError anymore

filetransfer.transfer(src_cfg, tgt_cfg=None, *, collect_data=False)

Transfer files.

The first parameter (src_cfg) may be a dict or a ConfigParser object.

If it is a dict the argument tgt_cfg must also be a dict and they must represent valid [source] and [target] sections of a Job Configuration.

Else the ConfigParser object must contain those sections and the second parameter can be omitted because it will be ignored.

When using FTP, FTPS or SFTP the host_id option must be omitted and the options from the host configuration must be contained in the above configuration objects.

See examples.

Parameters
Returns

job result

Return type

filetransfer.JobResult

Raises

Changed in version 0.7.0: This function now returns a JobResult object

Changed in version 0.10.0: Add parameter collect_data