airfs API

This section describes the airfs Python package API.

Python “Remote File Systems” library.

exception airfs.AirfsException

airfs base exception.

New in version 1.0.0.

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception airfs.AirfsWarning

airfs base warning.

New in version 1.5.0.

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception airfs.MountException

airfs mount exception.

New in version 1.5.0.

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

airfs.copy(src, dst, *, follow_symlinks=True)

Copy a source file to a destination file or directory.

Equivalent to “shutil.copy”.

Source and destination can also be binary opened file-like objects.

New in version 1.0.0.

Parameters:

  • src (path-like object or file-like object) – Source file.

  • dst (path-like object or file-like object) – Destination file or directory.

  • follow_symlinks (bool) – If True, follow symlinks.

Raises:

FileNotFoundError – Destination directory not found.

airfs.copyfile(src, dst, *, follow_symlinks=True)

Copy a source file to a destination file.

Equivalent to “shutil.copyfile”.

Source and destination can also be binary opened file-like objects.

New in version 1.2.0.

Parameters:

  • src (path-like object or file-like object) – Source file.

  • dst (path-like object or file-like object) – Destination file.

  • follow_symlinks (bool) – Follow symlinks.

Raises:

FileNotFoundError – Destination directory not found.

airfs.exists(path)

Return True if the path refers to an existing path. Follow symlinks if any.

Equivalent to “os.path.exists”.

New in version 1.1.0.

Parameters:

path (path-like object) – Path or URL.

Returns:

True if the path exists.

Return type:

bool

airfs.getctime(path)

Return the creation time of the path object.

Equivalent to “os.path.getctime”.

New in version 1.2.0.

Parameters:

path (path-like object) – File path or URL.

Returns:

The number of seconds since the epoch (see the time module).

Return type:

float

Raises:

  • OSError – if the file does not exist or is inaccessible.

  • io.UnsupportedOperation – Information not available for this path.

airfs.getmtime(path)

Return the time of last access of path object.

Equivalent to “os.path.getmtime”.

New in version 1.0.0.

Parameters:

path (path-like object) – File path or URL.

Returns:

The number of seconds since the epoch (see the time module).

Return type:

float

Raises:

  • OSError – if the file does not exist or is inaccessible.

  • io.UnsupportedOperation – Information not available for this path.

airfs.getsize(path)

Return the size, in bytes, of the path object.

Equivalent to “os.path.getsize”.

New in version 1.0.0.

Parameters:

path (path-like object) – File path or URL.

Returns:

Size in bytes.

Return type:

int

Raises:

  • OSError – if the file does not exist or is inaccessible.

  • io.UnsupportedOperation – Information not available for this path.

airfs.isabs(path)

Return True if the path is an absolute pathname.

Equivalent to “os.path.isabs”.

New in version 1.1.0.

Parameters:

path (path-like object) – Path or URL.

Returns:

True if the path is absolute.

Return type:

bool

airfs.isdir(path)

Return True if the path is an existing directory.

Follow symlinks if any.

Equivalent to “os.path.isdir”.

New in version 1.1.0.

Parameters:

path (path-like object) – Path or URL.

Returns:

True if directory exists.

Return type:

bool

airfs.isfile(path)

Return True if the path is an existing regular file.

Follow symlinks if any.

Equivalent to “os.path.isfile”.

New in version 1.0.0.

Parameters:

path (path-like object) – Path or URL.

Returns:

True if file exists.

Return type:

bool

Return True if the path is an existing symlink.

Equivalent to “os.path.islink”.

New in version 1.2.0.

Parameters:

path (path-like object) – Path or URL.

Returns:

True if symlink.

Return type:

bool

airfs.ismount(path)

Return True if the pathname path is a mount point.

Equivalent to “os.path.ismount”.

New in version 1.1.0.

Parameters:

path (path-like object) – Path or URL.

Returns:

True if the path is a mount point.

Return type:

bool

airfs.lexists(path)

Return True if the path refers to an existing path. Does not follow symlinks.

Equivalent to “os.path.lexists”.

New in version 1.5.0.

Parameters:

path (path-like object) – Path or URL.

Returns:

True if the path exists.

Return type:

bool

airfs.listdir(path='.')

Return a list containing the names of the entries in the directory given by path.

Follow symlinks if any.

Equivalent to “os.listdir”.

New in version 1.2.0.

Parameters:

path (path-like object) – Path or URL.

Returns:

Entries names.

Return type:

list of str

airfs.lstat(path, *, dir_fd=None)

Get the status of a file or a file descriptor.

Perform the equivalent of a “lstat()” system call on the given path.

Equivalent to “os.lstat”.

On storage object, may return extra storage-specific attributes in “os.stat_result”.

New in version 1.2.0.

