Merge pull request #100 from planetlabs/v1

V1

Author: ischneider

.travis.yml

@@ -5,11 +5,9 @@ python:
 cache:
   directories:
     - $HOME/.cache/pip
+before_install:
+  - pip install --upgrade pytest
 install:
-  - "pip install flake8"
-  - "pip install -e .[dev]"
-before_script:
-  - flake8 planet tests
+  - pip install -e .[dev]
 script:
-  - "py.test"
-
+  - make check html-docs

CHANGES.txt

@@ -1,3 +1,8 @@
+1.0.0 (2017-04-01) Code name: no-joke
+-------------------------------------
+- Remove V0 API support
+- Initial V1 Data API support
+
 0.0.6 (2016-02-17)
 ------------------
 - Support for 'aoi_id' (saved geometry) queries in 'search' command.

Makefile

@@ -1,16 +1,24 @@
 GH_PAGES_SOURCES = planet docs Makefile
 
 check:
-	py.test tests
+	py.test --doctest-modules planet tests
 	flake8 planet tests
 
+coverage:
+	py.test --doctest-modules --cov planet --cov-report=html:htmlcov tests planet/api
+
 pex:
-	pex .  -o dist/planet -m planet.scripts:cli
+	# disable-cache seemed required or the older version would be used
+	pex . -o dist/planet -e planet.scripts:main --disable-cache
 
 html-docs:
 	python docs/source/generate.py
 	$(MAKE) -C docs clean html
 
+auto-docs:
+	which sphinx-autobuild || ( echo 'PLEASE INSTALL sphinx-autobuild: pip install sphinx-autobuild'; exit 1 )
+	sphinx-autobuild --watch planet docs/source docs/build/html
+
 docs-zip: html-docs
 	cp -a docs/build/html planet-docs
 	zip -m -r dist/planet-docs.zip planet-docs

README.rst

@@ -2,28 +2,47 @@
 Planet API Client
 =================
 
-**PRE-ALPHA SOFTWARE - MAY CHANGE**
-
-Initial, incomplete, strawman effort at a Python client to Planet's public API.
+Python client library and CLI for Planet's public API.
 
 .. image:: https://travis-ci.org/planetlabs/planet-client-python.svg?branch=master
    :target: https://travis-ci.org/planetlabs/planet-client-python
 
 
+Installation
+------------
+
+Via pip::
+
+    pip install planet
+
+A PEX executable (Windows not supported) and source releases are
+`here <https://github.com/planetlabs/planet-client-python/releases/latest>`__.
+
+
 Documentation
 -------------
 
-`https://planetlabs.github.io/planet-client-python/index.html <https://planetlabs.github.io/planet-client-python/index.html>`__
+Online documentation: `https://planetlabs.github.io/planet-client-python/index.html <https://planetlabs.github.io/planet-client-python/index.html>`__
 
+Documentation is also provided for download `here <https://github.com/planetlabs/planet-client-python/releases/latest>`__.
 
-Installation
-------------
 
-Executable CLI releases and documentation are `here <https://github.com/planetlabs/planet-client-python/releases/latest>`__.
+Development
+-----------
 
 To develop with or use the library in your own projects, see the `wiki <https://github.com/planetlabs/planet-client-python/wiki>`__.
 
 
+API Key
+-------
+
+The API requires an account for use. `Signup here <https://www.planet.com/explorer/?signup>`__.
+
+This can be provided via the environment variable `PL_API_KEY` or the flag `-k` or `--api-key`.
+
+Using `planet init` your account credentials (login/password) can be used to obtain the api key.
+
+
 Example CLI Usage
 -----------------
 
@@ -35,25 +54,10 @@ Basics and help::
 
     planet
 
-OR specific command help::
-
-    planet search --help
-
-An API key is `required <https://www.planet.com/explorers/>`__.
+The CLI provides access to the `data API <https://www.planet.com/docs/reference/data-api/>`__ ::
 
-This can be provided via the environment variable `PL_API_KEY` or the flag `-k` or `--api-key`. Using the `planet init` the username and password can be used and saved instead.
+    planet data
 
-Examples
-~~~~~~~~
-
-Get a visual ortho scene by id (writes to working directory)::
-
-    planet download 20150825_180952_1_0b07
-
-Get scene metadata by id (and pretty print)::
-
-    planet metadata -pp 20150825_180952_1_0b07
-
-Get a list of all mosaics::
+OR specific command help::
 
-    planet mosaics
+    planet data download --help

docs/source/_static/custom.css

