airfs API

This section describes the airfs Python package API.

Python “Remote File Systems” library

Copyright 2020 J.Goutin Copyright 2018-2019 Accelize

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

airfs.copy(src, dst)

Copies a source file to a destination file or directory.

Equivalent to “shutil.copy”.

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

Parameters:
  • src (path-like object or file-like object) – Source file.
  • dst (path-like object or file-like object) – Destination file or directory.
Raises:

IOError – Destination directory not found.

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

Copies a source file to a destination file.

Equivalent to “shutil.copyfile”.

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

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. Not supported on cloud storage objects.
Raises:

IOError – Destination directory not found.

airfs.exists(path)

Return True if path refers to an existing path.

Equivalent to “os.path.exists”.

Parameters:path (path-like object) – Path or URL.
Returns:True if path exists.
Return type:bool
airfs.getctime(path)

Return the creation time of path.

Equivalent to “os.path.getctime”.

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.

Equivalent to “os.path.getmtime”.

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 path.

Equivalent to “os.path.getsize”.

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 path is an absolute pathname.

Equivalent to “os.path.isabs”.

Parameters:path (path-like object) – Path or URL.
Returns:True if path is absolute.
Return type:bool
airfs.isdir(path)

Return True if path is an existing directory.

Equivalent to “os.path.isdir”.

Parameters:path (path-like object) – Path or URL.
Returns:True if directory exists.
Return type:bool
airfs.isfile(path)

Return True if path is an existing regular file.

Equivalent to “os.path.isfile”.

Parameters:path (path-like object) – Path or URL.
Returns:True if file exists.
Return type:bool

Return True if path is an existing symlink.

Equivalent to “os.path.islink”.

Parameters:path (path-like object) – Path or URL.
Returns:True if symlink.
Return type:bool
airfs.ismount(path)

Return True if pathname path is a mount point.

Equivalent to “os.path.ismount”.

Parameters:path (path-like object) – Path or URL.
Returns:True if path is a mount point.
Return type:bool
airfs.listdir(path='.')

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

Equivalent to “os.listdir”.

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 cloud object, may return extra storage specific attributes in “os.stat_result”.

Parameters:
  • path (path-like object) – Path or URL.
  • dir_fd – directory descriptors; see the os.rmdir() description for how it is interpreted. Not supported on cloud 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”.

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 cloud storage objects.
  • exist_ok (bool) – Don’t raises 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 mode.

Equivalent to “os.mkdir”.

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 cloud storage objects.
  • dir_fd – directory descriptors; see the os.remove() description for how it is interpreted. Not supported on cloud storage objects.
Raises:
  • FileExistsError – Directory already exists.
  • FileNotFoundError – Parent directory not exists.
airfs.mount(storage=None, name='', storage_parameters=None, unsecure=None, extra_root=None)

Mount a new storage.

Parameters:
  • storage (str) – Storage name.
  • name (str) – File URL. If storage is not specified, URL scheme will be used as storage value.
  • storage_parameters (dict) – Storage configuration parameters. Generally, client configuration and credentials.
  • unsecure (bool) – If True, disables TLS/SSL to improves transfer performance. But makes connection unsecure. Default to False.
  • extra_root (str) – Extra root that can be used in replacement of root in path. This can be used to provides support for shorter URLS. Example: with root “https://www.mycloud.com/user” and extra_root “mycloud://” it is possible to access object using “mycloud://container/object” instead of “https://www.mycloud.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, 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.

Parameters:
  • file (path-like object or file-like object) – File path, object URL or opened file-like object.
  • 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 kind 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.
  • storage (str) – Storage name.
  • storage_parameters (dict) – Storage configuration parameters. Generally, client configuration and credentials.
  • unsecure (bool) – If True, disables TLS/SSL to improves transfer performance. But makes connection unsecure. Default to False.
  • kwargs – Other arguments to pass to opened object. Note that theses arguments may not be compatible with all kind of file 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.
airfs.relpath(path, start=None)

Return a relative file path to 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 storage objects path. The ending slash is required on some storage to signify that target is a directory.

Equivalent to “os.path.relpath”.

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”.

Parameters:
  • path (path-like object) – Path or URL.
  • dir_fd – directory descriptors; see the os.remove() description for how it is interpreted. Not supported on cloud storage objects.
airfs.rmdir(path, dir_fd=None)

Remove a directory.

Equivalent to “os.rmdir”.

Parameters:
  • path (path-like object) – Path or URL.
  • dir_fd – directory descriptors; see the os.rmdir() description for how it is interpreted. Not supported on cloud storage objects.
airfs.samefile(path1, path2)

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

Equivalent to “os.path.samefile”.

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='.')

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”.

Parameters:path (path-like object) – Path or URL. If 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.splitdrive(path)

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”.

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 cloud object, may return extra storage specific attributes in “os.stat_result”.

Parameters:
  • path (path-like object) – Path or URL.
  • dir_fd – directory descriptors; see the os.rmdir() description for how it is interpreted. Not supported on cloud storage objects.
  • follow_symlinks (bool) – Follow symlinks. Not supported on cloud storage objects.
Returns:

stat result.

Return type:

os.stat_result

Remove a file.

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

Parameters:
  • path (path-like object) – Path or URL.
  • dir_fd – directory descriptors; see the os.remove() description for how it is interpreted. Not supported on cloud storage objects.