Parameters:

  • path (path-like object) – Path or URL.

  • dir_fd (int) – directory descriptors; see the os.rmdir() description for how it is interpreted. Not supported on storage objects.

Returns:

stat result.

Return type:

os.stat_result

airfs.makedirs(name, mode=511, exist_ok=False)

Super-mkdir; create a leaf directory and all intermediate ones.

Works like mkdir, except that any intermediate path segment (not just the rightmost) will be created if it does not exist.

Equivalent to “os.makedirs”.

New in version 1.1.0.

Parameters:

  • name (path-like object) – Path or URL.

  • mode (int) – The mode parameter is passed to os.mkdir(); see the os.mkdir() description for how it is interpreted. Not supported on storage objects.

  • exist_ok (bool) – Don’t raise error if target directory already exists.

Raises:

FileExistsError – if exist_ok is False and if the target directory already exists.

airfs.mkdir(path, mode=511, *, dir_fd=None)

Create a directory named path with numeric mode.

Equivalent to “os.mkdir”.

New in version 1.1.0.

Parameters:

  • path (path-like object) – Path or URL.

  • mode (int) – The mode parameter is passed to os.mkdir(); see the os.mkdir() description for how it is interpreted. Not supported on storage objects.

  • dir_fd (int) – directory descriptors; see the os.remove() description for how it is interpreted. Not supported on storage objects.

Raises:

  • FileExistsError – Directory already exists.

  • FileNotFoundError – Parent directory does not exist.

airfs.mount(storage=None, name='', storage_parameters=None, unsecure=None, extra_root=None)

Mount a new storage.

New in version 1.0.0.

Parameters:

  • storage (str) – Storage name.

  • name (str) – File URL. If storage is not specified, it will be inferred from this name.

  • storage_parameters (dict) – Storage configuration parameters. Generally, client configuration and credentials.

  • unsecure (bool) – If True, disables TLS/SSL to improve transfer performance. But makes connection unsecure. Default to False.

  • extra_root (str) – Extra root that can be used in replacement of root in the path. This can be used to provide support for shorter URLS. Example: with root “https://www.my_storage.com/user” and extra_root “mystorage://” it is possible to access an object using “mystorage://container/object” instead of “https://www.my_storage.com/user/container/object”.

Returns:

keys are mounted storage, values are dicts of storage information.

Return type:

dict

airfs.open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None, storage=None, storage_parameters=None, unsecure=None, **kwargs)

Open file and return a corresponding file object.

Equivalent to “io.open” or builtin “open”.

File can also be binary opened file-like object.

New in version 1.0.0.

Parameters:

  • file (path-like object or file-like object or int) – File path, object URL, opened file-like object, or file descriptor.

  • mode (str) – mode in which the file is opened (default to ‘rb’). see “io.open” for all possible modes. Note that all modes may not be supported by all kinds of file and storage.

  • buffering (int) – Set the buffering policy. -1 to use default behavior, 0 to switch buffering off, 1 to select line buffering (only usable in text mode), and an integer > 1 to indicate the size in bytes of a fixed-size chunk buffer. See “io.open” for more information.

  • encoding (str) – The name of the encoding used to decode or encode the file. This should only be used in text mode. See “io.open” for more information.

  • errors (str) – Specifies how encoding and decoding errors are to be handled. This should only be used in text mode. See “io.open” for more information.

  • newline (str) – Controls how universal newlines mode works. This should only be used in text mode. See “io.open” for more information.

  • closefd (bool) – If closefd is False and a file descriptor rather than a filename was given, the underlying file descriptor will be kept open when the file is closed. Must be True elsewhere (the default) otherwise an error will be raised.

  • opener – A callable used as custom opener. see the standard library “open()” documentation for more information. Not supported on storage objects.

  • storage (str) – Storage name.

  • storage_parameters (dict) – Storage configuration parameters. Generally, client configuration and credentials.

  • unsecure (bool) – If True, disables TLS/SSL to improve transfer performance. But makes connection unsecure. Default to False.

  • kwargs – Other arguments to pass to the opened object. Note that these arguments may not be compatible with all kinds of files and storage.

Returns:

opened file.

Return type:

file-like object

Raises:

  • OSError – If the file cannot be opened.

  • FileExistsError – File open in ‘x’ mode already exists.

Return a string representing the path to which the symbolic link points.

The result may be either an absolute or relative pathname; if it is relative, it may be converted to an absolute pathname using os.path.join(os.path.dirname(path), result).

If the path is a string object (directly or indirectly through a PathLike interface), the result will also be a string object, and the call may raise a UnicodeDecodeError. If the path is a bytes object (directly or indirectly), the result will be a bytes object.

Equivalent to “os.readlink”.

New in version 1.5.0.

Parameters:

  • path (path-like object) – Path or URL.

  • dir_fd (int) – directory descriptors; see the os.readlink() description for how it is interpreted. Not supported on storage objects.

