The Filesystem Utils Module (`tendril.utils.fsutils`)¶

This module provides utilities to deal with filesystems. For the most part, this module basically proxies specific requests to various other third-party or python libraries.

Module Contents

`TEMPDIR`	The path to the temporary directory which all application code can import, and create whatever temporary files it needs within it.
`get_tempname`()	Gets a random string for use as a temporary filename.
`fsutils_cleanup`()	Called when the python interpreter is shutting down.
`zipdir`(path, zfpath)	Creates a zip file at `zfpath` containing all the files in `path`.
`get_concatenated_fd`(filepaths)	Generates a `cStringIO` instance containing the content of the files at the provided `filepaths`.
`Crumb`	A named tuple definition for a Crumb of a Breadcrumb.
`get_path_breadcrumbs`(path[, base, rootst, ...])	Given a certain filesystem `path` and an optional `base`, this function returns a list of `Crumb` objects, forming the breadcrumbs to that path from the base.
`get_folder_mtime`(folder[, fs])	Given the path to a certain filesystem `folder`, this function returns a `datetime.datetime` instance representing the time of the latest change of any file contained within the folder.
`get_file_mtime`(f[, fs])	Given the path to a certain filesystem `file`, this function returns a `datetime.datetime` instance representing the time of the latest change of that file.
`get_file_hash`(filepath[, hasher, blocksize])	Return the hash of the file located at the given filepath, using the hasher specified.
`in_directory`(path, directory)	Naive check of whether a path is located at or within a specified directory.
`VersionedOutputFile`(pathname[, numSavedVersions])	Create a new output file.
`import_`(fpath)	Imports the file specified by the `fpath` parameter using the `imp` python module and returns the loaded module.
`get_parent`(obj[, n])	This function is intended for use by modules imported from outside the package via the filesystem to get around the behavior of python’s super() which breaks when something is effectively reloaded.

tendril.utils.fsutils.TEMPDIR = '/tmp/tmp5M6hcc'¶

The path to the temporary directory which all application code can import, and create whatever temporary files it needs within it.

This directory will be removed by Tendril at clean application exit or by the Operating System as per it’s policies.

Every execution of tendril in a separate process owns it’s own temporary directory.

See also

fsutils_cleanup()

tendril.utils.fsutils.get_tempname()[source]¶

Gets a random string for use as a temporary filename.

Returns:	A filename that can be used.

tendril.utils.fsutils.zipdir(path, zfpath)[source]¶

Creates a zip file at zfpath containing all the files in path. This function is simple wrapper around python’s zipfile module.

Parameters:	path – Path of the source folder, which is to be added to the zip file. zfpath – Path of the zip file to create.
Returns:	The path of the created zip file.

tendril.utils.fsutils.get_concatenated_fd(filepaths)[source]¶

Generates a cStringIO instance containing the content of the files at the provided filepaths.

The returned cStringIO instance is a file-like object, holding in memory the concatenated content of the source files, included in the same ordering as in the provided list.

Parameters:	filepaths – List of filepaths
Returns:	StringIO / cStringIO object with the contents of the files

class tendril.utils.fsutils.Crumb¶

Bases: tuple

A named tuple definition for a Crumb of a Breadcrumb. This can be used to construct breadcrumb navigation by application code. While it resides in the tendril.utils.fs module, the same type should be used for other forms of breadcrumbs as well. It is placed here due to its proximity to os.path.

_asdict()¶: Return a new OrderedDict which maps field names to their values

_fields = ('name', 'path')¶

classmethod _make(iterable, new=<built-in method __new__ of type object at 0x906d60>, len=<built-in function len>)¶: Make a new Crumb object from a sequence or iterable

_replace(_self, **kwds)¶: Return a new Crumb object replacing specified fields with new values

name¶: Alias for field number 0

path¶: Alias for field number 1

tendril.utils.fsutils.get_path_breadcrumbs(path, base=None, rootst='Root', prefix=None)[source]¶

Given a certain filesystem path and an optional base, this function returns a list of Crumb objects, forming the breadcrumbs to that path from the base. The value of rootst is prepended to the list, providing a means to insert a title indicating the base of the breadcrumb list. An optional prefix can be provided, which is prepended to the path (as opposed to the rootst breadcrumb, which does not effect the path).

