Archives API Reference

Module imagedata.archives.abstractarchive

Abstract class for archives.

Defines generic functions.

class imagedata.archives.abstractarchive.AbstractArchive(name, description, authors, version, url, _mimetypes)[source]

Abstract base class definition for imagedata archive plugins.

Standard plugins provide support for local filesystem and zip archives.

The archive plugins access actual data through a Transport plugin.

Plugins must be a subclass of AbstractPlugin and must define the attributes set in __init__() and the following methods:

__init__() method use_query() method getnames() method basename() method open() method getmembers() method to_localfile() method add_localfile() method writedata() method is_file() method

abstract add_localfile(local_file, filename)[source]

Add a local file to the archive.

Parameters:

local_file – named local file
filename – filename in the archive

property authors

Plugin authors

Multi-line string naming the author(s) of the plugin.

property base: str: Archive base.

abstract basename(filehandle: Member)[source]

Basename of file.

Examples

if archive.basename(filehandle) == “DICOMDIR”:

Parameters:: filehandle – reference to member object
Returns:: str
Return type:: Basename of file

abstract close()[source]: Close archive.

abstract construct_filename(tag: Tuple | None, query: str = None) → str[source]

Construct a filename with given scheme.

Parameters:

tag – a tuple giving the present position of the filename (tuple).
query – from url query (str).

Returns:

A filename compatible with the given archive (str).

property description

Plugin description

Single line string describing the image format.

abstract exists(member)[source]

Determine whether the named path exists.

Parameters:: member – member name.
Returns:: whether member exists (bool)

abstract getmembers(files=None)[source]

Get the members of the archive.

Parameters:

files – List of filename matches.

Returns:

The members of the archive as a list of Filehandles.: The list has the same order as the members of the archive.

abstract getnames(files=None)[source]

Get name list of the members.

Parameters:

files – List or single str of filename matches.

Returns:

The members as a list of their names.: It has the same order as the members of the archive.

abstract is_file(member)[source]

Determine whether the named file is a single file.

Parameters:: member – file member.
Returns:: whether member is a single file (bool)

property mimetypes

MIME types supported by this plugin.

List of strings.

property name

Plugin name

Single word string describing the image format. Typical names: dicom, nifti, itk.

abstract new_local_file(filename: str) → Member[source]

Create new local file.

Parameters:: filename – Preferred filename (str)
Returns:: member object (Member). The local_file property has the local filename.

abstract open(member: Member, mode: str = 'rb')[source]

Open file.

Parameters:

member – Handle to file.
mode – Open mode.

Returns:

An IO object for the member.

property path: str

Archive path.

Typically, this will be a combination of archive root and base.

property root: str: Archive root name.

set_member_naming_scheme(fallback: str, level: tuple = None, default_extension: str = None, extensions: List[str] = None)[source]

Set member naming scheme.

Parameters:

fallback – default filename (str).
level –
default_extension – default extension (str).
extensions –

abstract to_localfile(member)[source]

Access a member object through a local file.

Parameters:: member – handle to member file.
Returns:: filename to file guaranteed to be local.

property transport: Underlying transport plugin

property url

Plugin URL

URL string to the site of the plugin or the author(s).

abstract use_query()[source]: Does the plugin need the ?query part of the url?

property version

Plugin version

String giving the plugin version. Version scheme: 1.0.0

abstract writedata(filename, data)[source]

Write data to a named file in the archive.

Parameters:

filename – named file in the archive
data – data to write

class imagedata.archives.abstractarchive.Member(filename, info=None, fh=None, local_file=None)[source]: Class definition for filehandle in imagedata archives.

exception imagedata.archives.abstractarchive.NoOtherInstance[source]

exception imagedata.archives.abstractarchive.WriteMultipleArchives[source]

Module imagedata.archives.filesystemarchive

Read/Write local files

class imagedata.archives.filesystemarchive.FilesystemArchive(transport=None, url=None, mode='r', read_directory_only=True, opts=None)[source]

Read/write local files.

Parameters:

transport – a Transport instance
url (str) – URL to filesystem
mode (str) – filesystem access mode
read_directory_only (bool) – Whether url should refer to a directory.
opts (dict) – Options

Returns:

FilesystemArchive instance

add_localfile(local_file, filename)[source]

Add a local file to the archive.

Parameters:

local_file – named local file
filename – filename in the archive

Raises:

imagedata.archives.FileAlreadyExistsError – When file already exists.

property base: str: Archive base name.

basename(filehandle: Member)[source]

Basename of file.

Examples

if archive.basename(filehandle) == “DICOMDIR”:

Parameters:: filehandle – reference to member object
Returns:: str
Return type:: Basename of file

close()[source]: Close function.

construct_filename(tag: Tuple | None, query: str = None) → str[source]

