globalfunctions

Global common functions.

aeneas.globalfunctions.absolute_path(path, from_file)

Return the absolute path of a file or directory, specified as path relative to (the parent directory of) from_file.

This method is intented to be called with __file__ as second argument.

If path is None, return None.

Example:

path="res/foo.bar"
from_file="/abc/def/ghi.py"
=> "/abc/def/res/foo.bar"

Parameters:

• path (string) – the file path
• from_file (string) – the reference file

Return type:

string

aeneas.globalfunctions.bundle_directory()

Return the absolute path of the bundle directory if running from a frozen binary; otherwise return None.

Return type:string

aeneas.globalfunctions.can_run_c_extension(name=None)

Determine whether the given Python C extension loads correctly.

If name is None, tests all Python C extensions, and return True if and only if all load correctly.

Parameters:name (string) – the name of the Python C extension to test Return type:bool

aeneas.globalfunctions.close_file_handler(handler)

Safely close the given file handler.

Parameters:handler (object) – the file handler (as returned by tempfile)

aeneas.globalfunctions.config_dict_to_string(dictionary)

Convert a given config dictionary

dictionary[key_1] = value_1
dictionary[key_2] = value_2
...
dictionary[key_n] = value_n

into the corresponding string

key_1=value_1|key_2=value_2|...|key_n=value_n

Parameters:dictionary (dict) – the config dictionary Return type:string

aeneas.globalfunctions.config_string_to_dict(string, result=None)

Convert a given configuration string

key_1=value_1|key_2=value_2|...|key_n=value_n

into the corresponding dictionary

dictionary[key_1] = value_1
dictionary[key_2] = value_2
...
dictionary[key_n] = value_n

Parameters:string (string) – the configuration string Return type:dict

aeneas.globalfunctions.config_txt_to_string(string)

Convert the contents of a TXT config file into the corresponding configuration string

key_1=value_1|key_2=value_2|...|key_n=value_n

Leading and trailing blank characters will be stripped and empty lines (after stripping) will be ignored.

Parameters:string (string) – the contents of a TXT config file Return type:string

aeneas.globalfunctions.config_xml_to_dict(contents, result, parse_job=True)

Convert the contents of a XML config file into the corresponding dictionary

dictionary[key_1] = value_1
dictionary[key_2] = value_2
...
dictionary[key_n] = value_n

Parameters:

• contents (bytes) – the XML configuration contents
• parse_job (bool) – if True, parse the job properties; if False, parse the tasks properties

Return type:

dict (parse_job=True) or list of dict (parse_job=False)

aeneas.globalfunctions.copytree(source_directory, destination_directory, ignore=None)

Recursively copy the contents of a source directory into a destination directory. Both directories must exist.

This function does not copy the root directory source_directory into destination_directory.

Since shutil.copytree(src, dst) requires dst not to exist, we cannot use for our purposes.

Code adapted from http://stackoverflow.com/a/12686557

Parameters:

• source_directory (string) – the source directory, already existing
• destination_directory (string) – the destination directory, already existing

aeneas.globalfunctions.custom_tmp_dir()

Return the path of the temporary directory to use.

On POSIX OSes (Linux and OS X), return the value of TMP_PATH_DEFAULT_POSIX (e.g., /tmp/).

On non-POSIX OSes, return the value of TMP_PATH_DEFAULT_NONPOSIX (i.e., None), so that tempfile will use the directory specified by the environment/user TMP or TEMP variable.

Return type:string

aeneas.globalfunctions.datetime_string(time_zone=False)

Return a string representing the current date and time, in YYYY-MM-DDThh:mm:ss or YYYY-MM-DDThh:mm:ss+hh:mm format

Parameters:time_zone (boolean) – if True, add the time zone offset. Return type:string

aeneas.globalfunctions.delete_directory(path)

Safely delete a directory.

Parameters:path (string) – the file path

aeneas.globalfunctions.delete_file(handler, path)

Safely delete file.

Parameters:

• handler (object) – the file handler (as returned by tempfile)
• path (string) – the file path

aeneas.globalfunctions.directory_exists(path)

Return True if the given path string points to an existing directory.

Parameters:path (string) – the file path Return type:bool

aeneas.globalfunctions.ensure_parent_directory(path, ensure_parent=True)

Ensures the parent directory exists.

Parameters:

• path (string) – the path of the file
• ensure_parent (bool) – if True, ensure the parent directory of path exists; if False, ensure path exists

Raises:

OSError: if the path cannot be created

aeneas.globalfunctions.file_can_be_read(path)

Return True if the file at the given path can be read.

Parameters:path (string) – the file path Return type:bool

New in version 1.4.0.

aeneas.globalfunctions.file_can_be_written(path)

Return True if a file can be written at the given path.

Parameters:path (string) – the file path Return type:bool

Warning

This function will attempt to open the given path in write mode, possibly destroying the file previously existing there.

New in version 1.4.0.

aeneas.globalfunctions.file_exists(path)

Return True if the given path string points to an existing file.

Parameters:path (string) – the file path Return type:bool

aeneas.globalfunctions.file_extension(path)

Return the file extension.

Examples:

/foo/bar.baz => baz
None         => None

Parameters:path (string) – the file path Return type:string

aeneas.globalfunctions.file_name_without_extension(path)

Return the file name without extension.

Examples:

/foo/bar.baz => bar
/foo/bar     => bar
None         => None

Parameters:path (string) – the file path Return type:string

aeneas.globalfunctions.file_size(path)

Return the size, in bytes, of the file at the given path. Return -1 if the file does not exist or cannot be read.

Parameters:path (string) – the file path Return type:int

aeneas.globalfunctions.fix_slash(path)

On non-POSIX OSes, change the slashes in path for loading in the browser.

Example:

c:\abc\def => c:/abc/def

Parameters:path (string) – the path Return type:string

aeneas.globalfunctions.human_readable_number(number, suffix='')

Format the given number into a human-readable string.

Code adapted from http://stackoverflow.com/a/1094933

Parameters:

• number (variant) – the number (int or float)
• suffix (string) – the unit of the number

Return type:

string

aeneas.globalfunctions.is_bytes(string)

Return True if the given string is a sequence of bytes.

Parameters:string (variant) – the string to test Return type:bool

aeneas.globalfunctions.is_linux()

Return True if running on Linux.

Return type:bool

aeneas.globalfunctions.is_osx()

Return True if running on Mac OS X (Darwin).

Return type:bool

aeneas.globalfunctions.is_posix()

Return True if running on a POSIX OS.

Return type:bool

aeneas.globalfunctions.is_py2_narrow_build()

Return True if running on a Python 2 narrow build.

Return type:bool

aeneas.globalfunctions.is_unicode(string)

Return True if the given string is a sequence of Unicode code points.

Parameters:string (variant) – the string to test Return type:bool

aeneas.globalfunctions.is_utf8_encoded(bstring)

Return True if the given byte string can be decoded into a Unicode string using the UTF-8 decoder.

Parameters:bstring (bytes) – the string to test Return type:bool

aeneas.globalfunctions.is_windows()

Return True if running on Windows.

Return type:bool

aeneas.globalfunctions.mimetype_from_path(path)

Return a mimetype from the file extension.

Parameters:path (string) – the file path Return type:string

aeneas.globalfunctions.norm_join(prefix, suffix)

Join prefix and suffix paths and return the resulting path, normalized.

Parameters:

• prefix (string) – the prefix path
• suffix (string) – the suffix path

Return type:

string

aeneas.globalfunctions.object_to_bytes(obj)

Return a sequence of bytes from the given object.

Parameters:obj (object) – the object Return type:bytes

aeneas.globalfunctions.object_to_unicode(obj)

Return a sequence of Unicode code points from the given object.

Parameters:obj (object) – the object Return type:string

aeneas.globalfunctions.pairs_to_dict(pairs, result=None)

Convert a given list of key=value strings

