Suggestion Re Simple Client Example: about asyncssh HOT 1 OPEN

Thanks for the feedback! See my response below.

Most users don't have localhost included in ~/.ssh/known_hosts. Suggestion: state this requirement

If you take a look at https://asyncssh.readthedocs.io/en/stable/#client-examples, it currently says the following just above the first example:

The following code shows an example of a simple SSH client which logs into localhost and
lists files in a directory named ‘abc’ under the user’s home directory. The username provided
is the logged in user, and the user’s default SSH client keys or certificates are presented during
authentication. The server’s host key is checked against the user’s SSH known_hosts file and
the connection will fail if there’s no entry for localhost there or if the key doesn’t match.

Was there something more you were looking for here? I could add a sentence around running "ssh localhost" to get the key added, but my expectation is that most AsyncSSH users are already familiar with the basics of SSH, like how user authentication and server host key checking works. Also, without knowing the config of OpenSSH on the system, I can't count on ssh localhost always prompting to add a server host key to known_hosts.

I intentionally avoided including known_hosts=None to disable host key checking in the example as I didn't want to encourage insecure behavior. I wanted it to fail if the server host key wasn't trusted.

This is because the example used runs the remote command: ls abc and most users won't realize (without some work) that this command fails unless there is a file or directory in their home directory on the remote machine named 'abc'.

You're right that I could have used a command which would be less likely to fail, like hostname. The text above the example clearly states what the command is attempting to do, though, and I chose that in part so that there would be a chance it could fail, triggering a Python exception rather than just outputting an error back on stderr. Note that this example includes the check=True argument, which is what triggers it to turn the failure into an exception.

That said, the example doesn't do a very good job explaining what comes back. The current output is something like:

SSH connection failed: Process exited with non-zero exit status 1

I could have the example catch the exception in conn.run() explicitly, and have it print out exc.stderr instead of result.stdout. It makes the example a bit longer, but it could be worth it to make it clearer what's going on. For example:

import asyncio, asyncssh, sys

async def run_client() -> None:
    async with asyncssh.connect('localhost') as conn:
        try:
            result = await conn.run('ls abc', check=True)
        except asyncssh.ProcessError as exc:
            print(exc.stderr, end='')
            print(f'Process exited with status {exc.exit_status}', file=sys.stderr)
        else:
            print(result.stdout, end='')

try:
    asyncio.run(run_client())
except (OSError, asyncssh.Error) as exc:
    sys.exit('SSH connection failed: ' + str(exc))

What do you think?

from asyncssh.