Built In Commands¶
A few commands are provided out of the box. To use them in a project, import them:
# E.g., commands.py at the top level of your project
from runcommands.commands import local, remote
runcommand local --help
Or call them from your own commands:
from runcommands import command
from runcommands.commands import local
@command
def test():
local('python -m unittest discover .')
Copy files locally¶
-
copy_file.
implementation
(destination, follow_symlinks=True, template: arg<BoolOrStr>() = False, context=None)¶ Copy source file to destination.
The destination may be a file path or a directory. When it’s a directory, the source file will be copied into the directory using the file’s base name.
When the source file is a template,
context
will be used as the template context. The supported template types are ‘format’ and ‘string’. The former usesstr.format_map()
and the latter usesstring.Template()
.Note
shutil.copy()
from the standard library is used to do the copy operation.
Sync files with remote¶
-
sync.
implementation
(destination, host, user=None, sudo=False, run_as=None, options=('-rltvz', '--no-perms', '--no-group'), excludes=(), exclude_from=None, delete=False, dry_run=False, mode='u=rwX, g=rwX, o=', quiet=True, pull=False, stdout: arg<StreamOptions>() = None, stderr: arg<StreamOptions>() = None, echo=False, raise_on_error=True) → runcommands.result.Result¶ Sync files using rsync.
By default, a local
source
is pushed to a remotedestination
. To pull from a remotesource
to a localdestination
instead, passpull=True
.
Git version¶
-
git_version.
implementation
(show: Print version to stdout = False)¶ Get tag associated with HEAD; fall back to SHA1.
If HEAD is tagged, return the tag name; otherwise fall back to HEAD’s short SHA1 hash.
Note
Only annotated tags are considered.
Note
When no minimum hash length is specified, the minimum length is determined by
git rev-parse
based on git’score.abbrev
config variable.Note
The output isn’t shown by default. To show it, pass the
--show
flag.
Run local commands¶
-
local.
implementation
(background=False, cd=None, environ: arg<dict>() = None, replace_env=False, paths=(), shell: arg<bool>() = None, stdout: arg<StreamOptions>() = None, stderr: arg<StreamOptions>() = None, echo=False, raise_on_error=True, dry_run=False) → runcommands.result.Result¶ Run a local command via
subprocess.run()
.Parameters: - args (list|str) – A list of args or a shell command.
- background (bool) – Run process in background? If this is set,
the command will be run in the background via
subprocess.Popen
then this function will immediately return. The call site will need to wait on the returnedPopen
object usingPopen.wait()
or by some other means (perhaps by starting another long-running process in the foreground). - cd (str) – Working directory to change to first.
- environ (dict) – Additional environment variables to pass to the subprocess.
- replace_env (bool) – If set, only pass env variables from
environ
to the subprocess. - paths (list) – A list of additional paths.
- shell (bool) – Run as a shell command? The default is to run in
shell mode if
args
is a string. This flag can be used to force a list of args to be run as a shell command too. - stdout (StreamOptions) – What to do with stdout (capture, hide, or show).
- stderr (StreamOptions) – Same as
stdout
. - echo (bool) – Whether to echo the command before running it.
- raise_on_error (bool) – Whether to raise an exception when the subprocess returns a non-zero exit code.
- dry_run (bool) – If set, print command instead of running it.
Returns: When the command is run in the foreground. -
subprocess.Popen
: When the command is run in thebackground.
Return type: Result
Raises: Result
– When the subprocess returns a non-zero exit code (andraise_on_error
is set).
Run remote commands¶
-
remote.
implementation
(host, user=None, port=None, sudo=False, run_as=None, shell='/bin/sh', cd=None, environ: arg<None>() = None, paths=(), stdout: arg<StreamOptions>() = None, stderr: arg<StreamOptions>() = None, echo=False, raise_on_error=True, dry_run=False) → runcommands.result.Result¶ Run a remote command via SSH.
Runs a remote shell command using
ssh
in a subprocess like so:ssh -q [-t] [<user>@]<host> [sudo [-u <run_as>] -H] /bin/sh -c ' [cd <cd> &&] [export XYZ="xyz" &&] [export PATH="<path>" &&] <cmd> '
Parameters: - cmd (list|str) – The command to run. If this is a list, it will be flattened into a string.
- host (str) – Remote host to SSH into.
- user (str) – Remote user to log in as (defaults to current local user).
- port (int) – SSH port on remote host.
- sudo (bool) – Run the remote command as root using
sudo
. - run_as (str) – Run the remote command as a different user using
sudo -u <run_as>
. - shell (str) – The remote user’s default shell will be used to run the remote command unless this is set to a different shell.
- cd (str) – Where to run the command on the remote host.
- environ (dict) – Extra environment variables to set on the remote host.
- paths (list) – Additional paths to prepend to the remote
$PATH
. - stdout – See
runcommands.commands.local
. - stderr – See
runcommands.commands.local
. - echo – See
runcommands.commands.local
. - raise_on_error – See
runcommands.commands.local
. - dry_run – See
runcommands.commands.local
.