FTP Filesystem

Manage filesystems on remote FTP servers.

class fs.ftpfs.FTPFS(host: Text, user: Text = 'anonymous', passwd: Text = '', acct: Text = '', timeout: int = 10, port: int = 21, proxy: Optional[Text] = None, tls: bool = False)[source]

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: Text, user: Text = 'anonymous', passwd: Text = '', acct: Text = '', timeout: int = 10, port: int = 21, proxy: Optional[Text] = None, tls: bool = False) → None[source]

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() → None[source]

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: Text, wipe: bool = False) → bool[source]

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

property features

Features of the remote FTP server.

Type

dict

property ftp

the underlying FTP client.

Type

FTP

property ftp_url

Get the FTP url this filesystem will open.

getinfo(path: Text, namespaces: Optional[Container[Text]] = None) → Info[source]

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: Text = 'standard') → Dict[Text, object][source]

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.

geturl(path: str, purpose: str = 'download') → Text[source]

Get FTP url for resource.

listdir(path: Text) → List[Text][source]

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
makedir(path: Text, permissions: Optional[Permissions] = None, recreate: bool = False) → SubFS[_F][source]

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
openbin(path: Text, mode: Text = 'r', buffering: int = -1, **options: Any) → BinaryIO[source]

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
readbytes(path: Text) → bytes[source]

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
remove(path: Text) → None[source]

Remove a file from the filesystem.

Parameters

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

Raises
removedir(path: Text) → None[source]

Remove a directory from the filesystem.

Parameters

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

Raises
scandir(path: Text, namespaces: Optional[Container[Text]] = None, page: Optional[Tuple[int, int]] = None) → Iterator[Info][source]

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
setinfo(path: Text, info: RawInfo) → None[source]

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)
property supports_mlst

whether the server supports MLST feature.

Type

bool

upload(path: Text, file: BinaryIO, chunk_size: Optional[int] = None, **options: Any) → None[source]

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: Text, contents: ByteString) → None[source]

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.