3.3. Namespaces¶

3.3.1. Introduction¶

Namespaces are an abstraction over firlesystem and other hirarchical constructs which have a notion of a :class:`saga.namespace.Directory and of `:class:`saga.namespace.Entry`s which exist in those directories. The API provides a number of operations, which all behave similar to the common unix command line tools (cp, ls, rm etc).

Example:

# get a directory handle
dir = radical.saga.namespace.Directory("sftp://localhost/tmp/")

# create a subdir
dir.make_dir ("data/")

# list contents of the directory
entries = dir.list ()

# copy *.dat files into the subdir
for e in entries :
    if re.match ('^.*\.dat$', f) :
        dir.copy (e, "sftp://localhost/tmp/data/")

The above example covers most of the semantics of the namespace package – additional capabilities, such get_size() or move(), can be found in the individual class documentations.

3.3.2. Flags¶

The following constants are defined as valid flags for file and directory methods:

radical.saga.namespace.OVERWRITE¶

radical.saga.namespace.RECURSIVE¶

radical.saga.namespace.CREATE¶

radical.saga.namespace.CREATE_PARENTS¶

radical.saga.namespace.LOCK¶

radical.saga.namespace.EXCLUSIVE¶

radical.saga.namespace.DEREFERENCE¶

3.3.3. Entry – `radical.saga.namespace.Entry`¶

class radical.saga.namespace.Entry(url=None, flags=None, session=None, _adaptor=None, _adaptor_state={}, _ttype=None)[source]¶

Bases: Base, Async

Represents a SAGA namespace entry as defined in GFD.90

The saga.namespace.Entry class represents, as the name indicates, an entry in some (local or remote) namespace. That class offers a number of operations on that entry, such as copy, move and remove:

# get an entry handle
entry = saga.namespace.Entry ("sftp://localhost/tmp/data/data.bin")

# copy the entry
entry.copy ("sftp://localhost/tmp/data/data.bak")

# move the entry
entry.move ("sftp://localhost/tmp/data/data.new")

__init__(url=None, flags=None, session=None, _adaptor=None, _adaptor_state={}, _ttype=None)[source]¶

Parameters:: url (saga.Url) – Url of the (remote) entry

flags: flags enum session: saga.Session ret: obj

Construct a new entry object

The specified entry is expected to exist – otherwise a DoesNotExist exception is raised. Also, the URL must point to an entry (not to a directory), otherwise a BadParameter exception is raised.

Example:

# get an entry handle
entry = saga.namespace.Entry("sftp://localhost/tmp/data/data.bin")

# print the entry's url
print(entry.get_url ())

close(timeout=None, ttype=None)[source]¶: timeout: float ttype: saga.task.type enum ret: None / saga.Task

copy(tgt, flags=0, ttype=None)[source]¶

tgt: saga.Url flags: enum flags ttype: saga.task.type enum ret: None / saga.Task

Copy the entry to another location

Parameters:

target – Url of the copy target.
flags – Flags to use for the operation.

The entry is copied to the given target location. The target URL must be an absolute path, and can be a target entry name or target directory name. If the target entry exists, it is overwritten:

# copy an entry
entry = saga.namespace.Entry("sftp://localhost/tmp/data/data.bin")
entry.copy ("sftp://localhost/tmp/data/data.bak")

property cwd¶: ttype: saga.task.type enum ret: string / saga.Task

get_cwd(ttype=None)[source]¶: ttype: saga.task.type enum ret: string / saga.Task

get_name(ttype=None)[source]¶: ttype: saga.task.type enum ret: string / saga.Task

get_url(ttype=None)[source]¶

ttype: saga.task.type enum ret: saga.Url / saga.Task

Return the complete url pointing to the entry.

The call will return the complete url pointing to this entry as a saga.Url object:

# print URL of an entry
entry = saga.namespace.Entry("sftp://localhost/etc/passwd")
print(entry.get_url())

is_dir(ttype=None)[source]¶

ttype: saga.task.type enum ret: bool / saga.Task

Returns True if path is a directory, False otherwise.

Example:

# inspect an entry
dir  = saga.namespace.Directory("sftp://localhost/tmp/")
if dir.is_dir ('data'):
    # do something

is_entry(ttype=None)[source]¶: ttype: saga.task.type enum ret: bool / saga.Task

