Merge pull request #17 from Paperspace/fun-readme-graphic

BartoszCki · web-flow · commit 5a20f9ede131 · 2019-06-13T11:45:32.000+02:00
Update README.md
diff --git a/README.md b/README.md
@@ -1,4 +1,6 @@
-Paperspace Python
+![Artboard 1](https://user-images.githubusercontent.com/585865/59315146-781a3300-8c86-11e9-9b7d-0cbca81d4278.png)
+
+Gradient CLI
 =================
 
 Release 0.2.2a0
@@ -9,7 +11,7 @@ See [releasenotes.md](https://github.com/Paperspace/paperspace-python/blob/maste
 
 Getting Started
 ===============
-1. Make sure you have a Paperspace account set up. Go to http://paperspace.com
+1. Make sure you have a Paperspace account set up. Go to [http://paperspace.com](https://www.paperspace.com/account/signup?gradient=true)
    to register.
 
 2. Use pip, pipenv, or conda to install the gradient package, e.g.:
@@ -33,42 +35,22 @@ Getting Started
     and then add `. ~/paperspace_complete.sh` to your `.bashrc`, `.zshrc` or `activate` script.
 
     More: https://click.palletsprojects.com/en/7.x/bashcomplete/
-4. Download your api key by executing the following:
-
-    `gradient login`
-
-   Follow the prompts to enter your Paperspace email and password.
+4. Set your api key by executing the following:
 
-   You can also enter your credentials directly on the command line as follows:
-
-    `gradient login <email> <password> [<api_token_name>]`
+    `gradient apiKey <your-api-key-here>`
 
    Note: your api key is cached in ~/.paperspace/config.json
+
    You can remove your cached api key by executing:
 
     `gradient logout`
 
-5. Run the sample script hello.py using Python:
-
-    `python hello.py`
-
-   The source of this sample script shows how a script can automatically run itself on the Paperspace job cluster node:
-
-    ```
-    import paperspace
-
-    paperspace.run()
-
-    print('hello gradient!')
-    ```
-
-   Note: the source is modified before transfer to the job cluster in order to remove imported `paperspace` references.
+5. Use gradient to run a python script remotely:
 
-6. Use gradient to run a python script remotely:
-
-    `gradient run myscript.py`
+    `gradient run myscript.py --name <your-new-job-name>`
 
    The script will be run on the Paperspace job cluster node, and its output will be logged locally.
+   Note: this will archive and upload your entire current working directory to our server if `--workspace` was not provided
 
 
 Create/create and start experiment
@@ -84,79 +66,25 @@ To create and immediately start new experiment use:
 gradient experiments run [type] [--options]
 ```
 
-For a full list of available commands run `paperspace experiments --help`. 
+For a full list of available commands run `gradient experiments --help`. 
 Note that some options are required to create new experiment.
 
 
-Specifying jobs options within a script
-=======================================
-This example shows how a script can specify paperspace jobs options for itself, such as `project` name, `machineType`, and a `container` reference:
-
-    # tests/test_remote.py - runs itself on paperspace, demonstrates setting jobs create options
-    import os
-    import paperspace
-
-    paperspace.run({'project': 'myproject', 'machineType': 'P5000',
-                    'container': 'paperspace/tensorflow-python'})
-
-    print(os.getcwd())
-    print('something useful')
-
-
-Automatic running of a python script remotely
-=============================================
-The above example demonstrates running a python script locally and having that script transmit itself to the paperspace jobs cluster for further execution.  To do this a copy of the local script is modified before transmission to the jobs cluster, in order to strip out the `import paperspace` statements and other `paperspace` library references. There are also some limitations on the types of import statements that are supported, and the dependencies that are supported in each environment (local vs. remote):
-
-1. You need to use a bare import statement, `import paperspace`, and not use the `import paperspace as ...` form.
-2. The import form `from paperspace import ...` is currently not supported.
-3. Everything after the `paperspace.run()` function call is ignored when running locally (when no script name is provided).  The local script execution stops after the `paperspace.run()` call.
-4. Dependencies that are included before `paperspace.run()` must be available locally.
-5. If you need to reference dependencies that are not available locally but are available remotely, those should be imported after the `paperspace.run()` call.
-6. Dependencies that are needed remotely need to either be already installed in the container used for the job, or need to be installed using one of the techniques below in the section [Dependency Options](#dependency-options)
-
-Because of these limitations it may not always be appropriate to run python scripts automatically from within the same script file.  As an alternative you can run your python scripts unmodified using the techniques below.
-
-
 Running a python script by name
 ===============================
-You can run an python script on paperspace from the command line as follows:
+You can run a Python script on a Paperspace server from the command line as follows:
 
-    gradient run myscript.py
+    gradient run myscript.py --name my_new_job
 
 You can also provide additional jobs options on the command line:
 
-    gradient run myscript.py --project myproject --machineType P5000 \
+    gradient run myscript.py --name my_new_job --project myproject --machineType P5000 \
      --container paperspace/tensorflow-python`
 
-Alternatively you can use the `paperspace.run()` fuction in code with a script file name as the first argument:
-
-    import paperspace
+Note: this functionality is deprecated and will not be available in future releases
 
-    paperspace.run('myscript.py') # runs myscript on paperspace
+See the [Gradient docs](https://docs.paperspace.com/gradient/jobs/about) for the full list of jobs create options that can be specified.
 
-In code you can provide additional paperspace jobs create options in a dict in the second argument to run():
-
-    paperspace.run('myscript.py', {'project': 'myproject', 'machineType': 'P5000',
-                                   'container': 'paperspace/tensorflow-python'})
-
-See the Paperspace API [jobs create](https://paperspace.github.io/paperspace-node/jobs.html#.create) documentation for the full list of jobs create options that can be specified.
-
-
-Using gradient run
-===========================
-The `gradient run` command provides a number of options to run python code and other commands remotely, as well as copy files and set up python dependencies:
-
-    gradient run [options] [[-m] <script> [args] | -c "python code" | --command "shell cmd"]
-      options:
-      [--python 2|3]
-      [--init [<init.sh>]]
-      [--pipenv]
-      [--req [<requirements.txt>]]
-      [--workspace .|<workspace_path>]
-      [--ignoreFiles "<file-or-dir>,..."]
-      [jobs create options]
-      [--dryrun]
-      [-]
 
 Basic Run Scenarios
 ===================
@@ -210,61 +138,22 @@ Job Options
 ===========
 The `--workspace` option allows you to specify a workspace file or directory to upload, or a git repo link to download and merge with the container.  For example, to upload the current directory along with a script file run:
 
-    gradient run myscript.py --workspace .
+    gradient run myscript.py --name my_new_job --workspace workspace-dir
+
+Note: `--workspace` defaults to `.`
 
 See the Paperspae API [jobs create](https://paperspace.github.io/paperspace-node/jobs.html#.create) documentation for more details on the `--workspace` option and related options.
 
 The `--ignoreFiles "<file-or-dir>,..."` option can be used specify a simple comma separated list of files and directories to ignore for the workspace upload:
 
-    gradient run myscript.py --workspace . --ignoreFiles "hello.py,paperspace"
+    gradient run myscript.py --name my_new_job --workspace . --ignoreFiles "hello.py,paperspace"
 
 The following files and directories are ignored by default: `.git`, `.gitignore`, `__pycache__`.
 
-Other `jobs create options` can be specified, such as `--machineType <machine type>`, `--container <container image reference>`, and `--project <project name>`.
-
-Here are some of the other jobs create options available:
-
-- `--project "<project name>"`  (defaults to 'paperspace-python')
-- `--machineType [C2|C7|GPU+|P4000|P5000|P6000|V100|G1|G6|G12|K80|GV100|GV100x8]`  (defaults to P5000)
-- `--container <docker image link or paperspace container name>`  (defaults to `docker.io/paperspace/tensorflow-python`)
-- `--name "<job name>"` (defaults to 'job for project <project name>')
-- `--projectId "<existing paperspace project id>"`
-- `--registryUsername "<username>"`  (for access to a private docker registry)
-- `--registryPassword "<secretpw>"`  (for access to a private docker registry)
-- `--workspaceUsername "<username>"`  (for access to a private git repo)
-- `--workspacePassword "<secretpw>"`  (for access to a private git repo)
+Other `jobs create` options can be specified, such as `--machineType <machine-type>`, `--container <container-image-reference>`, and `--project <project-name>`.
 
 See the Paperspae API [jobs create](https://paperspace.github.io/paperspace-node/jobs.html#.create) documentation for a complete description of these options.
 
-Dependency Options
-==================
-When running python scripts on paperspace you may need to provide additional dependencies to your scripts or specify the python version.
-The `gradient run` command has several options to support this: `--python`, `--init`, `--pipenv`, and `--req`. In addition you can use the `--workspace` option above to upload file dependencies.
-
-The `--python 2|3` option allows you specify whether to use `python2` or `python3` when running the script on paperspace.
-If ommitted, the script will be run with the same major version as is being used to run `gradient` locally.
-
-The `--init [<init.sh>]` option is used to specify a script to be run on the remote machine, inside the container, before the python script is run.
-If the init script name is ommitted, it is assumed to be the script named `init.sh` in the current directory.  The script is run using
-`source init.sh` in the container bash shell.  You can use this option to provide a list of commands to run to set up the dependencies for the script, such as running a list of `pip install` commands.  However, if you are using `pipenv` or a `requirements.txt` file we recommend you use one of the options below.  Multiple dependency setup options can be combinded however.
-
-The `--pipenv` option is used to upload and run the `Pipfile` and `Pipfile.lock` files in the current directory, if found.  These files
-are used on the paperspace machine to initialize the python environment using the `pipenv` tool, by running `pipenv install` within the container.  Note: `pipenv` must already be installed in the container for this option to work.  The default container used by gradient already has the `pipenv` package installed.
-
-The `--req [<requirements.txt>]` option is used specify that a `requirements.txt` file should be used to install the required python dependencies using `pip`.
-By default this option looks for a file named `requirements.txt` in the current directory, but you can override this by specifying a different file name.  Note: `pip` must already be installed in the container for this option to work.  The default container used by gradient already has the `pip` package installed.
-
-The `--dryrun` option allows you to see the resultant script that will be run on the paperspace job runner without actually running it.
-
-All of the above options can be combined in any combination, however, the order of operations is fixed to the following:
-
-1. `source <init.sh>` is run if `--init <init.sh>` is specified
-2. `pipenv [--two|--three] install` is run if `--pipenv` is specified
-3. `pip[2|3] install -r requirements.txt` is run if `--req <requirements.txt>` is specified
-4. `python[2|3] myscript.py` is run
-
-As mentioned above, you can use the `--dryrun` option to see the resultant commands that will be run on the paperspace jobs cluster node for a given set of options, without actually running the commands.
-
 
 Default Container
 =================
@@ -278,20 +167,13 @@ Other examples
 See the scripts in the `tests` folder for other examples.
 
 
-Other Authentication options
+Authentication options
 ============================
-1. Specify your apiKey explicitly on the paperspace.run() function or any of the paperspace.jobs methods, e.g.:
-
-    ```
-    paperspace.jobs.create({'apiKey': '1qks1hKsU7e1k...', 'project': 'myproject',
-                            'machineType': 'P5000', 'container': 'paperspace/tensorflow-python'})
-    ```
-
-2. Set the package paperspace.config option in your python code:
+1. Set the package paperspace.config option in your python code:
 
-    `paperspace.config.PAPERSPACE_API_KEY = '1qks1hKsU7e1k...'`
+    `gradient.config.PAPERSPACE_API_KEY = '1qks1hKsU7e1k...'`
 
-3. Set the PAPERSPACE_API_KEY environment variable:
+2. Set the PAPERSPACE_API_KEY environment variable:
 
     (on linux/mac:) `export PAPERSPACE_API_KEY=1qks1hKsU7e1k...`
 
@@ -300,17 +182,10 @@ Other Authentication options
    Note: the above methods take precedence over use of the cached api key in
    `~/.paperspace/config.json`
 
-4. Set the key in the `~/.paperspace/config.json` file from the command line by running:
-
-    `gradient apikey 1qks1hKsU7e1k...`
-
+3. Set the key in the `~/.paperspace/config.json` file from the command line by running:
 
-Using SAML, AD or GitHub credentials
-====================================
-Currently only email login is supported in the CLI - if you're using AD, SAML or GitHub to login to Paperspace, you will need an API key to log in with the CLI. 
+    `gradient apiKey 1qks1hKsU7e1k...`
 
-You can create an API key from within your Paperspace console under the [API](https://www.paperspace.com/console/account/api) section. Login to your [Paperspace console](https://www.paperspace.com/console), scroll to the API section in the left navigation bar, and click [CREATE AN API KEY](https://www.paperspace.com/console/account/api). Follow the instructions there.
-You will need to pick and API token name for your API key, and also provide a description.  You can copy the API key value associated with the API token name only at the time of initial creation. If you need to access your API key in the future, you can instead access it by API token name using the 'gradient login' command.
 
 Contributing
 ============
diff --git a/gradient/commands/run.py b/gradient/commands/run.py
@@ -1,7 +1,7 @@
 import os
 import sys
 
-from gradient import client, config, logger
+from gradient import logger
 from gradient.commands.jobs import CreateJobCommand
 from gradient.constants import RunMode
 from gradient.workspace import WorkspaceHandler
