Library Use¶
Fabric’s primary use case is via fabfiles and the fab tool,
and this is reflected in much of the documentation. However, Fabric’s internals
are written in such a manner as to be easily used without fab
or fabfiles
at all – this document will show you how.
There’s really only a couple of considerations one must keep in mind, when
compared to writing a fabfile and using fab
to run it: how connections are
really made, and how disconnections occur.
Connections¶
We’ve documented how Fabric really connects to its hosts before, but it’s currently somewhat buried in the middle of the overall execution docs. Specifically, you’ll want to skip over to the Connections section and read it real quick. (You should really give that entire document a once-over, but it’s not absolutely required.)
As that section mentions, the key is simply that run
,
sudo
and the other operations only look in one place when
connecting: env.host_string. All of the other mechanisms
for setting hosts are interpreted by the fab
tool when it runs, and don’t
matter when running as a library.
That said, most use cases where you want to marry a given task X
and a given list of hosts Y
can, as of Fabric 1.3, be handled with the execute
function via execute(X, hosts=Y)
. Please see execute
‘s documentation for details – manual host string manipulation should be rarely necessary.
Disconnecting¶
The other main thing that fab
does for you is to disconnect from all hosts
at the end of a session; otherwise, Python will sit around forever waiting for
those network resources to be released.
Fabric 0.9.4 and newer have a function you can use to do this easily:
disconnect_all
. Simply make sure your code calls this when it
terminates (typically in the finally
clause of an outer try: finally
statement – lest errors in your code prevent disconnections from happening!)
and things ought to work pretty well.
If you’re on Fabric 0.9.3 or older, you can simply do this (disconnect_all
just adds a bit of nice output to this logic):
from fabric.state import connections
for key in connections.keys():
connections[key].close()
del connections[key]
Final note¶
This document is an early draft, and may not cover absolutely every difference
between fab
use and library use. However, the above should highlight the
largest stumbling blocks. When in doubt, note that in the Fabric source code,
fabric/main.py
contains the bulk of the extra work done by fab
, and may
serve as a useful reference.