is_link(ttype=None)[source]¶: tgt: saga.Url / None ttype: saga.task.type enum ret: bool / saga.Task

link(tgt, flags=0, ttype=None)[source]¶: tgt: saga.Url flags: enum flags ttype: saga.task.type enum ret: None / saga.Task

move(tgt, flags=0, ttype=None)[source]¶

Parameters:

target – Url of the move target.
flags – Flags to use for the operation.

ttype: saga.task.type enum ret: None / saga.Task

Move the entry to another location

The entry is copied to the given target location. The target URL must be an absolute path, and can be a target entry name or target directory name. If the target entry exists, it is overwritten:

# copy an entry
entry = rs.namespace.Directory("sftp://localhost/tmp/data/data.bin")
entry.move ("sftp://localhost/tmp/data/data.bak")

property name¶: ttype: saga.task.type enum ret: string / saga.Task

read_link(ttype=None)[source]¶: tgt: saga.Url / None ttype: saga.task.type enum ret: saga.Url / saga.Task

remove(flags=0, ttype=None)[source]¶

Parameters:: flags – Flags to use for the operation.

ttype: saga.task.type enum ret: None / saga.Task

Reove the entry.

The entry is removed, and this object instance is then invalid for further operations.

# remove an entry entry = rs.namespace.Directory(“sftp://localhost/tmp/data/data.bin”) entry.remove ()

property url¶

ttype: saga.task.type enum ret: saga.Url / saga.Task

Return the complete url pointing to the entry.

The call will return the complete url pointing to this entry as a saga.Url object:

# print URL of an entry
entry = saga.namespace.Entry("sftp://localhost/etc/passwd")
print(entry.get_url())

3.3.4. Directory – `radical.saga.namespace.Directory`¶

class radical.saga.namespace.Directory(url=None, flags=None, session=None, _adaptor=None, _adaptor_state={}, _ttype=None)[source]¶

Bases: Entry

Represents a SAGA directory as defined in GFD.90

The saga.namespace.Directory class represents, as the name indicates, a directory on some (local or remote) namespace. That class offers a number of operations on that directory, such as listing its contents, copying entries, or creating subdirectories:

# get a directory handle
dir = saga.namespace.Directory("sftp://localhost/tmp/")

# create a subdir
dir.make_dir ("data/")

# list contents of the directory
entries = dir.list ()

# copy *.dat entries into the subdir
for f in entries :
    if f ^ '^.*\.dat$' :
        dir.copy (f, "sftp://localhost/tmp/data/")

3.3. Implementation note:¶

The SAGA API Specification (GFD.90) prescribes method overloading on method signatures, but that is not supported by Python (Python only does method overwriting). So we implement one generic method version here, and do the case switching based on the provided parameter set.

__init__(url=None, flags=None, session=None, _adaptor=None, _adaptor_state={}, _ttype=None)[source]¶

Parameters:: url (saga.Url) – Url of the (remote) entry system directory.

flags: flags enum session: saga.Session ret: obj

Construct a new directory object

The specified directory is expected to exist – otherwise a DoesNotExist exception is raised. Also, the URL must point to a directory (not to an entry), otherwise a BadParameter exception is raised.

Example:

# open some directory
dir = saga.namespace.Directory("sftp://localhost/tmp/")

# and list its contents
entries = dir.list ()

change_dir(url, flags=0, ttype=None)[source]¶: url: saga.Url flags: flags enum ttype: saga.task.type enum ret: None / saga.Task

copy(url_1, url_2=None, flags=0, ttype=None)[source]¶

Parameters:

src – path of the entry to copy
tgt – absolute URL of target name or directory

url_1: saga.Url url_2: saga.Url / None flags: flags enum / None ttype: saga.task.type enum / None ret: None / saga.Task

Copy an entry from source to target

The source is copied to the given target directory. The path of the source can be relative:

# copy an entry
dir = saga.namespace.Directory("sftp://localhost/tmp/")
dir.copy ("./data.bin", "sftp://localhost/tmp/data/")

exists(path, ttype=None)[source]¶

Parameters:: path – path of the entry to check

ttype: saga.task.type enum ret: bool / saga.Task

Returns True if path exists, False otherwise.

Example:

