Client API

class aioftp.Client(*, create_connection=None, socket_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)

Bases: aioftp.client.BaseClient

FTP client.

Parameters:
  • create_connection (callable()) – factory for creating connection. Using default asyncio.BaseEventLoop.create_connection() if omitted.
  • socket_timeout (float, int or None) – timeout for read operations
  • 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.
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=())

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
connect(host, port=21)

asyncio.coroutine()

Connect to server.

Parameters:
  • host (str) – host name for connection
  • port (int) – port number for connection
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=('epsv', 'pasv'))

asyncio.coroutine()

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

Parameters:
  • conn_type (str) – connection type (“I”, “A”, “E”, “L”)
  • commands (list) – sequence of commands to try to initiate passive server creation. First success wins. Default is EPSV, then PASV.
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”.

Parameters:
  • path (str or pathlib.PurePosixPath) – directory or file path
  • 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)
parse_ls_date(s, *, now=None)

Parsing dates from the ls unix utility. For example, “Nov 18 1958” 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.ClientSession(host, port=21, user='anonymous', password='anon@', account='', **kwargs)

aioftp.Client wrapper to use client as context manager. This 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.ClientSession("127.0.0.1") as client:
...     # do
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.