FTP Filesystem

Manage filesystems on remote FTP servers.

class fs.ftpfs.FTPFS(host, user='anonymous', passwd='', acct='', timeout=10, port=21, proxy=None, tls=False)

A FTP (File Transport Protocol) Filesystem.

Optionally, the connection can be made securely via TLS. This is known as FTPS, or FTP Secure. TLS will be enabled when using the ftps:// protocol, or when setting the tls argument to True in the constructor.

Examples

Create with the constructor:

>>> from fs.ftpfs import FTPFS
>>> ftp_fs = FTPFS("demo.wftpserver.com")

Or via an FS URL:

>>> ftp_fs = fs.open_fs('ftp://test.rebex.net')

Or via an FS URL, using TLS:

>>> ftp_fs = fs.open_fs('ftps://demo.wftpserver.com')

You can also use a non-anonymous username, and optionally a password, even within a FS URL:

>>> ftp_fs = FTPFS("test.rebex.net", user="demo", passwd="password")
>>> ftp_fs = fs.open_fs('ftp://demo:password@test.rebex.net')

Connecting via a proxy is supported. If using a FS URL, the proxy URL will need to be added as a URL parameter:

>>> ftp_fs = FTPFS("ftp.ebi.ac.uk", proxy="test.rebex.net")
>>> ftp_fs = fs.open_fs('ftp://ftp.ebi.ac.uk/?proxy=test.rebex.net')

__init__(host, user='anonymous', passwd='', acct='', timeout=10, port=21, proxy=None, tls=False)

Create a new FTPFS instance.

Parameters:

• host (str) – A FTP host, e.g. 'ftp.mirror.nl'.
• user (str) – A username (default is 'anonymous').
• passwd (str) – Password for the server, or None for anon.
• acct (str) – FTP account.
• timeout (int) – Timeout for contacting server (in seconds, defaults to 10).
• port (int) – FTP port number (default 21).
• proxy (str, optional) – An FTP proxy, or None (default) for no proxy.
• tls (bool) – Attempt to use FTP over TLS (FTPS) (default: False)

close()

Close the filesystem and release any resources.

It is important to call this method when you have finished working with the filesystem. Some filesystems may not finalize changes until they are closed (archives for example). You may call this method explicitly (it is safe to call close multiple times), or you can use the filesystem as a context manager to automatically close.

Example

>>> with OSFS('~/Desktop') as desktop_fs:
...    desktop_fs.writetext(
...        'note.txt',
...        "Don't forget to tape Game of Thrones"
...    )

If you attempt to use a filesystem that has been closed, a FilesystemClosed exception will be thrown.

create(path, wipe=False)

Create an empty file.

The default behavior is to create a new file if one doesn’t already exist. If wipe is True, any existing file will be truncated.

Parameters:

• path (str) – Path to a new file in the filesystem.
• wipe (bool) – If True, truncate any existing file to 0 bytes (defaults to False).

Returns:

True if a new file had to be created.

Return type:

bool

features

Features of the remote FTP server.

Type:dict

ftp

the underlying FTP client.

Type:FTP

ftp_url

Get the FTP url this filesystem will open.

getinfo(path, namespaces=None)

Get information about a resource on a filesystem.

Parameters:

• path (str) – A path to a resource on the filesystem.
• namespaces (list, optional) – Info namespaces to query. The "basic" namespace is alway included in the returned info, whatever the value of namespaces may be.

Returns:

resource information object.

Return type:

Info

Raises:

fs.errors.ResourceNotFound – If path does not exist.

For more information regarding resource information, see Resource Info.

getmeta(namespace='standard')

Get meta information regarding a filesystem.

Parameters:namespace (str) – The meta namespace (defaults to "standard"). Returns:the meta information. Return type:dict

Meta information is associated with a namespace which may be specified with the namespace parameter. The default namespace, "standard", contains common information regarding the filesystem’s capabilities. Some filesystems may provide other namespaces which expose less common or implementation specific information. If a requested namespace is not supported by a filesystem, then an empty dictionary will be returned.

The "standard" namespace supports the following keys:

key	Description
case_insensitive	True if this filesystem is case insensitive.
invalid_path_chars	A string containing the characters that may not be used on this filesystem.
max_path_length	Maximum number of characters permitted in a path, or None for no limit.
max_sys_path_length	Maximum number of characters permitted in a sys path, or None for no limit.
network	True if this filesystem requires a network.
read_only	True if this filesystem is read only.
supports_rename	True if this filesystem supports an os.rename operation.

Most builtin filesystems will provide all these keys, and third- party filesystems should do so whenever possible, but a key may not be present if there is no way to know the value.

Note

Meta information is constant for the lifetime of the filesystem, and may be cached.

getmodified(path)

Get the timestamp of the last modifying access of a resource.

Parameters:path (str) – A path to a resource. Returns:The timestamp of the last modification. Return type:datetime

The modified timestamp of a file is the point in time that the file was last changed. Depending on the file system, it might only have limited accuracy.

geturl(path, purpose='download')

