Final steps for releasing v3.6.1 (#126)

* changelog

* update the readme a bit

* versioning

* changelog and version

* 3

* wheels note

* api note

* Notes from Nick

* no deps

* words

* move stuff around

* unit to uint

* conventional usage: `## Usage`

* the

* omit needless words!

* nix they

* update release date

CHANGELOG.md

@@ -13,9 +13,15 @@ avoid adding features or APIs which do not map onto the
 [H3 core API](https://uber.github.io/h3/#/documentation/api-reference/).
 
 
-## [3.6.1] - **Unreleased**
+## [3.6.1] - 2020-05-29
 
 - Switch to Cython wrapper implementation
+- Pre-built wheels on PyPI for Linux/Mac/Windows
+- Provide multiple APIs:
+    + `h3.api.basic_str`
+    + `h3.api.basic_int`
+    + `h3.api.numpy_int`
+    + `h3.api.memview_int`
 
 
 ## [3.4.3] - 2019-04-18

readme.md

@@ -3,7 +3,7 @@
 # h3-py
 
 [![PyPI version](https://badge.fury.io/py/h3.svg)](https://badge.fury.io/py/h3)
-[![version](https://img.shields.io/badge/h3-v3.6.1-blue.svg)](https://github.com/uber/h3/releases/tag/v3.6.1)
+[![version](https://img.shields.io/badge/h3-v3.6.3-blue.svg)](https://github.com/uber/h3/releases/tag/v3.6.3)
 [![version](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 
 [![CI-linux](https://github.com/uber/h3-py/workflows/CI-linux/badge.svg)](https://github.com/uber/h3-py/actions)
@@ -17,53 +17,174 @@ Python bindings for the
 For API reference, please see the
 [H3 Documentation](https://h3geo.org/).
 
-**NOTE: This version (v.3.6.1) corresponds to the new Cython
-bindings, which will replace the old bindings (v3.4.3).
-This version is not yet published to PyPI.**
+**New in v3.6.1**: We upload pre-built
+[Python Wheels to PyPI](https://pypi.org/project/h3) for Linux/Mac/Windows,
+which should avoid many previous installation issues.
 
 
 ## Install from PyPI
 
-TODO: instructions for installing from pre-built wheels
+`pip install h3`
 
+## Usage
 
-## Install from GitHub
+```python
+>>> import h3
+>>> lat, lng = 0, 0
+>>> resolution = 0
+>>> h3.geo_to_h3(lat, lng, resolution)
+'8075fffffffffff'
+```
+
+## Example gallery
 
-You need to have `cc`, `make`, `cmake`, and `git` in your `$PATH` when installing this package.
+Browse [a collection of example notebooks](https://github.com/uber/h3-py-notebooks),
+and if you have examples or visualizations of your own, please feel free to contribute!
+
+We also have a simple [walkthrough of the API](https://nbviewer.jupyter.org/github/uber/h3-py-notebooks/blob/master/Usage.ipynb).
+For more information, please see the [H3 Documentation](https://h3geo.org/).
 
-Then run:
 
-`pip install git+https://github.com/uber/h3-py.git`
+## APIs
 
-Try the library with:
+We provide multiple APIs in `h3-py`.
+All APIs have the same set of functions, but differ
+in their input/output formats.
+
+### `h3.api.basic_str`
+
+H3 indexes are represented as Python `str`s, using `list` and `set` for collections.
+
+This is the default API provided when you `import h3`.
+That is, `import h3.api.basic_str as h3` and `import h3`
+are basically equivalent.
 
 ```python
 >>> import h3
->>> h3.geo_to_h3(0, 0, 0)
+>>> h = h3.geo_to_h3(0, 0, 0)
+>>> h
 '8075fffffffffff'
+
+>>> h3.hex_ring(h, 1)
+{'8055fffffffffff',
+ '8059fffffffffff',
+ '807dfffffffffff',
+ '8083fffffffffff',
+ '8099fffffffffff'}
+```
+
+### `h3.api.basic_int`
+
+H3 indexes are represented as Python `int`s, using `list` and `set` for collections.
+
+```python
+>>> import h3.api.basic_int as h3
+>>> h = h3.geo_to_h3(0, 0, 0)
+>>> h
+578536630256664575
+
+>>> h3.hex_ring(h, 1)
+{577973680303243263,
+ 578044049047420927,
+ 578677367745019903,
+ 578782920861286399,
+ 579169948954263551}
 ```
 
+### `h3.api.numpy_int`
+
+H3 indexes are represented as `uint64`s, using `numpy.ndarray`
+for collections.
 
-## NumPy support
+The intention is for this API to be faster and more memory-efficient by
+not requiring `int` to `str` conversion and by using
+no-copy `numpy` arrays instead of Python `list`s and `set`s.
 
-`h3` has no runtime dependencies on other libraries, so a standard
+```python
+>>> import h3.api.numpy_int as h3
+>>> h = h3.geo_to_h3(0, 0, 0)
+>>> h
+578536630256664575
+
+>>> h3.hex_ring(h, 1)
+array([578782920861286399, 578044049047420927, 577973680303243263,
+       578677367745019903, 579169948954263551], dtype=uint64)
+```
+
+Note that `h3` has no runtime dependencies on other libraries, so a standard
 `pip install` will install no additional libraries.
+However, `h3.api.numpy_int` requires `numpy`. To have `numpy` installed (if it isn't already) along
+with `h3`, run `pip install h3[numpy]`.
 
-The optional `h3.api.numpy_int` API requires `numpy`.
-To have `numpy` installed (if it isn't already) along
-with `h3`, run:
 
-`pip install git+https://github.com/uber/h3-py.git[numpy]`
+### `h3.api.memview_int`
 
-or
+H3 indexes are represented as `uint64`s, using Python
+[`memoryview` objects](https://docs.python.org/dev/library/stdtypes.html#memoryview)
+for collections.
 
-`pip install git+https://github.com/uber/h3-py.git[all]`
+This API has the same benefits as `numpy_int`, except it uses
+(the less well-known but dependency-free) `memoryview`.
 
+```python
+>>> import h3.api.memview_int as h3
+>>> h = h3.geo_to_h3(0, 0, 0)
+>>> h
+578536630256664575
+
+>>> mv = h3.hex_ring(h, 1)
+>>> mv
+<MemoryView of 'array' at 0x11188c710>
+
+>>> mv[0]
+578782920861286399
+
+>>> list(mv)
+[578782920861286399,
+ 578044049047420927,
+ 577973680303243263,
+ 578677367745019903,
+ 579169948954263551]
+```
 
-## Example gallery
+When using this API with `numpy`, note that `numpy.array` **creates a copy**
+of the data, while `numpy.asarray` **does not create a copy** and the
+result points to the same memory location as the `memoryview` object.
 
-Browse [a collection of example notebooks](https://github.com/uber/h3-py-notebooks),
-and if you have examples or visualizations of your own, please feel free to contribute!
+Continuing from the example above,
 
-We also have a simple [walkthrough of the API](https://nbviewer.jupyter.org/github/uber/h3-py-notebooks/blob/master/Usage.ipynb).
-For more information, please see the [H3 Documentation](https://h3geo.org/).
+```python
+>>> mv = h3.hex_ring(h, 1)
+>>> a = np.array(mv)
+>>> mv[0] = 0
+>>> a
+array([578782920861286399, 578044049047420927, 577973680303243263,
+       578677367745019903, 579169948954263551], dtype=uint64)
+
+>>> mv = h3.hex_ring(h, 1)
+>>> a = np.asarray(mv)
+>>> mv[0] = 0
+>>> a
+array([                 0, 578044049047420927, 577973680303243263,
+       578677367745019903, 579169948954263551], dtype=uint64)
+```
+
+## Versioning
+
+`h3-py` wraps the [H3 Core Library](https://github.com/uber/h3),
+which is written in C.
+Both projects employ [semantic versioning](https://semver.org/),
+with versions taking the form `X.Y.Z`.
+
+`h3-py` will match the C library
+in *major* and *minor* numbers (`X.Y`), but may be different on the
+*patch* (`Z`) number.
+
+Use `h3.versions()` to see the version numbers for both
+`h3-py` and the C library. For example,
+
+```python
+>>> import h3
+>>> h3.versions()
+{'c': '3.6.3', 'python': '3.6.1'}
+```

src/h3/_version.py

@@ -1,11 +1,11 @@
-__version__ = '3.6.1a5'
+__version__ = '3.6.1'
 __description__ = 'Hierarchical hexagonal geospatial indexing system'
 __url__ = 'https://github.com/uber/h3-py'
 __license__ = "Apache 2.0 License"
 __author__ = 'Uber Technologies'
 __author_email__ = 'AJ Friend <[email protected]>'
 __classifiers__ = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "Intended Audience :: Science/Research",
     "License :: OSI Approved :: Apache Software License",