@@ -0,0 +1,53 @@
+div.body, body {
+  background-color: #f2f2f2;
+}
+
+.documentwrapper {
+  min-height: 80vh;
+}
+
+pre {
+  background-color: #191919;
+  word-wrap: break-word;
+  white-space: pre-wrap;
+}
+pre span {
+  font-weight: 800;
+}
+
+.highlight-text .highlight pre,
+.highlight-bash .highlight,
+.highlight-bash .highlight .m,
+.highlight-bash .highlight .s2,
+.highlight-python .highlight .n,
+.highlight-python .highlight .p,
+.highlight-default .highlight .n,
+.highlight-default .highlight .p
+{
+  color: #f2f2f2;
+}
+
+.highlight-bash .highlight .c1,
+.highlight-python .highlight .c1,
+.highlight-python .highlight .s1,
+.highlight-default .highlight .c1,
+.highlight-default .highlight .s1
+{
+  color: #b5bd68;
+}
+
+.highlight-python .highlight .k,
+.highlight-python .highlight .kn,
+.highlight-python .highlight .ow,
+.highlight-default .highlight .k,
+.highlight-default .highlight .kn,
+.highlight-default .highlight .ow,
+.highlight-default .highlight .go
+{
+  color: #b294bb;
+}
+
+.highlight-javascript .highlight .p
+{
+  color: #f2f2f2;
+}

docs/source/_static/logo.png

@@ -1,13 +1,16 @@
-pblue = '#008fd5'
-sblue = '#18aae6'
-pgrey = ' #666666'
+pgrey = '#191919'
+pprimary_dark = '#006c72'
+
 
 html_theme_options = {
-    'logo': 'logo.png',
-    'body_text': '#000',
+    'logo': 'logo.svg',
+    'body_text': 'lighten(black, 20%)',
     'gray_1': pgrey,
-    'link': pblue,
-    'sidebar_search_button': pblue,
-    'sidebar_link': pblue,
+    'link': pgrey,
+    'font_family': 'Helvetica, sans-serif',
+    'font_size': '14px',
+    'sidebar_search_button': pprimary_dark,
+    'sidebar_link': pprimary_dark,
     'github_button': 'false',
-}
+    'fixed_sidebar': True,
+}

docs/source/_static/logo.svg

@@ -8,7 +8,7 @@ Everything needed is provided in the `api` module.
 
 .. code-block:: python
 
-   from planet import api
+    from planet import api
 
 Creating a Client
 -----------------
@@ -17,63 +17,39 @@ Without any arguments, the Client will look for an API_KEY using the operating s
 
 .. code-block:: python
 
-   client = api.Client()
+    client = api.ClientV1()
 
-Searching for Scenes
---------------------
+Searching for Items
+-------------------
 
-Get the most recent Planet scenes.
+A common case is searching for items in an AOI.
 
 .. code-block:: python
 
-   body = client.get_scenes_list(scene_type='ortho')
+    aoi = {
+      "type": "Polygon",
+      "coordinates": [
+        [
+          [-122.54, 37.81],
+          [-122.38, 37.84],
+          [-122.35, 37.71],
+          [-122.53, 37.70],
+          [-122.54, 37.81]
+        ]
+      ]
+    }
 
-Get the most recent Landsat scenes.
+    # build a filter for the AOI
+    query = api.filters.and_filter(
+      api.filters.geom_filter(aoi)
+    )
+    # we are requesting PlanetScope 4 Band imagery
+    item_types = ['PSScene4Band']
+    request = api.filters.build_search_request(query, item_types)
+    # this will cause an exception if there are any API related errors
+    results = client.quick_search(request)
 
-.. code-block:: python
-
-   body = client.get_scenes_list(scene_type='landsat')
-
-Providing metadata filters in a search.
-
-.. code-block:: python
-
-   filters = { 'sat.id.eq' : '090b'}
-   body = client.get_scenes_list(scene_type='landsat', **filters)
-
-Using an AOI (in WKT in this example) to search.
-
-.. code-block:: python
-
-   wkt = 'POINT(-100 40)'
-   body = client.get_scenes_list(scene_type='landsat', intersects=wkt)
-
-Handling a response `body` - the `get` method returns JSON (in this case, GeoJSON).
-
-.. code-block:: python
-
-   geojson = body.get()
-   # the results are paginated and the total result set count is provided
-   print '%s total results' % geojson['count']
-   # loop over features and print the scene 'id'
-   for f in geojson['features']:
-       print f['id']
-
-Downloading Scenes
-------------------
-
-One or more scenes may be downloaded using scenes ids. Downloading is currently
-done asynchronously and a callback must be provided. The callback will execute
-when data is available.
-
-.. code-block:: python
-
-   scene_ids = ['20150810_235346_0b10', '20150810_235345_0b10']
-   # create a callback that will write scenes to the 'downloads' directory
-   # note - the directory must exist!
-   callback = api.write_to_file('downloads')
-   bodies = client.fetch_scene_geotiffs(ids, callback=callback)
-   # await the completion of the asynchronous downloads, this is where
-   # any exception handling should be performed
-   for b in bodies:
-       b.await()
+    # items_iter returns an iterator over API response pages
+    for item in results.items_iter():
+      # each item is a GeoJSON feature
+      sys.stdout.write('%s\n' % item['id'])

docs/source/alabaster_planet.py

@@ -3,9 +3,6 @@ API
 
 Unless noted here, other classes, modules or functions should be considered 'private' and subject to change.
 
-.. warning::
-   As this project is still in development, there may be reorganization and modifications that cause breaking changes.
-
 .. toctree::
    :maxdepth: 3