server_tutorial.rst

Server tutorial

aioftp server is much more like a tool. You configure it, run and forget about it.

Configuring server

At first you should create :class:`aioftp.Server` instance and start it

:py:meth:`aioftp.Server.start`

>>> server = aioftp.Server()
>>> await server.start()

Default arguments allow anonymous login and read/write current directory. So, there is one user with anonymous login and read/write permissions on "/" virtual path. Real path is current working directory.

Dealing with users and permissions

You can specify as much users as you want, just pass list of them when creating :class:`aioftp.Server` instance

:class:`aioftp.User`

:class:`aioftp.Permission`

>>> users = (
...     aioftp.User(
...         "Guido",
...         "secret_password",
...         home_path="/Guido",
...         permissions=(
...             aioftp.Permission("/", readable=False, writable=False),
...             aioftp.Permission("/Guido", readable=True, writable=True),
...         )
...     ),
...     aioftp.User(
...         home_path="/anon",
...         permissions=(
...             aioftp.Permission("/", readable=False, writable=False),
...             aioftp.Permission("/anon", readable=True),
...         )
...     ),
... )
>>> server = aioftp.Server(users)
>>> await server.start()

This will create two users: "Guido", who can read and write to "/Guido" folder, which is home folder, but can't read/write the root and other directories and anonymous user, who home directory is "/anon" and there is only read permission.

Path abstraction layer

aioftp provides abstraction of file system operations. You can use exist ones:

• :py:class:`aioftp.PathIO` — blocking path operations
• :py:class:`aioftp.AsyncPathIO` — non-blocking path operations, this one is blocking ones just wrapped with :py:meth:`asyncio.BaseEventLoop.run_in_executor`. It's really slow, so it's better to avoid usage of this path io layer.
• :py:class:`aioftp.MemoryPathIO` — in-memory realization of file system, this one is just proof of concept and probably not too fast (as it can be).

You can specify path_io_factory when creating :py:class:`aioftp.Server` instance. Default factory is :py:class:`aioftp.PathIO`.

>>> server = aioftp.Server(path_io_factory=aioftp.MemoryPathIO)
>>> await server.start()

Dealing with timeouts

There is three different timeouts you can specify:

• socket_timeout — timeout for low-level socket operations :py:meth:`asyncio.StreamReader.read`, :py:meth:`asyncio.StreamReader.readline` and :py:meth:`asyncio.StreamWriter.drain`. This one does not affects awaiting command read operation.
• path_timeout — timeout for file system operations
• idle_timeout — timeout for socket read operation when awaiting command, another words: how long user can keep silence without sending commands
• wait_future_timeout — timeout for waiting connection states (the main purpose is wait for passive connection)

Maximum connections

Connections count can be specified:

• per server
• per user

First one via server constructor

>>> server = aioftp.Server(maximum_connections=3)

Second one via user class

>>> users = (aioftp.User(maximum_connections=3),)
>>> server = aioftp.Server(users)

Throttle

Server have many options for read/write speed throttle:

• global per server
• per connection
• global per user
• per user connection

"Global per server" and "per connection" can be provided by constructor

>>> server = aioftp.Server(
...     read_speed_limit=1024 * 1024,
...     write_speed_limit=1024 * 1024,
...     read_speed_limit_per_connection=100 * 1024,
...     write_speed_limit_per_connection=100 * 1024
... )

User throttles can be provided by user constructor

>>> users = (
...     aioftp.User(
...         read_speed_limit=1024 * 1024,
...         write_speed_limit=1024 * 1024,
...         read_speed_limit_per_connection=100 * 1024,
...         write_speed_limit_per_connection=100 * 1024
...     ),
... )
>>> server = aioftp.Server(users)

Stopping the server

>>> await server.close()

WARNING

:py:meth:`aioftp.Server.list` use :py:meth:`aioftp.Server.build_list_string`, which should produce LIST strings with :py:meth:`datetime.datetime.strftime`. For proper work (in part of formatting month abbreviation) locale should be setted to "C". For this reason if you use multithreaded app, and use some locale-dependent stuff, you should use :py:meth:`aioftp.setlocale` context manager when you dealing with locale in another thread.

Futher reading

:doc:`server_api`