Parameters:	path (str) – The path to the target, compatible with `os.path` base (str) – The path of the base, compatible with `os.path`. Optional. rootst (str) – The string for the root breadcrumb. prefix (str) – The string for the prefix breadcrumb.
Returns:	The breadcrumbs.
Return type:	`list` of `Crumb`

tendril.utils.fsutils.register_for_changes(path, callback, *args, **kwargs)[source]¶

class tendril.utils.fsutils.ThrottledEventHandler(spacing=0)[source]¶

Bases: watchdog.events.FileSystemEventHandler

add_callback(callback, *args, **kwargs)[source]¶

on_any_event(event)[source]¶

arm()[source]¶

disarm()[source]¶

trigger()[source]¶

tendril.utils.fsutils.get_folder_mtime(folder, fs=None)[source]¶

Given the path to a certain filesystem folder, this function returns a datetime.datetime instance representing the time of the latest change of any file contained within the folder.

Parameters:	folder (str) – The path to the `folder`, compatible with `os.path` fs (`fs.base.FS`) – The pyfilesystem to use. (Default) None for local fs.
Returns:	The time of the latest change within the `folder`
Return type:	`datetime.datetime`

See also

get_file_mtime()

tendril.utils.fsutils.get_file_mtime(f, fs=None)[source]¶

Given the path to a certain filesystem file, this function returns a datetime.datetime instance representing the time of the latest change of that file.

Parameters:	f (str) – The path to the `file`, compatible with `os.path` fs (`fs.base.FS`) – The pyfilesystem to use. (Default) None for local fs.
Returns:	The time of the latest change within the `folder`
Return type:	`datetime.datetime`

See also

get_folder_mtime()

tendril.utils.fsutils.get_file_hash(filepath, hasher=None, blocksize=65536)[source]¶

Return the hash of the file located at the given filepath, using the hasher specified. The hash is encoded in base64 to make it shorter while preserving collision resistance. Note that the resulting hash is case sensitive.

See also

hashlib

Parameters:	filepath – Path of the file which needs to be hashed. hasher – Hash function to use. Default `hashlib.sha256` blocksize – Size of each block to hash.
Returns:	The hex digest for the file.

tendril.utils.fsutils.in_directory(path, directory)[source]¶

Naive check of whether a path is located at or within a specified directory.

Warning

os.path.commonprefix() should not actually be trusted here.

Parameters:	path – directory –
Returns:	True, if path is contained under the directory’s tree.

class tendril.utils.fsutils.VersionedOutputFile(pathname, numSavedVersions=3)[source]¶

Create a new output file.

Parameters:	pathname – The name of the file to [over]write. numSavedVersions – How many of the most recent versions of pathname to save.

close()[source]¶

as_file()[source]¶: Return self’s shadowed file object, since marshal is pretty insistent on working w. pure file objects.

_replace_current_file()[source]¶: Replace the current contents of self’s named file.

_backup_current_file()[source]¶: Save a numbered backup of self’s named file.

_versioned_name(revision)[source]¶: Get self’s pathname with a revision number appended.

_current_revision()[source]¶: Get the revision number of self’s largest existing backup.

_revisions()[source]¶: Get the revision numbers of all of self’s backups.

_delete_old_revisions()[source]¶: Delete old versions of self’s file, so that at most _numSavedVersions versions are retained.

tendril.utils.fsutils.fsutils_cleanup()[source]¶

Called when the python interpreter is shutting down. Cleans up all tendril.utils.fs related objects and other artifacts created by the module. Each user of the TEMPDIR should clean up it’s own files and folders before now. If TEMPDIR is non-empty at this point, this function won’t delete the folder.

Performs the following tasks:

Removes the TEMPDIR

tendril.utils.fsutils.import_(fpath)[source]¶

Imports the file specified by the fpath parameter using the imp python module and returns the loaded module.

Parameters:	fpath – Path of the python module to import.
Returns:	Module object of the imported python module.

tendril.utils.fsutils.get_parent(obj, n=1)[source]¶: This function is intended for use by modules imported from outside the package via the filesystem to get around the behavior of python’s super() which breaks when something is effectively reloaded.

Todo

A cleaner solution to handle this condition is needed.

The Filesystem Utils Module (tendril.utils.fsutils)¶

The Filesystem Utils Module (`tendril.utils.fsutils`)¶