Package commons :: Module files

[frames] | no frames]

Module files

source code

File and directory manipulation.

Classes

[hide private]

disk_double_buffer
A simple disk double-buffer.

Functions

[hide private]

soft_makedirs(path)
Emulate mkdir -p (doesn't complain if it already exists). source code

str

temp_dir(base_dir_name, do_create_subdir=True)
Get a temporary directory without polluting top-level /tmp.

source code

cleanse_filename(filename)
Replaces all problematic characters in a filename with "_", as specified by invalid_filename_chars. source code

bool

versioned_guard(path, fresh_version)
Maintain a version object.

source code

versioned_cache(version_path, fresh_version, cache_path, cache_func)
If fresh_version is newer than the version in version_path, then invoke cache_func and cache the result in cache_path (using pickle).

source code

read_file(path)

source code

write_file(path, contents)

source code

write_or_rm(p, contents)
Write the file or remove it if contents is empty.

source code

is_nonempty_file(path)

source code

Variables

[hide private]

invalid_filename_chars = '*|\\/:<>?'
The characters which are usually prohibited on most modern file systems.

invalid_filename_chars_regex = '[*|\\\\\\/:<>?]'
A regex character class constructed from invalid_filename_chars.

HIGHEST_PROTOCOL = 2

__package__ = 'commons'

compatible_formats = ['1.0', '1.1', '1.2', '1.3', '2.0']

format_version = '2.0'

Function Details

[hide private]

soft_makedirs(path)

source code

Emulate mkdir -p (doesn't complain if it already exists).

Parameters:

path (str) - The path of the directory to create.

Raises:

OSError - If it cannot create the directory. It only swallows OS error 17.

temp_dir(base_dir_name, do_create_subdir=True)

source code

Get a temporary directory without polluting top-level /tmp. This follows Ubuntu's conventions, choosing a temporary directory name based on the given name plus the user name to avoid user conflicts.

Parameters:

base_dir_name (str) - The "name" of the temporary directory. This is usually identifies the purpose of the directory, or the application to which the temporary directory belongs. E.g., if joe calls passes in "ssh-agent" on a standard Linux/Unix system, then the full path of the temporary directory will be "/tmp/ssh-agent-joe".
do_create_subdir (bool) - If True, then creates a sub-sub-directory within the temporary sub-directory (and returns the path to that). The sub-sub-directory's name is randomized (uses tempfile.mkdtemp).

Returns: str

The path to the temporary (sub-)sub-directory.

cleanse_filename(filename)

source code

Replaces all problematic characters in a filename with "_", as specified by invalid_filename_chars.

Parameters:

filename (str) - The filename to cleanse.

versioned_guard(path, fresh_version)

source code

Maintain a version object. This is useful for working with versioned caches.

Parameters:

path (str) - The path to the file containing the cached version object.
fresh_version (object (any type that can be compared)) - The actual latest version that the cached version should be compared against.

Returns: bool

True iff the cached version is obsolete (less than the fresh version or doesn't exist).

versioned_cache(version_path, fresh_version, cache_path, cache_func)

source code

If fresh_version is newer than the version in version_path, then invoke cache_func and cache the result in cache_path (using pickle).

Note the design flaw with versioned_guard: the updated version value is stored immediately, rather than after updating the cache.

Parameters:

version_path (str) - The path to the file version.
fresh_version (object (any type that can be compared)) - The actual, up-to-date version value.
cache_path (str) - The path to the cached data.
cache_func (function (no arguments)) - The function that produces the fresh data to be cached.