Skip to content

Commit 671c221

Browse files
sgilliessgillies
committed
Merge branch 'main' of github.com:planetlabs/planet-client-python into main
2 parents 1f29c0f + a0ff3c7 commit 671c221

File tree

2 files changed

+182
-29
lines changed

2 files changed

+182
-29
lines changed

‎README.md

+57-29
Original file line numberDiff line numberDiff line change
@@ -17,17 +17,67 @@ The Planet SDK for Python is in 'pre-release' stages, working towards an
1717
initial release around July. Active development is tracked in the [Planet SDK
1818
for Python Project](https://github.com/planetlabs/planet-client-python/projects/2).
1919
The initial release will support Orders, Data and Subscription API's in the
20-
command-line interface, with corresponding Python libraries. We expect 'beta'
21-
milestones to be released in some form for each of the API's. After the
20+
command-line interface, with corresponding Python libraries. After the
2221
initial July release there will be additional work to support the remaining
2322
Planet API's ([analytics](https://developers.planet.com/docs/analytics/),
2423
[basemaps](https://developers.planet.com/docs/basemaps/) and
2524
[tasking](https://developers.planet.com/docs/tasking/)).
2625

26+
## Installation
27+
28+
There are two options for installation: installing from PyPi or installing from source.
29+
30+
Be aware that using either route will by default update your `planet` command-line and
31+
python library to v2, so you will no longer be able to use v1. As v2 is in a pre-release
32+
stage, with not all functionality implemented, we strongly recommend installing it in a
33+
virtual environment - either [venv](https://python.land/virtual-environments/virtualenv)
34+
or [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html).
35+
If you've never worked with either then check out our [getting started with venv and Planet
36+
SDK](docs/venv-tutorial.md). For anyone planning to contribute to the SDK the instructuctions
37+
are a bit different, see the [testing section of CONTRIBUTING.md](https://github.com/planetlabs/planet-client-python/blob/main/CONTRIBUTING.md#testing).
38+
39+
Both installation routes use [pip](https://pip.pypa.io/en/stable/getting-started/), Python's
40+
package installer.
41+
42+
The [--user](https://pip.pypa.io/en/stable/user_guide/#user-installs)
43+
flag is highly recommended for those new to pip.
44+
45+
The Planet SDK for Python requires Python 3.7+.
46+
47+
### Installing from PyPi
48+
49+
(Note this is not yet working, as the pre-release has not happened yet, but will soon)
50+
51+
To get version 2 of the Planet SDK you just use pip with the `--pre` command:
52+
53+
```console
54+
$ pip install planet --pre
55+
```
56+
57+
### Installing from source
58+
59+
To install you must [clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
60+
the [planet-client-python](https://github.com/planetlabs/planet-client-python) repository
61+
to your local computer. After you have the repo local just navigate to the root
62+
directory, where this readme lives.
63+
64+
Then you can install locally with pip:
65+
66+
```console
67+
$ pip install .
68+
```
69+
70+
### Confirming its working
71+
72+
After installation you should be able to use the command-line interface. Just type
73+
`planet` into the command-line and the usage and options should appear. If it doesn't
74+
work don't hesitate to ask for help in the [discussions](https://github.com/planetlabs/planet-client-python/discussions/categories/q-a)
75+
forum.
76+
2777
## Documentation
2878

2979
Documentation is currently [hosted online](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/)
30-
It should be considered 'in progress', with many updated to come. It can also
80+
It should be considered 'in progress', with many updates to come. It can also
3181
be built and hosted locally (see [CONTRIBUTING.md](CONTRIBUTING.md)) or can be
3282
read from source in the `[docs](docs/)` directory.
3383

@@ -37,9 +87,8 @@ The Planet SDK includes both a Python API and a command-line interface (CLI)
3787
to make use of the following Planet APIs:
3888

3989
* [orders](https://developers.planet.com/docs/orders/)
40-
* [data](https://developers.planet.com/docs/data/) (in progress)
41-
* [subscriptions](https://developers.planet.com/docs/subscriptions/) (not
42-
yet implemented)
90+
* [data](https://developers.planet.com/docs/data/) (mostly complete)
91+
* [subscriptions](https://developers.planet.com/docs/subscriptions/) (in progress)
4392

4493
This quickstart focuses on getting started with the CLI to place an order.
4594
For information on the Python API see the
@@ -114,32 +163,11 @@ also lots of good information in the docs, in the
114163
[User Guide](https://planet-sdk-for-python.readthedocs.io/en/latest/guide/#cli)
115164
and the [CLI Reference](https://planet-sdk-for-python.readthedocs.io/en/latest/cli/).
116165

117-
## Installation
118-
119-
This repository is not yet available on PyPi or any other distribution channels. To
120-
install you must [clone this repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
121-
to your local computer. After you have the repo local just navigate to the root
122-
directory.
123-
124-
Then you can install locally with [pip](https://pip.pypa.io):
125-
126-
```console
127-
$ python -m pip install .
128-
```
129-
130-
The [--user](https://pip.pypa.io/en/stable/user_guide/#user-installs)
131-
flag is highly recommended for those new to pip.
132-
133-
The Planet SDK for Python requires Python 3.7+.
134-
135-
After installation you should be able to use the command-line interface. Just type
136-
`planet` into the command-line and the usage and options should appear. If it doesn't
137-
work don't hesitate to ask for help in the [discussions](https://github.com/planetlabs/planet-client-python/discussions/categories/q-a)
138-
139166
## Authentication
140167

141168
Planet's APIs require an account for use.
142-
[Sign up here](https://www.planet.com/explorer/?signup).
169+
[Sign up here](https://www.planet.com/signup/) or if you are developer try the
170+
[developer trial](https://developers.planet.com/devtrial/).
143171

144172
## Development
145173

‎docs/venv-tutorial.md

+125
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
## Getting started with venv & Planet SDK
2+
3+
There are lots of great resources online about virtual environments for python.
4+
This tutorial is aimed at users of the Planet SDK who have little or no experience
5+
with virtual environments but want to be early users of v2 (and still use
6+
their v1 when testing).
7+
8+
### Conda vs venv
9+
10+
There are two main options in the Python world for virtual environments:
11+
12+
* [venv](https://docs.python.org/3/library/venv.html)
13+
* [conda](https://conda.io)
14+
15+
Both are great options. Venv is built into python (version 3.3 and above), so if you've got python
16+
then it's already there. Conda does a bit 'more', as venv just works for python, while conda
17+
creates virtual environments for all libraries and languages (but was designed for python). We
18+
recommend venv, as [GDAL](https://gdal.org/), arguably the most useful geospatial command-lines,
19+
can sometimes be a pain with Conda. And our releases are not (yet) targeting conda packaging.
20+
21+
### venv pre-requisites
22+
23+
The main pre-requisite for venv is that you have Python 3.3 and above. To check your python
24+
version type:
25+
26+
```console
27+
$ python --version
28+
```
29+
30+
If you installed on Windows or Linux you most likely have python 3. Mac OS ships by default with
31+
python 2, so you'll need to install python 3.
32+
33+
#### Installing Python 3 on a Mac.
34+
35+
Our recommended route is to install [homebrew](https://brew.sh/). To do that you just run the
36+
following on your command-line:
37+
38+
```console
39+
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
40+
```
41+
42+
After it download and installs you just run:
43+
44+
```console
45+
$ brew install python
46+
```
47+
48+
That will set up a command called `python3` that you can use to call python3.
49+
50+
### Setting your venvs
51+
52+
It's good to read up on how venv works, we recommend
53+
[this tutorial](https://www.dataquest.io/blog/a-complete-guide-to-python-virtual-environments/)
54+
to get a solid understanding.
55+
56+
To be able to work with both the v1 stable and v2 pre-release we recommend setting up 2 virtual enviroments.
57+
A good place to put them is in a .venv directory.
58+
59+
```console
60+
$ mkdir ~/.venv
61+
$ cd ~/.venv
62+
```
63+
64+
Then you'll want to create a venv for v1 and v2. First create the
65+
v1 virtual environment with:
66+
67+
```console
68+
$ python3 -m venv ~/.venv/planet-v1
69+
```
70+
71+
Then you can activate on a mac or linux with:
72+
73+
```console
74+
$ source ~/.venv/planet-v1/bin/activate
75+
```
76+
77+
and on windows with:
78+
79+
```console
80+
$ planet-v1\Scripts\activate.bat
81+
```
82+
83+
Then you'll be in your new virtual environment. If you already have v1 installed
84+
it will likely work. But you can install it with:
85+
86+
```console
87+
$ pip install planet
88+
```
89+
90+
Run `planet --version` to check which version it is. If you don't see a v1 then you may
91+
need to adjust your path (ask in [discussions](https://github.com/planetlabs/planet-client-python/discussions)
92+
if you're having trouble, and we can add more info here).
93+
94+
Then you'll want to deactivate, and set up v2:
95+
96+
```console
97+
$ deactivate
98+
```
99+
100+
Takes you out of the virtual environment, to your base install.
101+
102+
Then set up v2, like you did v1:
103+
104+
```console
105+
$ python3 -m venv ~/.venv/planet-v2
106+
```
107+
108+
And activate the same way. Then install as instructed in [the readme](../README.md#installation).
109+
110+
### Working with virtual environments
111+
112+
It's easy to switch in and out of the virtual environments, just `activate` and `deactivate`. You can
113+
install additional tools with pip on each. The core directories and files remain the same, so you can
114+
use both v1 and v2 in the same directory. You can even work with them side by side, just open two
115+
different terminal windows, and activate v1 in one, and v2 in the other.
116+
117+
You should see a different command-line prompt for each, to easily tell which one you are in:
118+
119+
```console
120+
$ (planet-v1) user@computer ~ $
121+
```
122+
123+
Note that non-python programs (like from node, or C/C++) will be available in both environments. If you want
124+
to manage those in a virtual environment then Conda is the way to go, or even full on [docker](https://www.docker.com/)
125+
containers.

0 commit comments

Comments
 (0)