Client API

class aioftp.Client(*, socket_timeout=None, connection_timeout=None, read_speed_limit=None, write_speed_limit=None, path_timeout=None, path_io_factory=<class 'aioftp.pathio.PathIO'>, encoding='utf-8', ssl=None, parse_list_line_custom=None, parse_list_line_custom_first=True, passive_commands=('epsv', 'pasv'), **siosocks_asyncio_kwargs)

Bases: aioftp.client.BaseClient

FTP client.

Parameters:
  • socket_timeout (float, int or None) – timeout for read operations
  • connection_timeout (float, int or None) – timeout for connection
  • read_speed_limit – download speed limit in bytes per second
  • write_speed_limit – upload speed limit in bytes per second
  • path_timeout (float, int or None) – timeout for path-related operations (make directory, unlink file, etc.)
  • path_io_factory (aioftp.AbstractPathIO) – factory of «path abstract layer»
  • encoding (str) – encoding to use for convertion strings to bytes
  • ssl (bool or ssl.SSLContext) – if given and not false, a SSL/TLS transport is created (by default a plain TCP transport is created). If ssl is a ssl.SSLContext object, this context is used to create the transport; if ssl is True, a default context returned from ssl.create_default_context() is used. Please look asyncio.loop.create_connection() docs.
  • parse_list_line_custom (callable) – callable, which receive exactly one argument: line of type bytes. Should return tuple of Path object and dictionary with fields “modify”, “type”, “size”. For more information see sources.
  • parse_list_line_custom_first (bool) – Should be custom parser tried first or last
  • **siosocks_asyncio_kwargs –

    siosocks key-word only arguments
abort(*, wait=True)

asyncio.coroutine()

Request data transfer abort.

Parameters:wait (bool) – wait for abort response [426]→226 if True
append_stream(destination, *, offset=0)

Create stream for append (write) data to destination file.

Parameters:
  • destination (str or pathlib.PurePosixPath) – destination path of file on server side
  • offset (int) – byte offset for stream start position
Return type:

aioftp.DataConnectionThrottleStreamIO
change_directory(path='..')

asyncio.coroutine()

Change current directory. Goes «up» if no parameters passed.

Parameters:path (str or pathlib.PurePosixPath) – new directory, goes «up» if omitted
check_codes(expected_codes, received_code, info)

Checks if any of expected matches received.

Parameters:
  • expected_codes (tuple) – tuple of expected codes
  • received_code (aioftp.Code) – received code for matching
  • info (list) – list of response lines from server
Raises:

aioftp.StatusCodeError – if received code does not matches any expected code
close()

Close connection.

command(command=None, expected_codes=(), wait_codes=(), censor_after=None)

asyncio.coroutine()

Basic command logic.

  1. Send command if not omitted.
  2. Yield response until no wait code matches.
  3. Check code for expected.
Parameters:
  • command (str) – command line
  • expected_codes (tuple of str or str) – tuple of expected codes or expected code
  • wait_codes (tuple of str or str) – tuple of wait codes or wait code
  • censor_after (None or int) – index after which the line should be censored when logging
connect(host, port=21)

asyncio.coroutine()

Connect to server.

Parameters:
  • host (str) – host name for connection
  • port (int) – port number for connection
classmethod context(host, port=21, user='anonymous', password='anon@', account='', **kwargs)

Classmethod async context manager. This create aioftp.Client, make async call to aioftp.Client.connect(), aioftp.Client.login() on enter and aioftp.Client.quit() on exit.

Parameters:
  • host (str) – host name for connection
  • port (int) – port number for connection
  • user (str) – username
  • password (str) – password
  • account (str) – account (almost always blank)
  • **kwargs –

    keyword arguments, which passed to aioftp.Client

 
>>> async with aioftp.Client.context("127.0.0.1") as client:
...     # do
download(source, destination='', *, write_into=False, block_size=8192)

asyncio.coroutine()

