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'
).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
isTrue
, any existing file will be truncated.
- 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:
- Returns:
resource information object.
- Return type:
- 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:
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
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: Text) Optional[datetime.datetime] [source]¶
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.
- 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:
- Raises:
fs.errors.DirectoryExpected – If
path
is not a directory.fs.errors.ResourceNotFound – If
path
does not exist.
- makedir(path: Text, permissions: Optional[Permissions] = None, recreate: bool = False) SubFS[_F] [source]¶
Make a directory.
- Parameters:
- Returns:
a filesystem whose root is the new directory.
- Return type:
- Raises:
fs.errors.DirectoryExists – If the path already exists.
fs.errors.ResourceNotFound – If the path is not found.
- 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:
- 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 andmode
does not imply creating the file, or if any ancestor ofpath
does not exist.
- 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:
- Raises:
fs.errors.FileExpected – if
path
exists but is not a file.fs.errors.ResourceNotFound – if
path
does not exist.
- remove(path: Text) None [source]¶
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: Text) None [source]¶
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: 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, orNone
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:
- Raises:
fs.errors.DirectoryExpected – If
path
is not a directory.fs.errors.ResourceNotFound – If
path
does not exist.
- 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:
- 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 bygetinfo(file).raw
.Example
>>> details_info = {"details": { ... "modified": time.time() ... }} >>> my_fs.setinfo('file.txt', details_info)
- 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)