Client API¶
- class aioftp.Client(*, loop=None, 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')¶
Bases:
BaseClient
FTP client.
- Parameters:
loop (
asyncio.BaseEventLoop
) – loop to use for creating connection and binding with streamscreate_connection (
callable()
) – factory for creating connection. Using defaultasyncio.BaseEventLoop.create_connection()
if omitted.socket_timeout (
float
,int
or None) – timeout for read operationsread_speed_limit – download speed limit in bytes per second
write_speed_limit – upload speed limit in bytes per second
path_timeout (
float
,int
orNone
) – 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
- async 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
orpathlib.PurePosixPath
) – destination path of file on server sideoffset (
int
) – byte offset for stream start position
- Return type:
- async change_directory(path='..')¶
asyncio.coroutine()
Change current directory. Goes «up» if no parameters passed.
- Parameters:
path (
str
orpathlib.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 codesreceived_code (
aioftp.Code
) – received code for matchinginfo (
list
) – list of response lines from server
- Raises:
aioftp.StatusCodeError – if received code does not matches any expected code
- close()¶
Close connection.
- async command(command=None, expected_codes=(), wait_codes=())¶
asyncio.coroutine()
Basic command logic.
Send command if not omitted.
Yield response until no wait code matches.
Check code for expected.
- async connect(host, port=21)¶
asyncio.coroutine()
Connect to server.
- async 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
orpathlib.PurePosixPath
) – source path of file or directory on server sidedestination (
str
orpathlib.Path
) – destination path of file or directory on client sidewrite_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:
source (
str
orpathlib.PurePosixPath
) – source path of file on server sideoffset (
int
) – byte offset for stream start position
- Return type:
- async exists(path)¶
asyncio.coroutine()
Check path for existence.
- Parameters:
path (
str
orpathlib.PurePosixPath
) – path to check- Return type:
- async get_current_directory()¶
asyncio.coroutine()
Getting current working directory.
- Return type:
- async get_passive_connection(conn_type='I')¶
asyncio.coroutine()
Getting pair of reader, writer for passive connection with server.
- Parameters:
conn_type (
str
) – connection type (“I”, “A”, “E”, “L”)- Return type:
- 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:
- async is_dir(path)¶
asyncio.coroutine()
Checks if path is dir.
- Parameters:
path (
str
orpathlib.PurePosixPath
) – path to check- Return type:
- async is_file(path)¶
asyncio.coroutine()
Checks if path is file.
- Parameters:
path (
str
orpathlib.PurePosixPath
) – path to check- Return type:
- list(path='', *, recursive=False, raw_command=None)¶
asyncio.coroutine()
List all files and directories in “path”.
- Parameters:
path (
str
orpathlib.PurePosixPath
) – directory or file pathrecursive (
bool
) – list recursively
- :param raw_command optional ftp command to use in place of
fallback logic (must be one of “MLSD”, “LIST”)
:type cmd
str
- 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()
- async login(user='anonymous', password='anon@', account='')¶
asyncio.coroutine()
Server authentication.
- Parameters:
- Raises:
aioftp.StatusCodeError – if unknown code received
- async make_directory(path, *, parents=True)¶
asyncio.coroutine()
Make directory.
- Parameters:
path (
str
orpathlib.PurePosixPath
) – path to directory to createparents (
bool
) – create parents if does not exists
- static parse_directory_response(s)¶
Parsing directory server response.
- Parameters:
s (
str
) – response line- Return type:
- static parse_epsv_response(s)¶
Parsing EPSV (message (|||port|)) response.
- async parse_line()¶
asyncio.coroutine()
Parsing server response line.
- Returns:
(code, line)
- Return type:
(
aioftp.Code
,str
)- Raises:
ConnectionResetError – if received data is empty (this means, that connection is closed)
asyncio.TimeoutError – if there where no data for timeout period
- parse_list_line(b)¶
Attempt to parse a LIST line (similar to unix ls utility).
- Parameters:
- Returns:
(path, info)
- Return type:
- static parse_ls_date(s, *, now=None)¶
Parsing dates from the ls unix utility. For example, “Nov 18 1958” and “Nov 18 12:29”.
- parse_mlsx_line(b)¶
Parsing MLS(T|D) response.
- Parameters:
- Returns:
(path, info)
- Return type:
- static parse_pasv_response(s)¶
Parsing PASV server response.
- async parse_response()¶
asyncio.coroutine()
Parsing full server response (all lines).
- Returns:
(code, lines)
- Return type:
(
aioftp.Code
,list
ofstr
)- 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.
- async quit()¶
asyncio.coroutine()
Send “QUIT” and close connection.
- async remove(path)¶
asyncio.coroutine()
High level remove method for removing path recursively (file or directory).
- Parameters:
path (
str
orpathlib.PurePosixPath
) – path to remove
- async remove_directory(path)¶
asyncio.coroutine()
Low level remove method for removing empty directory.
- Parameters:
path (
str
orpathlib.PurePosixPath
) – empty directory to remove
- async remove_file(path)¶
asyncio.coroutine()
Low level remove method for removing file.
- Parameters:
path (
str
orpathlib.PurePosixPath
) – file to remove
- async rename(source, destination)¶
asyncio.coroutine()
Rename (move) file or directory.
- Parameters:
source (
str
orpathlib.PurePosixPath
) – path to renamedestination (
str
orpathlib.PurePosixPath
) – path new name
- async stat(path)¶
asyncio.coroutine()
Getting path stats.
- Parameters:
path (
str
orpathlib.PurePosixPath
) – path for getting info- Returns:
path info
- Return type:
- async 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
orpathlib.Path
) – source path of file or directory on client sidedestination (
str
orpathlib.PurePosixPath
) – destination path of file or directory on server sidewrite_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
orpathlib.PurePosixPath
) – destination path of file on server sideoffset (
int
) – byte offset for stream start position
- Return type:
- 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 toaioftp.Client.connect()
,aioftp.Client.login()
on enter andaioftp.Client.quit()
on exit.- Parameters:
>>> async with aioftp.ClientSession("127.0.0.1") as client: ... # do
- class aioftp.DataConnectionThrottleStreamIO(client, *args, **kwargs)¶
Bases:
ThrottleStreamIO
Add finish method to
aioftp.ThrottleStreamIO
, which is specific for data connection. This requires client.- Parameters:
client (
aioftp.BaseClient
) – client class, which haveaioftp.Client.command()
*args –
positional arguments passed to
aioftp.ThrottleStreamIO
**kwargs –
keyword arguments passed to
aioftp.ThrottleStreamIO
- async finish(expected_codes='2xx', wait_codes='1xx')¶
asyncio.coroutine()
Close connection and wait for expected_codes response from server passing wait_codes.
- class aioftp.StatusCodeError(expected_codes, received_codes, info)¶
Raised for unexpected or “bad” status codes.
- Parameters:
expected_codes (
tuple
ofaioftp.Code
oraioftp.Code
) – tuple of expected codes or expected codereceived_codes (
tuple
ofaioftp.Code
oraioftp.Code
) – tuple of received codes or received code
>>> 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.