Skip to content
Browse files

Update README.md

  • Loading branch information...
1 parent de35f0a commit d0d704fab757df4ab28555537c4ed29ba58a912b @sporsh committed
Showing with 36 additions and 33 deletions.
  1. +36 −33 README.md
View
69 README.md
@@ -3,8 +3,32 @@
Carnifex provides an api for executing commands. The processes can be started locally or remotely on another machine with minimal effort for the user.
Current implementations support local sub processes and remote processes over ssh.
-## The Process Inductor
-The process inductor classes abstract execution of processes. It lets you induce processes via `run`, `getOutput`, `getExitCode` and the slightly more complex method `execute` processes.
+## Running commands and starting processes
+All the fun is abstracted in what is called the Process Inductor.
+It lets you 'induce' processes locally or remote with `run`, `getOutput`, `getExitCode` and the slightly more complex method `execute`.
+
+It's super simple to use:
+```python
+inductor.run('echo "hello world")
+```
+This will work exactly the same for local and remote processes.
+You will gather stdout, stderr, exit code or signal if the process was terminated
+
+Here is a more complex example:
+```python
+complex_command_line = """\
+python -c
+"import sys
+sys.stdout.write('hello stdout\\n')
+sys.stderr.write('whops, we err\\'d'\\n)
+exit(1)
+"
+"""
+inductor.run(complex_command_line)
+```
+
+Which will launch a python process that outputs `hello stdout` on standard output,
+`whops, we err'd` on standard error, and exits with exitcode `1`
* `Inductor.run`: execute and a command and run the process until completed (or terminated), then return stdout, stderr and exit code of the process
* `Inductor.getOutput`: just like run, but only gather output (stdout and/or stderr can be specified)
@@ -13,51 +37,30 @@ The process inductor classes abstract execution of processes. It lets you induce
All of these ways of running processes can be used in the same way both for starting a local sub process, or a remote process on another machine.
-### Local processes
+
+### Setting up a local processes inductor
+For running commands locally, you will use a `LocalProcessInductor`:
```python
-import carnifex
from twisted.internet import reactor
inductor = carnifex.LocalProcessInductor(reactor)
```
-### Remote processes
+### Setting up a remote processes inductor
+It is just as simple for remote process inductor, but you can in addition specify credentials for users
```python
-import carnifex
from twisted.internet import reactor
inductor = carnifex.SSHProcessInductor(reactor, 'localhost', 22)
+inductor.addCredentials(user='remoteuser', password='remotepass')
```
+You can set up credentials for different users by using the `addCredentials` method, and both `password` and `privateKey`, `publicKey` authentication is possible.
+By using `addKnownHost` you can choose to only allow connecting to servers with keys you have validated as well!
-### Building commands
-To start a process with carnifex, you need to supply at least one parameter, which is the `executable` to launch.
-This is the bare minimum, and does not give you any flexibility to specify arguments to the executable. To do that, you'll need to specify one more argument `args`, which basically is the argument list that is passed to the process. The argument list consist of the name of the process and subsequent arguments to it. The name is usually the same as the `executable`
-
-One usual use case is the following
+To run a remote process as a different user, simply specify the `uid` attribute:
```python
-args = ['echo', 'hello world']
-inductor.run(args[0], args)
+inductor.run('echo "hello world", uid='remoteuser')
```
-This can be a quite tedious way of specifying the command line to run, so we have the convenience method `parseCommandLine` to assist us. `parseCommandLine` will take a command line string - like you would type it in a shell - and parse it to a dictionary, suitable for the keyword arguments to the inductor methods.
-
-Here is a more complex example, to illustrate the usefulness of the `parseCommandLine` function:
-```python
-complex_command_line = """\
-python -c
-"import sys
-sys.stdout.write('hello stdout\\n')
-sys.stderr.write('whops, we err\\'d'\\n)
-exit(1)
-"
-"""
-exec_args = parseCommandLine(complex_command_line)
-inductor.run(**exec_args)
-```
-
-Which will launch a python process that outputs `hello stdout` on standard output,
-`whops, we err'd` on standard error, and exits with exitcode `1`
-
-
## Endpoint - use a process as network transport
A endpoint adaption is provided to make it possible to connect any Twisted

0 comments on commit d0d704f

Please sign in to comment.
Something went wrong with that request. Please try again.