Client API¶
- class aioftp.Client(*, 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, parse_list_line_custom=None, **siosocks_asyncio_kwargs)¶
Bases:
BaseClient
FTP client.
- Parameters:
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 bytesssl (
bool
orssl.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 lookasyncio.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.
**siosocks_asyncio_kwargs –
siosocks key-word only arguments
- 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:
- 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`
- async get_current_directory()¶
asyncio.coroutine()
Getting current working directory.
- Return type:
- async get_passive_connection(conn_type='I', commands=('epsv', 'pasv'))¶
asyncio.coroutine()
Getting pair of reader, writer for passive connection with server.
- Parameters:
- 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 recursivelyraw_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()
- 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)¶
Parse LIST response with both Microsoft Windows® parser and UNIX parser
- Parameters:
- Returns:
(path, info)
- Return type:
- parse_list_line_unix(b)¶
Attempt to parse a LIST line (similar to unix ls utility).
- Parameters:
- Returns:
(path, info)
- Return type:
- parse_list_line_windows(b)¶
Parsing Microsoft Windows dir output
- Parameters:
- Returns:
(path, info)
- Return type:
- 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.