Construct a filename with given scheme.

Parameters:

tag – a tuple giving the present position of the filename (tuple).
query – from url query (str).

Returns:

A filename compatible with the given archive (str).

exists(member)[source]

Determine whether the named path exists.

Parameters:: member – member name.
Returns:: whether member exists (bool)

getmembers(files=None)[source]

Get the members of the archive.

Parameters:

files – List of filename matches

Returns:

The members of the archive as a list of member objects.: The list has the same order as the members in the archive.

Raises:

FileNotFoundError – When no matching file is found.

getnames(files=None)[source]

Get name list of the members.

Parameters:

files – List or single str of filename matches.

Returns:

The members as a list of their names.: It has the same order as the members of the archive.

Raises:

FileNotFoundError – when no matching file is found.

is_file(member)[source]

Determine whether the named file is a single file.

Parameters:: member – file member
Returns:: whether named file is a single file (bool)

new_local_file(filename: str) → Member[source]

Create new local file.

Parameters:: filename – Preferred filename (str)
Returns:: member object (Member). The local_file property has the local filename.

open(member: Member, mode: str = 'rb')[source]

Open file.

Parameters:

member – Handle to file
mode – Open mode

Returns:

An IO object for the member

property path: str: Archive path.

property root: str: Archive root name.

to_localfile(member)[source]

Access a member object through a local file.

Parameters:: member – handle to member file.
Returns:: filename to file guaranteed to be local.

use_query()[source]: Does the plugin need the ?query part of the url?

writedata(filename, data)[source]

Write data to a named file in the archive.

Parameters:

filename – named file in the archive
data – data to write

Raises:

ReadOnlyError – when the archive is read-only.
WriteOnFile – when attempting to write a file to a file.

exception imagedata.archives.filesystemarchive.NoSuchFile[source]

exception imagedata.archives.filesystemarchive.ReadOnlyError[source]

exception imagedata.archives.filesystemarchive.WriteOnFile[source]

Module imagedata.archives.zipfilearchive

Read/Write files from a zipfile

class imagedata.archives.zipfilearchive.WriteFileIO(archive, member, local_file)[source]

Local object making sure the new file is written to zip archive before closing.

close()[source]: Close file, copy it to archive, then delete local file.

class imagedata.archives.zipfilearchive.ZipfileArchive(transport=None, url=None, mode='r', read_directory_only=False, opts=None)[source]

Read/write image files from a zipfile.

add_localfile(local_file, filename)[source]

Add a local file to the archive.

Parameters:

local_file – named local file
filename – filename in the archive

property base: str: Archive base name.

basename(filehandle: Member)[source]

Basename of file.

Examples

if archive.basename(filehandle) == “DICOMDIR”:

Parameters:: filehandle – reference to member object
Returns:: str
Return type:: Basename of file

close()[source]: Close zip file.

construct_filename(tag: Tuple | None, query: str = None) → str[source]

Construct a filename with given scheme.

Parameters:

tag – a tuple giving the present position of the filename (tuple).
query – from url query (str).

Returns:

A filename compatible with the given archive (str).

exists(member)[source]

Determine whether the named path exists.

Parameters:: member – member name.
Returns:: whether member exists (bool)

getmembers(files=None)[source]

Get the members of the archive.

Parameters:

files – List of filename matches

Returns:

The members of the archive as a list of Filehandles.: The list same order as the members in the archive.

getnames(files=None)[source]

Get name list of the members.

Parameters:

files – List or single str of filename matches

Returns:

The members as a list of their names.: It has the same order as the members of the archive.

Raises:

FileNotFoundError – When no matching file is found.

is_file(member)[source]

Determine whether the named file is a single file.

Parameters:: member – file member
Returns:: whether named file is a single file (bool)

new_local_file(filename: str) → Member[source]

Create new local file.

Parameters:: filename – Preferred filename (str)
Returns:: member object (Member). The local_file property has the local filename.

open(member: Member, mode: str = 'rb')[source]

Open file.

Extract the member object to local file space. This is necessary to allow the seek() operation on open files.

Parameters:

member (imagedata.archives.abstractarchive.Member) – Handle to file.
mode (str) – Open mode.

Returns:

An IO object for the member.

Raises:

FileNotFoundError – when file is not found.
PermissionError – When archive is read-only.

property path: str: Archive path.

property root: str: Archive root name.

to_localfile(member)[source]

Access a member object through a local file.

Parameters:: member – handle to member file.
Returns:: filename to file guaranteed to be local.
Raises:: FileNotFoundError – when file is not found.

use_query()[source]: Does the plugin need the ?query part of the url?

writedata(filename, data)[source]

Write data to a named file in the archive.

Parameters:

filename – named file in the archive
data – data to write