Merge branch 'main' of github.com:planetlabs/planet-client-python int…

…o main

README.md

@@ -17,17 +17,67 @@ The Planet SDK for Python is in 'pre-release' stages, working towards an
 initial release around July. Active development is tracked in the [Planet SDK 
 for Python Project](https://github.com/planetlabs/planet-client-python/projects/2). 
 The initial release will support Orders, Data and Subscription API's in the 
-command-line interface, with corresponding Python libraries. We expect 'beta' 
-milestones to be released in some form for each of the API's. After the 
+command-line interface, with corresponding Python libraries. After the 
 initial July release there will be additional work to support the remaining 
 Planet API's ([analytics](https://developers.planet.com/docs/analytics/), 
 [basemaps](https://developers.planet.com/docs/basemaps/) and 
 [tasking](https://developers.planet.com/docs/tasking/)).
 
+## Installation
+
+There are two options for installation: installing from PyPi or installing from source.
+
+Be aware that using either route will by default update your `planet` command-line and
+python library to v2, so you will no longer be able to use v1. As v2 is in a pre-release
+stage, with not all functionality implemented, we strongly recommend installing it in a 
+virtual environment - either [venv](https://python.land/virtual-environments/virtualenv) 
+or [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html). 
+If you've never worked with either then check out our [getting started with venv and Planet 
+SDK](docs/venv-tutorial.md). For anyone planning to contribute to the SDK the instructuctions
+are a bit different, see the [testing section of CONTRIBUTING.md](https://github.com/planetlabs/planet-client-python/blob/main/CONTRIBUTING.md#testing).
+
+Both installation routes use [pip](https://pip.pypa.io/en/stable/getting-started/), Python's
+package installer.
+
+The [--user](https://pip.pypa.io/en/stable/user_guide/#user-installs)
+flag is highly recommended for those new to pip.
+
+The Planet SDK for Python requires Python 3.7+.
+
+### Installing from PyPi
+
+(Note this is not yet working, as the pre-release has not happened yet, but will soon)
+
+To get version 2 of the Planet SDK you just use pip with the `--pre` command:
+
+```console
+$ pip install planet --pre 
+```
+
+### Installing from source
+
+To install you must [clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
+the [planet-client-python](https://github.com/planetlabs/planet-client-python) repository 
+to your local computer. After you have the repo local just navigate to the root
+directory, where this readme lives.
+
+Then you can install locally with pip:
+
+```console
+$ pip install . 
+```
+
+### Confirming its working
+
+After installation you should be able to use the command-line interface. Just type
+`planet` into the command-line and the usage and options should appear. If it doesn't 
+work don't hesitate to ask for help in the [discussions](https://github.com/planetlabs/planet-client-python/discussions/categories/q-a)
+forum.
+
 ## Documentation
 
 Documentation is currently [hosted online](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/)
-It should be considered 'in progress', with many updated to come. It can also
+It should be considered 'in progress', with many updates to come. It can also
 be built and hosted locally (see [CONTRIBUTING.md](CONTRIBUTING.md)) or can be 
 read from source in the `[docs](docs/)` directory.
 
@@ -37,9 +87,8 @@ The Planet SDK includes both a Python API and a command-line interface (CLI)
 to make use of the following Planet APIs:
 
 * [orders](https://developers.planet.com/docs/orders/)
-* [data](https://developers.planet.com/docs/data/) (in progress)
-* [subscriptions](https://developers.planet.com/docs/subscriptions/) (not 
- yet implemented)
+* [data](https://developers.planet.com/docs/data/) (mostly complete)
+* [subscriptions](https://developers.planet.com/docs/subscriptions/) (in progress)
 
 This quickstart focuses on getting started with the CLI to place an order.
 For information on the Python API see the 
@@ -114,32 +163,11 @@ also lots of good information in the docs, in the
 [User Guide](https://planet-sdk-for-python.readthedocs.io/en/latest/guide/#cli)
 and the [CLI Reference](https://planet-sdk-for-python.readthedocs.io/en/latest/cli/).
 
-## Installation
-
-This repository is not yet available on PyPi or any other distribution channels. To 
-install you must [clone this repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
-to your local computer. After you have the repo local just navigate to the root
-directory.
-
-Then you can install locally with [pip](https://pip.pypa.io):
-
-```console
-$ python -m pip install . 
-```
-
-The [--user](https://pip.pypa.io/en/stable/user_guide/#user-installs)
-flag is highly recommended for those new to pip.
-
-The Planet SDK for Python requires Python 3.7+.
-
-After installation you should be able to use the command-line interface. Just type
-`planet` into the command-line and the usage and options should appear. If it doesn't 
-work don't hesitate to ask for help in the [discussions](https://github.com/planetlabs/planet-client-python/discussions/categories/q-a)
-
 ## Authentication
 
 Planet's APIs require an account for use.
-[Sign up here](https://www.planet.com/explorer/?signup).
+[Sign up here](https://www.planet.com/signup/) or if you are developer try the 
+[developer trial](https://developers.planet.com/devtrial/).
 
 ## Development
 

docs/venv-tutorial.md

@@ -0,0 +1,125 @@
+## Getting started with venv & Planet SDK
+
+There are lots of great resources online about virtual environments for python.
+This tutorial is aimed at users of the Planet SDK who have little or no experience
+with virtual environments but want to be early users of v2 (and still use
+their v1 when testing).
+
+### Conda vs venv
+
+There are two main options in the Python world for virtual environments:
+
+* [venv](https://docs.python.org/3/library/venv.html)
+* [conda](https://conda.io)
+
+Both are great options. Venv is built into python (version 3.3 and above), so if you've got python
+then it's already there. Conda does a bit 'more', as venv just works for python, while conda
+creates virtual environments for all libraries and languages (but was designed for python). We
+recommend venv, as [GDAL](https://gdal.org/), arguably the most useful geospatial command-lines,
+can sometimes be a pain with Conda. And our releases are not (yet) targeting conda packaging.
+
+### venv pre-requisites
+
+The main pre-requisite for venv is that you have Python 3.3 and above. To check your python
+version type:
+
+```console
+ $ python --version
+```
+
+ If you installed on Windows or Linux you most likely have python 3. Mac OS ships by default with
+ python 2, so you'll need to install python 3. 
+
+#### Installing Python 3 on a Mac.
+
+ Our recommended route is to install [homebrew](https://brew.sh/). To do that you just run the 
+ following on your command-line:
+
+```console
+ $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+After it download and installs you just run:
+
+```console
+ $ brew install python
+```
+
+ That will set up a command called `python3` that you can use to call python3.
+
+### Setting your venvs
+
+It's good to read up on how venv works, we recommend 
+[this tutorial](https://www.dataquest.io/blog/a-complete-guide-to-python-virtual-environments/)
+to get a solid understanding.
+
+To be able to work with both the v1 stable and v2 pre-release we recommend setting up 2 virtual enviroments.
+A good place to put them is in a .venv directory.
+
+```console
+ $ mkdir ~/.venv
+ $ cd ~/.venv
+```
+
+ Then you'll want to create a venv for v1 and v2. First create the
+ v1 virtual environment with:
+
+```console
+  $ python3 -m venv ~/.venv/planet-v1
+```
+
+ Then you can activate on a mac or linux with:
+
+```console
+ $ source ~/.venv/planet-v1/bin/activate
+```
+
+and on windows with:
+
+```console
+  $ planet-v1\Scripts\activate.bat
+```
+
+Then you'll be in your new virtual environment. If you already have v1 installed
+it will likely work. But you can install it with:
+
+```console
+  $ pip install planet
+```
+
+Run `planet --version` to check which version it is. If you don't see a v1 then you may
+need to adjust your path (ask in [discussions](https://github.com/planetlabs/planet-client-python/discussions)
+if you're having trouble, and we can add more info here).
+
+Then you'll want to deactivate, and set up v2:
+
+```console
+ $ deactivate
+```
+
+ Takes you out of the virtual environment, to your base install.
+
+ Then set up v2, like you did v1:
+
+```console
+ $ python3 -m venv ~/.venv/planet-v2
+```
+
+And activate the same way. Then install as instructed in [the readme](../README.md#installation).
+
+### Working with virtual environments
+
+It's easy to switch in and out of the virtual environments, just `activate` and `deactivate`. You can 
+install additional tools with pip on each. The core directories and files remain the same, so you can 
+use both v1 and v2 in the same directory. You can even work with them side by side, just open two 
+different terminal windows, and activate v1 in one, and v2 in the other.
+
+You should see a different command-line prompt for each, to easily tell which one you are in:
+
+```console
+ $ (planet-v1) user@computer ~ $
+ ```
+
+Note that non-python programs (like from node, or C/C++) will be available in both environments. If you want
+to manage those in a virtual environment then Conda is the way to go, or even full on [docker](https://www.docker.com/)
+containers.