Get FTP url for resource.

listdir(path)

Get a list of the resource names in a directory.

This method will return a list of the resources in a directory. A resource is a file, directory, or one of the other types defined in ResourceType.

Parameters:

path (str) – A path to a directory on the filesystem

Returns:

list of names, relative to path.

Return type:

list

Raises:

• fs.errors.DirectoryExpected – If path is not a directory.
• fs.errors.ResourceNotFound – If path does not exist.

makedir(path, permissions=None, recreate=False)

Make a directory.

Parameters:

• path (str) – Path to directory from root.
• permissions (Permissions, optional) – a Permissions instance, or None to use default.
• recreate (bool) – Set to True to avoid raising an error if the directory already exists (defaults to False).

Returns:

a filesystem whose root is the new directory.

Return type:

SubFS

Raises:

• fs.errors.DirectoryExists – If the path already exists.
• fs.errors.ResourceNotFound – If the path is not found.

openbin(path, mode='r', buffering=-1, **options)

Open a binary file-like object.

Parameters:

• path (str) – A path on the filesystem.
• mode (str) – Mode to open file (must be a valid non-text mode, defaults to r). Since this method only opens binary files, the b in the mode string is implied.
• buffering (int) – Buffering policy (-1 to use default buffering, 0 to disable buffering, or any positive integer to indicate a buffer size).
• **options – keyword arguments for any additional information required by the filesystem (if any).

Returns:

a file-like object.

Return type:

io.IOBase

Raises:

• fs.errors.FileExpected – If path exists and is not a file.
• fs.errors.FileExists – If the path exists, and exclusive mode is specified (x in the mode).
• fs.errors.ResourceNotFound – If path does not exist and mode does not imply creating the file, or if any ancestor of path does not exist.

readbytes(path)

Get the contents of a file as bytes.

Parameters:

path (str) – A path to a readable file on the filesystem.

Returns:

the file contents.

Return type:

bytes

Raises:

• fs.errors.FileExpected – if path exists but is not a file.
• fs.errors.ResourceNotFound – if path does not exist.

remove(path)

Remove a file from the filesystem.

Parameters:

path (str) – Path of the file to remove.

Raises:

• fs.errors.FileExpected – If the path is a directory.
• fs.errors.ResourceNotFound – If the path does not exist.

removedir(path)

Remove a directory from the filesystem.

Parameters:

path (str) – Path of the directory to remove.

Raises:

• fs.errors.DirectoryNotEmpty – If the directory is not empty ( see removetree for a way to remove the directory contents).
• fs.errors.DirectoryExpected – If the path does not refer to a directory.
• fs.errors.ResourceNotFound – If no resource exists at the given path.
• fs.errors.RemoveRootError – If an attempt is made to remove the root directory (i.e. '/')

scandir(path, namespaces=None, page=None)

Get an iterator of resource info.

Parameters:

• path (str) – A path to a directory on the filesystem.
• namespaces (list, optional) – A list of namespaces to include in the resource information, e.g. ['basic', 'access'].
• page (tuple, optional) – May be a tuple of (<start>, <end>) indexes to return an iterator of a subset of the resource info, or None to iterate over the entire directory. Paging a directory scan may be necessary for very large directories.

Returns:

an iterator of Info objects.

Return type:

Iterator

Raises:

• fs.errors.DirectoryExpected – If path is not a directory.
• fs.errors.ResourceNotFound – If path does not exist.

setinfo(path, info)

Set info on a resource.

This method is the complement to getinfo and is used to set info values on a resource.

Parameters:

• path (str) – Path to a resource on the filesystem.
• info (dict) – Dictionary of resource info.

Raises:

fs.errors.ResourceNotFound – If path does not exist on the filesystem

The info dict should be in the same format as the raw info returned by getinfo(file).raw.

Example

>>> details_info = {"details": {
...     "modified": time.time()
... }}
>>> my_fs.setinfo('file.txt', details_info)

supports_mdtm

whether the server supports the MDTM feature.

Type:bool

supports_mlst

whether the server supports MLST feature.

Type:bool

upload(path, file, chunk_size=None, **options)

Set a file to the contents of a binary file object.

This method copies bytes from an open binary file to a file on the filesystem. If the destination exists, it will first be truncated.

Parameters:

• path (str) – A path on the filesystem.
• file (io.IOBase) – a file object open for reading in binary mode.
• chunk_size (int, optional) – Number of bytes to read at a time, if a simple copy is used, or None to use sensible default.
• **options – Implementation specific options required to open the source file.

Raises:

fs.errors.ResourceNotFound – If a parent directory of path does not exist.

Note that the file object file will not be closed by this method. Take care to close it after this method completes (ideally with a context manager).

Example

>>> with open('~/movies/starwars.mov', 'rb') as read_file:
...     my_fs.upload('starwars.mov', read_file)

writebytes(path, contents)

Copy binary data to a file.

Parameters:

• path (str) – Destination path on the filesystem.
• contents (bytes) – Data to be written.

Raises:

TypeError – if contents is not bytes.