High level download method for downloading files and directories recursively and save them to the file system.

Parameters:
  • source (str or pathlib.PurePosixPath) – source path of file or directory on server side
  • destination (str or pathlib.Path) – destination path of file or directory on client side
  • write_into (bool) – write source into destination (if you want download file and change it name, as well with directories)
  • block_size (int) – block size for transaction
download_stream(source, *, offset=0)

asyncio.coroutine()

Create stream for read data from source file.

Parameters:
Return type:

aioftp.DataConnectionThrottleStreamIO
exists(path)

asyncio.coroutine()

Check path for existence.

Parameters:path (str or pathlib.PurePosixPath) – path to check
Return type:bool
static format_date_time(d)

Formats dates from strptime in a consistent format

Parameters:d (datetime) – return value from strptime
Return type::py:class`str`
get_current_directory()

asyncio.coroutine()

Getting current working directory.

Return type:pathlib.PurePosixPath
get_passive_connection(conn_type='I', commands=None)

asyncio.coroutine()

Getting pair of reader, writer for passive connection with server.

Parameters:
  • conn_type (str) – connection type (“I”, “A”, “E”, “L”)
  • commands (list or None) – sequence of commands to try to initiate passive server creation. First success wins. Default is EPSV, then PASV. Overwrites the parameters passed when initializing the client.
Return type:

(asyncio.StreamReader, asyncio.StreamWriter)
get_stream(*command_args, conn_type='I', offset=0)

asyncio.coroutine()

Create aioftp.DataConnectionThrottleStreamIO for straight read/write io.

Parameters:
  • command_args – arguments for aioftp.Client.command()
  • conn_type (str) – connection type (“I”, “A”, “E”, “L”)
  • offset (int) – byte offset for stream start position
Return type:

aioftp.DataConnectionThrottleStreamIO
is_dir(path)

asyncio.coroutine()

Checks if path is dir.

Parameters:path (str or pathlib.PurePosixPath) – path to check
Return type:bool
is_file(path)

asyncio.coroutine()

Checks if path is file.

Parameters:path (str or pathlib.PurePosixPath) – path to check
Return type:bool
list(path='', *, recursive=False, raw_command=None)

asyncio.coroutine()

List all files and directories in “path”. If “path” is a file, then result will be empty

Parameters:
  • path (str or pathlib.PurePosixPath) – directory
  • recursive (bool) – list recursively
  • raw_command (str) – optional ftp command to use in place of fallback logic (must be one of “MLSD”, “LIST”)
Return type:

list or async for context

 
>>> # lazy list
>>> async for path, info in client.list():
...     # no interaction with client should be here(!)

>>> # eager list
>>> for path, info in (await client.list()):
...     # interaction with client allowed, since all paths are
...     # collected already

>>> stats = await client.list()
login(user='anonymous', password='anon@', account='')

asyncio.coroutine()

Server authentication.

Parameters:
  • user (str) – username
  • password (str) – password
  • account (str) – account (almost always blank)
Raises:

aioftp.StatusCodeError – if unknown code received
make_directory(path, *, parents=True)

asyncio.coroutine()

Make directory.

Parameters:
static parse_directory_response(s)

Parsing directory server response.

Parameters:s (str) – response line
Return type:pathlib.PurePosixPath
static parse_epsv_response(s)

Parsing EPSV (message (|||port|)) response.

Parameters:s (str) – response line
Returns:(ip, port)
Return type:(None, int)
parse_line()

asyncio.coroutine()

Parsing server response line.

Returns:

(code, line)
Return type:

(aioftp.Code, str)
Raises:
parse_list_line(b)

Parse LIST response with both Microsoft Windows® parser and UNIX parser

Parameters:b (bytes or str) – response line
Returns:(path, info)
Return type:(pathlib.PurePosixPath, dict)
parse_list_line_unix(b)

Attempt to parse a LIST line (similar to unix ls utility).