# inspect an entry
dir  = saga.namespace.Directory("sftp://localhost/tmp/")
if dir.exists ('data'):
    # do something

find(pattern, flags=2, ttype=None)[source]¶: pattern: string flags: flags enum ttype: saga.task.type enum ret: list [saga.Url] / saga.Task

get_entry(num, ttype=None)[source]¶: num: int ttype: saga.task.type enum ret: saga.Url / saga.Task

get_num_entries(ttype=None)[source]¶: ttype: saga.task.type enum ret: int / saga.Task

is_dir(tgt=None, ttype=None)[source]¶

tgt: saga.Url / None ttype: saga.task.type enum ret: bool / saga.Task

Returns True if path is a directory, False otherwise.

Example:

# inspect an entry
dir  = saga.namespace.Directory("sftp://localhost/tmp/")
if dir.is_dir ('data'):
    # do something

is_entry(tgt=None, ttype=None)[source]¶: tgt: saga.Url / None ttype: saga.task.type enum ret: bool / saga.Task

is_link(tgt=None, ttype=None)[source]¶: tgt: saga.Url / None ttype: saga.task.type enum ret: bool / saga.Task

link(url_1, url_2=None, flags=0, ttype=None)[source]¶: src: saga.Url tgt: saga.Url flags: flags enum ttype: saga.task.type enum ret: None / saga.Task

list(pattern=None, flags=0, ttype=None)[source]¶

Parameters:: pattern – Entry name pattern (like POSIX ‘ls’, e.g. ‘*.txt’)

flags: flags enum ttype: saga.task.type enum ret: list [saga.Url] / saga.Task

List the directory’s content

The call will return a list of entries and subdirectories within the directory:

# list contents of the directory
for f in dir.list() :
    print(f)

make_dir(tgt, flags=0, ttype=None)[source]¶

Parameters:

tgt – name/path of the new directory
flags – directory creation flags

ttype: saga.task.type enum ret: None / saga.Task

Create a new directoy

The call creates a directory at the given location.

Example:

# create a subdir 'data' in /tmp
dir = saga.namespace.Directory("sftp://localhost/tmp/")
dir.make_dir ('data/')

move(url_1, url_2=None, flags=0, ttype=None)[source]¶

Parameters:

src – path of the entry to copy
tgt – absolute URL of target directory

flags: flags enum ttype: saga.task.type enum ret: None / saga.Task

Move an entry from source to target

The source is moved to the given target directory. The path of the source can be relative:

# copy an entry
dir = saga.namespace.Directory("sftp://localhost/tmp/")
dir.move ("./data.bin", "sftp://localhost/tmp/data/")

open(name, flags=None, ttype=None)[source]¶: name: saga.Url flags: saga.namespace.flags enum ttype: saga.task.type enum ret: saga.namespace.Entry / saga.Task

open_dir(path, flags=None, ttype=None)[source]¶

Parameters:

path – name/path of the directory to open
flags – directory creation flags

ttype: saga.task.type enum ret: saga.namespace.Directory / saga.Task

Open and return a new directoy

The call opens and returns a directory at the given location.

Example:

# create a subdir 'data' in /tmp
dir = saga.namespace.Directory("sftp://localhost/tmp/")
data = dir.open_dir ('data/', saga.namespace.Create)

read_link(tgt=None, ttype=None)[source]¶: tgt: saga.Url / None ttype: saga.task.type enum ret: saga.Url / saga.Task

remove(tgt=None, flags=0, ttype=None)[source]¶: tgt: saga.Url flags: flags enum ttype: saga.task.type enum ret: None / saga.Task

3.3. Namespaces¶

3.3.1. Introduction¶

3.3.2. Flags¶

3.3.3. Entry – `radical.saga.namespace.Entry`¶

3.3.4. Directory – `radical.saga.namespace.Directory`¶

3.3. Implementation note:¶

Table of Contents

Previous topic

Next topic

This Page

3.3. Namespaces¶

3.3.1. Introduction¶

3.3.2. Flags¶

3.3.3. Entry – radical.saga.namespace.Entry¶

3.3.4. Directory – radical.saga.namespace.Directory¶

3.3. Implementation note:¶

3.3.3. Entry – `radical.saga.namespace.Entry`¶

3.3.4. Directory – `radical.saga.namespace.Directory`¶