["key_1=value_1", "key_2=value_2", ..., "key_n=value_n"]

into the corresponding dictionary

dictionary[key_1] = value_1
dictionary[key_2] = value_2
...
dictionary[key_n] = value_n

Parameters:pairs (list) – the list of key=value strings Return type:dict

aeneas.globalfunctions.print_error(msg, color=True)

Print an error message.

Parameters:

• msg (string) – the message
• color (bool) – if True, print with POSIX color

aeneas.globalfunctions.print_info(msg, color=True)

Print an info message.

Parameters:

• msg (string) – the message
• color (bool) – if True, print with POSIX color

aeneas.globalfunctions.print_success(msg, color=True)

Print a success message.

Parameters:

• msg (string) – the message
• color (bool) – if True, print with POSIX color

aeneas.globalfunctions.print_warning(msg, color=True)

Print a warning message.

Parameters:

• msg (string) – the message
• color (bool) – if True, print with POSIX color

aeneas.globalfunctions.read_file_bytes(input_file_path)

Read the file at the given file path and return its contents as a byte string, or None if an error occurred.

Parameters:input_file_path (string) – the file path Return type:bytes

aeneas.globalfunctions.relative_path(path, from_file)

Return the relative path of a file or directory, specified as path relative to (the parent directory of) from_file.

This method is intented to be called with __file__ as second argument.

The returned path is relative to the current working directory.

If path is None, return None.

Example:

path="res/foo.bar"
from_file="/root/abc/def/ghi.py"
cwd="/root"
=> "abc/def/res/foo.bar"

Parameters:

• path (string) – the file path
• from_file (string) – the reference file

Return type:

string

aeneas.globalfunctions.run_c_extension_with_fallback(log_function, extension, c_function, py_function, args, rconf)

Run a function calling a C extension, falling back to a pure Python function if the former does not succeed.

Parameters:

• log_function (function) – a logger function
• extension (string) – the name of the extension
• c_function (function) – the (Python) function calling the C extension
• py_function (function) – the (Python) function providing the fallback
• rconf (aeneas.runtimeconfiguration.RuntimeConfiguration) – the runtime configuration

Return type:

depends on the extension being called

Raises:

RuntimeError: if both the C extension and the pure Python code did not succeed.

New in version 1.4.0.

aeneas.globalfunctions.safe_bytes(string)

Safely convert the given string to a bytes string.

Parameters:string (variant) – the byte string or Unicode string to convert Return type:bytes

aeneas.globalfunctions.safe_float(string, default=None)

Safely parse a string into a float.

On error return the default value.

Parameters:

• string (string) – string value to be converted
• default (float) – default value to be used in case of failure

Return type:

float

aeneas.globalfunctions.safe_get(dictionary, key, default_value, can_return_none=True)

Safely perform a dictionary get, returning the default value if the key is not found.

Parameters:

• dictionary (dict) – the dictionary
• key (string) – the key
• default_value (variant) – the default value to be returned
• can_return_none (bool) – if True, the function can return None; otherwise, return default_value even if the dictionary lookup succeeded

Return type:

variant

aeneas.globalfunctions.safe_int(string, default=None)

Safely parse a string into an int.

On error return the default value.

Parameters:

• string (string) – string value to be converted
• default (int) – default value to be used in case of failure

Return type:

int

aeneas.globalfunctions.safe_print(msg)

Safely print a given Unicode string to stdout, possibly replacing characters non-printable in the current stdout encoding.

Parameters:msg (string) – the message

aeneas.globalfunctions.safe_str(string)

Safely return the given Unicode string from a __str__ function: as a byte string in Python 2, or as a Unicode string in Python 3.

Parameters:string (string) – the string to return Return type:bytes or string

aeneas.globalfunctions.safe_unichr(codepoint)

Safely return a Unicode string of length one, containing the Unicode character with given codepoint.

Parameters:codepoint (int) – the codepoint Return type:string

aeneas.globalfunctions.safe_unicode(string)

