diff --git a/README.md b/README.md index 04b3f6aba..31d75d647 100644 --- a/README.md +++ b/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 diff --git a/docs/venv-tutorial.md b/docs/venv-tutorial.md new file mode 100644 index 000000000..08ca4187d --- /dev/null +++ b/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. \ No newline at end of file