airfs.realpath(path, *, strict=False)

Return the canonical path of the specified filename.

Eliminate any symbolic links encountered in the path (if they are supported by the operating system).

Equivalent to “os.path.realpath”.

New in version 1.5.0.

Parameters:

  • path (path-like object) – Path or URL.

  • strict (bool) – If a path doesn’t exist or a symlink loop is encountered, and strict is True, OSError is raised. If strict is False, the path is resolved as far as possible and any remainder is appended without checking whether it exists. Not supported on storage objects.

Returns:

Absolute path.

Return type:

str

airfs.relpath(path, start=None)

Return the relative path.

Return a relative file path to the path either from the current directory or from an optional start directory.

For storage objects, “path” and “start” are relative to storage root.

“/” are not stripped on a storage objects path. The ending slash is required on some storage to signify that the target is a directory.

Equivalent to “os.path.relpath”.

New in version 1.0.0.

Parameters:

  • path (path-like object) – Path or URL.

  • start (path-like object) – Relative from this optional directory. Default to “os.curdir” for local files.

Returns:

Relative path.

Return type:

str

airfs.remove(path, *, dir_fd=None)

Remove a file.

Equivalent to “os.remove” and “os.unlink”.

New in version 1.2.0.

Parameters:

  • path (path-like object) – Path or URL.

  • dir_fd (int) – directory descriptors; see the os.remove() description for how it is interpreted. Not supported on storage objects.

airfs.rmdir(path, *, dir_fd=None)

Remove a directory.

Equivalent to “os.rmdir”.

New in version 1.2.0.

Parameters:

  • path (path-like object) – Path or URL.

  • dir_fd (int) – directory descriptors; see the os.rmdir() description for how it is interpreted. Not supported on storage objects.

airfs.samefile(path1, path2)

Return True if both pathname arguments refer to the same file or directory.

Equivalent to “os.path.samefile”.

New in version 1.1.0.

Parameters:

  • path1 (path-like object) – Path or URL.

  • path2 (path-like object) – Path or URL.

Returns:

True if same file or directory.

Return type:

bool

airfs.scandir(path='.')

Iterate over a directory.

Return an iterator of os.DirEntry objects corresponding to the entries in the directory given by path. The entries are yielded in arbitrary order, and the special entries ‘.’ and ‘..’ are not included.

Equivalent to “os.scandir”.

New in version 1.2.0.

Parameters:

path (path-like object) – Path or URL. If the path is of type bytes (directly or indirectly through the PathLike interface), the type of the name and path attributes of each os.DirEntry will be bytes; in all other circumstances, they will be of type str.

Returns:

Entries information.

Return type:

Generator of os.DirEntry

airfs.shareable_url(path, expires_in=3600)

Get a shareable public URL for the specified path of an existing object.

Only available for some storage and not for local paths.

New in version 1.5.0.

Parameters:

  • path (str) – Path or URL.

  • expires_in (int) – Expiration in seconds. Default to 1 hour.

airfs.splitdrive(path)

Split the path to a drive tail pair.

Split the path into a pair (drive, tail) where drive is either a mount point or the empty string. On systems which do not use drive specifications, drive will always be the empty string.

In all cases, drive + tail will be the same as path.

Equivalent to “os.path.splitdrive”.

New in version 1.1.0.

Parameters:

path (path-like object) – Path or URL.

Returns:

drive, tail.

Return type:

tuple of str

airfs.stat(path, *, dir_fd=None, follow_symlinks=True)

Get the status of a file or a file descriptor.

Perform the equivalent of a “stat()” system call on the given path.

Equivalent to “os.stat”.

On storage object, may return extra storage-specific attributes in “os.stat_result”.

New in version 1.2.0.

Parameters:

  • path (path-like object) – Path or URL.

  • dir_fd (int) – directory descriptors; see the os.rmdir() description for how it is interpreted. Not supported on storage objects.

  • follow_symlinks (bool) – Follow symlinks.

Returns:

stat result.

Return type:

os.stat_result

Create a symbolic link pointing to src named dst.

Equivalent to “os.symlink”.

New in version 1.5.0.

Parameters:

  • src (path-like object) – Path or URL to the symbolic link.

  • dst (path-like object) – Path or URL to the target.

  • target_is_directory (bool) – On Windows, define if symlink represents either a file or a directory. Not supported on storage objects and non-Windows platforms.

  • dir_fd (int) – directory descriptors; see the os.symlink() description for how it is interpreted. Not supported on storage objects.

Remove a file.

Equivalent to “os.remove” and “os.unlink”.

New in version 1.2.0.

Parameters:

  • path (path-like object) – Path or URL.

  • dir_fd (int) – directory descriptors; see the os.remove() description for how it is interpreted. Not supported on storage objects.