Safely convert the given string to a Unicode string.

Parameters:string (variant) – the byte string or Unicode string to convert Return type:string

aeneas.globalfunctions.safe_unicode_stdin(string)

Safely convert the given string to a Unicode string, decoding using sys.stdin.encoding if needed.

If running from a frozen binary, utf-8 encoding is assumed.

Parameters:string (variant) – the byte string or Unicode string to convert Return type:string

aeneas.globalfunctions.split_url(url)

Split the given URL base#anchor into (base, anchor), or (base, None) if no anchor is present.

In case there are two or more # characters, return only the first two tokens: a#b#c => (a, b).

Parameters:url (string) – the url Return type:list of str

aeneas.globalfunctions.time_from_hhmmssmmm(string, decimal_separator='.')

Parse the given HH:MM:SS.mmm string and return a time value.

Parameters:

• string (string) – the string to be parsed
• decimal_separator (string) – the decimal separator to be used

Return type:

TimeValue

aeneas.globalfunctions.time_from_srt(string)

Parse the given HH:MM:SS,mmm string and return a time value.

Parameters:string (string) – the string to be parsed Return type:TimeValue

aeneas.globalfunctions.time_from_ssmmm(string)

Parse the given SS.mmm string and return a time value.

Parameters:string (string) – the string to be parsed Return type:TimeValue

aeneas.globalfunctions.time_from_ttml(string)

Parse the given SS.mmms string (TTML values have an “s” suffix, e.g. 1.234s) and return a time value.

Parameters:string (string) – the string to be parsed Return type:TimeValue

aeneas.globalfunctions.time_to_hhmmssmmm(time_value, decimal_separator='.')

Format the given time value into a HH:MM:SS.mmm string.

Examples:

12        => 00:00:12.000
12.345    => 00:00:12.345
12.345432 => 00:00:12.345
12.345678 => 00:00:12.346
83        => 00:01:23.000
83.456    => 00:01:23.456
83.456789 => 00:01:23.456
3600      => 01:00:00.000
3612.345  => 01:00:12.345

Parameters:

• time_value (float) – a time value, in seconds
• decimal_separator (string) – the decimal separator, default .

Return type:

string

aeneas.globalfunctions.time_to_srt(time_value)

Format the given time value into a HH:MM:SS,mmm string, as used in the SRT format.

Examples:

12        => 00:00:12,000
12.345    => 00:00:12,345
12.345432 => 00:00:12,345
12.345678 => 00:00:12,346
83        => 00:01:23,000
83.456    => 00:01:23,456
83.456789 => 00:01:23,456
3600      => 01:00:00,000
3612.345  => 01:00:12,345

Parameters:time_value (float) – a time value, in seconds Return type:string

aeneas.globalfunctions.time_to_ssmmm(time_value)

Format the given time value into a SS.mmm string.

Examples:

12        => 12.000
12.345    => 12.345
12.345432 => 12.345
12.345678 => 12.346

Parameters:time_value (float) – a time value, in seconds Return type:string

aeneas.globalfunctions.time_to_ttml(time_value)

Format the given time value into a SS.mmms string (TTML values have an “s” suffix, e.g. 1.234s).

Examples:

12        => 12.000s
12.345    => 12.345s
12.345432 => 12.345s
12.345678 => 12.346s

Parameters:time_value (float) – a time value, in seconds Return type:string

aeneas.globalfunctions.tmp_directory(root=None)

Return the path of a temporary directory created by tempfile.

Parameters:root (string) – path to the root temporary directory; if None, the default temporary directory will be used instead Return type:string

aeneas.globalfunctions.tmp_file(suffix='', root=None)

Return a (handler, path) tuple for a temporary file with given suffix created by tempfile.

Parameters:

• suffix (string) – the suffix (e.g., the extension) of the file
• root (string) – path to the root temporary directory; if None, the default temporary directory will be used instead

Return type:

tuple

aeneas.globalfunctions.uuid_string()

Return a uuid4 as a Unicode string.

Return type:string