Parameters:b (bytes or str) – response line
Returns:(path, info)
Return type:(pathlib.PurePosixPath, dict)
parse_list_line_windows(b)

Parsing Microsoft Windows dir output

Parameters:b (bytes or str) – response line
Returns:(path, info)
Return type:(pathlib.PurePosixPath, dict)
classmethod parse_ls_date(s, *, now=None)

Parsing dates from the ls unix utility. For example, “Nov 18 1958”, “Jan 03 2018”, and “Nov 18 12:29”.

Parameters:s (str) – ls date
Return type:str
parse_mlsx_line(b)

Parsing MLS(T|D) response.

Parameters:b (bytes or str) – response line
Returns:(path, info)
Return type:(pathlib.PurePosixPath, dict)
static parse_pasv_response(s)

Parsing PASV server response.

Parameters:s (str) – response line
Returns:(ip, port)
Return type:(str, int)
parse_response()

asyncio.coroutine()

Parsing full server response (all lines).

Returns:(code, lines)
Return type:(aioftp.Code, list of str)
Raises:aioftp.StatusCodeError – if received code does not matches all already received codes
static parse_unix_mode(s)

Parsing unix mode strings (“rwxr-x–t”) into hexacimal notation.

Parameters:s (str) – mode string
Return mode:
Return type:int
quit()

asyncio.coroutine()

Send “QUIT” and close connection.

remove(path)

asyncio.coroutine()

High level remove method for removing path recursively (file or directory).

Parameters:path (str or pathlib.PurePosixPath) – path to remove
remove_directory(path)

asyncio.coroutine()

Low level remove method for removing empty directory.

Parameters:path (str or pathlib.PurePosixPath) – empty directory to remove
remove_file(path)

asyncio.coroutine()

Low level remove method for removing file.

Parameters:path (str or pathlib.PurePosixPath) – file to remove
rename(source, destination)

asyncio.coroutine()

Rename (move) file or directory.

Parameters:
stat(path)

asyncio.coroutine()

Getting path stats.

Parameters:path (str or pathlib.PurePosixPath) – path for getting info
Returns:path info
Return type:dict
upload(source, destination='', *, write_into=False, block_size=8192)

asyncio.coroutine()

High level upload method for uploading files and directories recursively from file system.

Parameters:
  • source (str or pathlib.Path) – source path of file or directory on client side
  • destination (str or pathlib.PurePosixPath) – destination path of file or directory on server side
  • write_into (bool) – write source into destination (if you want upload file and change it name, as well with directories)
  • block_size (int) – block size for transaction
upload_stream(destination, *, offset=0)

Create stream for write data to destination file.

Parameters:
  • destination (str or pathlib.PurePosixPath) – destination path of file on server side
  • offset (int) – byte offset for stream start position
Return type:

aioftp.DataConnectionThrottleStreamIO
class aioftp.DataConnectionThrottleStreamIO(client, *args, **kwargs)

Bases: aioftp.common.ThrottleStreamIO

Add finish method to aioftp.ThrottleStreamIO, which is specific for data connection. This requires client.

Parameters:
finish(expected_codes='2xx', wait_codes='1xx')

asyncio.coroutine()

Close connection and wait for expected_codes response from server passing wait_codes.

Parameters:
  • expected_codes (tuple of str or str) – tuple of expected codes or expected code
  • wait_codes (tuple of str or str) – tuple of wait codes or wait code
class aioftp.Code

Bases: str

Representation of server status code.

matches(mask)
Parameters:mask (str) – Template for comparision. If mask symbol is not digit then it passes. 
>>> Code("123").matches("1")
True
>>> Code("123").matches("1x3")
True
class aioftp.StatusCodeError(expected_codes, received_codes, info)

Raised for unexpected or “bad” status codes.

Parameters: 
>>> try:
...     # something with aioftp
... except StatusCodeError as e:
...     print(e.expected_codes, e.received_codes, e.info)
...     # analyze state

Exception members are tuples, even for one code.