relentless.data.Directory#

class relentless.data.Directory(path, create=True)#

Context for a filesystem directory.

The directory specified by path (which can be either absolute or relative) is created if it does not already exist. This process is recursive, so path may include multiple directories that do not yet exist. This object represents the final directory in path.

A Directory is a context that can be used to manage the current working directory. Entering the context changes the current working directory to path, and exiting restores the working directory before the context was entered.

Parameters:

path (str) – Absolute or relative directory path.
create (bool) – If True, ensure the directory is created on the filesystem.

Raises:

OSError – If the specified path is not a valid directory.

Examples

Creating a directory:

d = Directory('foo')

Create a directory on the root rank and wait to proceed:

d = Directory('bar', create=relentless.mpi.world.rank_is_root)
relentless.mpi.world.barrier()

Using the context to open a file foo/bar.txt in a directory:

with Directory('foo') as d:
    f = open('bar.txt')

Methods

`cast`(directory[, create])	Try to cast an object to a directory.
`clear_contents`()	Clear the contents of a directory.
`copy_contents`(dest)	Copy the contents of the directory.
`directory`(name[, create])	Get a child directory.
`file`(name)	Get the absolute path to a file in the directory.
`is_empty`()	Check if the directory is empty.
`move_contents`(dest)	Move the contents of the directory.
`temporary_file`([suffix])	Get a temporary filename in the directory.

Attributes

path

Real path to the directory.

classmethod cast(directory, create=True)#

Try to cast an object to a directory.

Ensure that a str or Directory is a Directory. No action is taken if the object is already a Directory. Otherwise, a new one is constructed.

Parameters:

directory (str or Directory) – Object to ensure is a directory
create (bool) – If True, ensure the directory is created on the filesystem.

Returns:

The cast object.

Return type:

Directory

clear_contents()#

Clear the contents of a directory.

This method removes all the contents of a directory (files and directories), so it should be used carefully!

copy_contents(dest)#

Copy the contents of the directory.

Parameters:: dest (Directory or str) – Destination directory.

directory(name, create=True)#

Get a child directory.

This method is convenient for abstracting references to child directories.

Parameters:

name (str) – Name of the directory.
create (bool) – If True, ensure the directory is created on the filesystem.

Returns:

A new directory relative to this one.

Return type:

Directory

Examples

Making nested directories foo/bar:

foo = Directory('foo')
bar = foo.directory('bar')

file(name)#

Get the absolute path to a file in the directory.

This method is convenient for abstracting references to a file in the directory.

Parameters:: name (str) – Name of the file.
Returns:: The absolute path to the file name.
Return type:: str

Examples

Opening a file by absolute path:

d = Directory('foo')
f = open(d.file('bar.txt'))

is_empty()#

Check if the directory is empty.

Returns:: True if the directory is empty.
Return type:: bool

move_contents(dest)#

Move the contents of the directory.

Parameters:: dest (Directory or str) – Destination directory.
Raises:: OSError – If the destination exists and does not match the type of the source.

property path#

Real path to the directory.

Type:: str

temporary_file(suffix=None)#

Get a temporary filename in the directory.

This method generates a random filename using uuid.uuid4(). Unlike a Python temporary file, this file is not automatically created or destroyed. That responsibility is delegated to the caller.

Parameters:: suffix (str) – If specified, the suffix to add to the filename. If None (default), no suffix is added.
Returns:: The absolute path to the temporary file.
Return type:: str