Docstring suggests host parameter of fabric.connection class is a keyword and not a positional parameter

[doolio]

fabric/fabric/connection.py

Line 251 in 988dd0f

a call like ``Connection(host='myalias')`` will result in an

where the official docs here suggest it is a positional parameter.

[prokopto-dev]

This is not quite an issue, as far as I can tell.

Writing a 'positional' argument as a 'keyword' argument isn't against any PIP spec, and is perfectly functional Python 3.8+.

I think the author intended to make explicit the fact that the assigned variable in the underlying constructor for the Connection object (that is, in __init__) would be the host variable, but that it differs from Host as sourced from SSH configuration, and original_host, the value of the __init__-time value.

Because of the uses of the three hosts, and their interactions, simply referencing Connection('myalias'), while equally functionally correct, doesn't elaborate the possible confusion when someone attempts to do something like the following:

SSH Config

Host myalias
  Hostname realhostname

Fabric python file

from fabric import Connection

c: Connection = Connection('myalias')

assert c.host == 'myalias'
>> False

Whereas the document is stating that c.host will instead be realhostname, and that the original value should be gathered via c.original_hostname.

I think the point is more that, Fabric does a great job of hiding a lot of the magic under the hood that it hands off to the OpenSSH/Paramiko behaviors, but in some cases, it needs to show explicitly what it's doing to allow seamless use of the default SSH backends.

EDIT: For clarity.