From dc519434cf4916dc907eedc171b287fe7f1216fb Mon Sep 17 00:00:00 2001 From: Emmanuel Decitre <590094+decitre@users.noreply.github.com> Date: Thu, 31 Aug 2023 16:27:10 +0200 Subject: [PATCH] README cosmetics (#10) Signed-off-by: Emmanuel Decitre --- README.md | 6 +- docs/developers.md | 90 +++++---- pyproject.toml | 4 +- src/here_search/demo/notebooks/demo.ipynb | 234 +++++++++++----------- 4 files changed, 174 insertions(+), 160 deletions(-) diff --git a/README.md b/README.md index a0822b4..ed2d0da 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ [![Python package](https://github.com/heremaps/here-search-demo/actions/workflows/test.yml/badge.svg)](https://github.com/heremaps/here-search-demo/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/heremaps/here-search-demo/branch/main/graph/badge.svg?token=MVFCS4BUFN)](https://codecov.io/gh/heremaps/here-search-demo) -[![lite-badge](https://jupyterlite.rtfd.io/en/latest/_static/badge.svg)](https://decitre.github.io/here-search-demo-updated/lab/?path=demo.ipynb) +[![lite-badge](https://jupyterlite.rtfd.io/en/latest/_static/badge.svg)][3] # HERE Search notebooks @@ -36,7 +36,7 @@ Use the `here-search-notebooks` script with your HERE API Key: API_KEY="your API key" here-search-notebooks ``` -(More [details][2]) +(Additional [notes][2]) ## License @@ -46,6 +46,6 @@ This project is licensed under the MIT license - see the [LICENSE](./LICENSE) fi [1]: https://developer.here.com/documentation/geocoding-search-api/dev_guide/topics/quick-start.html#get-an-api-key [2]: https://github.com/heremaps/here-search-demo/blob/main/docs/developers.md -[3]: https://decitre.github.io/here-search-demo-updated/lab/?path=demo.ipynb +[3]: https://heremaps.github.io/here-search-demo/lab/?path=demo.ipynb [4]: https://developer.here.com/documentation/geocoding-search-api/dev_guide/index.html [5]: https://www.here.com/get-started/pricing \ No newline at end of file diff --git a/docs/developers.md b/docs/developers.md index 9176758..7d103e1 100644 --- a/docs/developers.md +++ b/docs/developers.md @@ -2,42 +2,47 @@ ### Setup a Notebook Python environment -It is recommended to use a Python virtual environment. The below recipe uses the python batteries `venv` module. - -1. Virtual environment +It is recommended to use a Python virtual environment. In that environment, after a `pip install -e '.[lab]'`, +you will need to install a kernel. For instance with a: ``` - mkdir -p ~/virtualenv; (cd ~/virtualenv; python -m venv search-notebook) - source ~/virtualenv/search-notebook/bin/activate + python -m ipykernel install \ + --prefix $(python -c "import sys; print(sys.prefix)") \ + --name search_demo --display-name "search demo" ``` + +To run the notebook on Jupyter Classic, you will need: -2. Download and install - - For users: ``` - pip -v install here-search-demo + jupyter nbextension enable --py widgetsnbextension + jupyter labextension install @jupyterlab/geojson-extension ``` - For contributors/developers: +### Versioning - ``` - git clone git@github.com:heremaps/here-search-demo.git - cd search-notebook-ext - pip install -e . - ``` +To update the package version, use `bumpver`. For instance: -3. Jupyter config - - ``` - python -m ipykernel install --user --name search_demo --display-name "search demo" ``` + bumpver update --patch --dry -To run the notebook on Jupyter Classic, you will need: - - ``` - jupyter nbextension enable --py widgetsnbextension - jupyter labextension install @jupyterlab/geojson-extension + INFO - fetching tags from remote (to turn off use: -n / --no-fetch) + INFO - Latest version from VCS tag: 0.9.0 + INFO - Working dir version : 0.9.0 + INFO - Old Version: 0.9.0 + INFO - New Version: 0.9.1 + --- docs/developers.md + +++ docs/developers.md + @@ -56,7 +56,7 @@ + ``` + try: + import piplite + - await piplite.install(["ipywidgets==8.1.0", "ipyleaflet==0.17.3", "emfs:here_search_demo-0.9.0-py3-none-any.whl"], keep_going=True) + + await piplite.install(["ipywidgets==8.1.0", "ipyleaflet==0.17.3", "emfs:here_search_demo-0.9.1-py3-none-any.whl"], keep_going=True) + except ImportError: + pass + ``` + (...) ``` ### Test on MacOS / python3.7 @@ -61,11 +66,11 @@ To run the notebook on Jupyter Classic, you will need: ### JupyterLite -[JupyterLite](https://jupyterlite.readthedocs.io/en/latest/) is a JupyterLab distribution that runs entirely in the browser. +[JupyterLite](https://JupyterLite.readthedocs.io/en/latest/) is a JupyterLab distribution that runs entirely in the browser. The Python kernels are backed by [`Pyodide`](https://pyodide.org/en/stable/) running in a Web Worker. Pyodide can not be used outside a browser. But for development purposes (type hints), it is advised to -install its [`py`](https://github.com/pyodide/pyodide/tree/main/src/py) package into the venv used for `search-notebook-ext` +install its [`py`](https://github.com/pyodide/pyodide/tree/main/src/py) package into the venv used for `here-search-demo`. ``` git clone git@github.com:pyodide/pyodide.git @@ -78,37 +83,54 @@ For the Pyodide kernels to be able to use certain packages, those need to be ins ``` try: import piplite - await piplite.install(["ipywidgets==7.7.1", "ipyleaflet==0.17.1", "emfs:here_search_widget-0.8.1-py3-none-any.whl"], keep_going=True) + await piplite.install(["ipywidgets==8.1.0", "ipyleaflet==0.17.3", "emfs:here_search_demo-0.9.0-py3-none-any.whl"], keep_going=True) except ImportError: pass ``` -The version of `here_search_widget` in the `.ipynb` files is updated through `bumpver`. +The version of `here_search_demo` in the `.ipynb` files and this `developers.md` is updated through `bumpver`. #### From a local git clone -To test the jupyterlite page locally, run from the local git repository: +To test the JupyterLite page locally, run from the local git repository: ``` - $(find . -name "lite_run.sh") + $(find . -name "lite-run.sh") ``` Option `-n` only builds the page and does not serve it. -A way to get the sources without git cloning the project is to use the source distribution: +#### Without git clone + +To test the JupyterLite page locally, run in a virtualenv : ``` - pip install --upgrade pip pip download here-search-demo --no-deps --no-binary ":all:" tar xpfz $(find . -name "*.tar.gz") - $(find . -name "lite_run.sh") + $(find . -name "lite-run.sh") ``` -## Inject a lat/lon using geojs.io +#### Clear your browser cache + +By default, JupyterLite uses the [browser storage][1] to store settings and site preferences. +It is sometimes helpful to clear in the browser settings the `127.0.0.1` site data to not use a stale state. + + +### Inject a lat/lon using geojs.io + + +`here-search-demo` facilitates the use of the services from [geojs.io][2] to discover the location behind an IP address. +The `get_lat_lon` helper is not used in the demo widgets. If you need to inject the geolocation associated with +your IP, please check the [GeoJS Terms Of Service][3]. + ``` from here_search.demo.util import get_lat_lon latitude, longitude = await get_lat_lon() ``` + +[1]: https://jupyterlite.readthedocs.io/en/latest/howto/configure/storage.html +[2]: https://www.geojs.io/ +[3]: https://www.geojs.io/tos/ \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 78aed25..b82958a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,4 +23,6 @@ push = true "src/here_search/demo/notebooks/*.ipynb" = [ 'here_search_demo-{version}-py3-none-any.whl' ] - +"docs/developers.md" = [ + 'here_search_demo-{version}-py3-none-any.whl' +] diff --git a/src/here_search/demo/notebooks/demo.ipynb b/src/here_search/demo/notebooks/demo.ipynb index 804e68b..28ae4ea 100644 --- a/src/here_search/demo/notebooks/demo.ipynb +++ b/src/here_search/demo/notebooks/demo.ipynb @@ -1,126 +1,116 @@ { - "cells": [ - { - "cell_type": "code", - "execution_count": null, - "id": "717d9c13-684f-4ef9-8045-09624217caeb", - "metadata": { - "tags": [] - }, - "outputs": [], - "source": [ - "try:\n", - " import piplite\n", - " await piplite.install([\"ipywidgets==8.1.0\", \"ipyleaflet==0.17.3\", \"emfs:here_search_demo-0.9.0-py3-none-any.whl\"], keep_going=True)\n", - " api_key = \"\"\n", - "except ImportError:\n", - " api_key = None" - ] - }, - { - "cell_type": "markdown", - "id": "712c9ba7-62a7-4795-9a5e-7cdfb320bb1c", - "metadata": { - "slideshow": { - "slide_type": "slide" + "metadata": { + "celltoolbar": "Slideshow", + "toc-autonumbering": false, + "toc-showcode": false, + "toc-showmarkdowntxt": false, + "kernelspec": { + "name": "python", + "display_name": "Python (Pyodide)", + "language": "python" }, - "tags": [] - }, - "source": [ - "# OneBoxMap\n", - "\n", - "\n", - "`OneBoxMap` is a demo application showing how [HERE Geocoding and Search](https://developer.here.com/documentation/geocoding-search-api/dev_guide/topics/endpoint-autosuggest-brief.html) following endpoints are meant to be used: `/autosuggest`, `/discover`, `/browse`, `/lookup`\n", - "- The app \n", - " - proposes a single text form to formulate queries\n", - " - displays three buttons with predicted last token text completions\n", - " - displays all API calls in a separate window\n", - " - displays search results on a map and a list\n", - " - supports location-aware language preferences\n", - "
\n", - "- `/autosuggest` endpoint is called for each key-stroke.\n", - " - Follow-up query suggestions are displayed in the list only\n", - " - Location suggestions are displayed in the list and on the map\n", - " - Query term suggestions are displayed in three buttons\n", - " - Selected locations lead to a call to `/lookup` using the location record `id`.\n", - " - Selected query suggestions lead to call to a http GET using the response `href` value\n", - "
\n", - "- `/discover` endpoint is called when a query submission is validated.\n", - " - Validation happens when the [return] key or the button are hit\n", - " - Location results are displayed in the list and on the map\n", - " - Selected results lead to a call to `/lookup` using the location record `id`.\n", - "- `/browse` endpoint is called when a place taxonomy button is selected.\n", - " - Location results are displayed in the list and on the map\n", - " - Selected results lead to a call to `/lookup` using the location record `id`.\n", - "
\n", - "- `/autosuggest`, `/discover` and `/browse` requests are sent using the map center as search center\n", - "- Search requests are cached during the lifetime of the application\n", - "\n", - "\n", - "" - ] + "language_info": { + "codemirror_mode": { + "name": "python", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8" + } }, - { - "cell_type": "code", - "execution_count": null, - "id": "54d57978-5cc6-40f1-aeda-04f49656b719", - "metadata": { - "slideshow": { - "slide_type": "-" + "nbformat_minor": 5, + "nbformat": 4, + "cells": [ + { + "cell_type": "code", + "source": "try:\n import piplite\n await piplite.install([\"ipywidgets==8.1.0\", \"ipyleaflet==0.17.3\", \"emfs:here_search_demo-0.9.0-py3-none-any.whl\"], keep_going=True)\n api_key = \"\"\nexcept ImportError:\n api_key = None", + "metadata": { + "tags": [], + "trusted": true + }, + "execution_count": 1, + "outputs": [], + "id": "717d9c13-684f-4ef9-8045-09624217caeb" }, - "tags": [] - }, - "outputs": [], - "source": [ - "from here_search.demo.widgets.app import OneBoxMap\n", - "app = OneBoxMap(api_key=api_key)\n", - "app.run()" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "691e81e5-064c-44ee-b3df-8e5f18f8f31f", - "metadata": { - "tags": [] - }, - "outputs": [], - "source": [ - "app.__del__()" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "23683ade-0f98-407f-b1ab-a60b2d777760", - "metadata": {}, - "outputs": [], - "source": [] - } - ], - "metadata": { - "celltoolbar": "Slideshow", - "kernelspec": { - "display_name": "search demo", - "language": "python", - "name": "search_demo" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.11.3" - }, - "toc-autonumbering": false, - "toc-showcode": false, - "toc-showmarkdowntxt": false - }, - "nbformat": 4, - "nbformat_minor": 5 -} + { + "cell_type": "markdown", + "source": "# OneBoxMap\n\n`OneBoxMap` is a demo application showing how [HERE Geocoding and Search](https://developer.here.com/documentation/geocoding-search-api/dev_guide/topics/endpoint-autosuggest-brief.html) following endpoints are meant to be used: `/autosuggest`, `/discover`, `/browse`, `/lookup`.", + "metadata": { + "slideshow": { + "slide_type": "slide" + }, + "tags": [] + }, + "id": "712c9ba7-62a7-4795-9a5e-7cdfb320bb1c" + }, + { + "cell_type": "code", + "source": "from here_search.demo.widgets.app import OneBoxMap\napp = OneBoxMap(api_key=api_key)\napp.run()", + "metadata": { + "slideshow": { + "slide_type": "-" + }, + "tags": [], + "trusted": true + }, + "execution_count": 2, + "outputs": [ + { + "output_type": "display_data", + "data": { + "text/plain": "HTML(value='')", + "application/vnd.jupyter.widget-view+json": { + "version_major": 2, + "version_minor": 0, + "model_id": "22bd278b42354b4aa1bcec94c4562995" + } + }, + "metadata": {} + }, + { + "execution_count": 2, + "output_type": "execute_result", + "data": { + "text/plain": "OneBoxMap(children=(HBox(children=(ResponseMap(center=[52.51604, 13.37691], controls=(AttributionControl(optio…", + "application/vnd.jupyter.widget-view+json": { + "version_major": 2, + "version_minor": 0, + "model_id": "3f7dcd63cc594d079f01bba55c697c45" + } + }, + "metadata": {} + } + ], + "id": "54d57978-5cc6-40f1-aeda-04f49656b719" + }, + { + "cell_type": "code", + "source": "if False: # change to True to deleted the app resources\n app.__del__()", + "metadata": { + "tags": [], + "trusted": true + }, + "execution_count": 3, + "outputs": [], + "id": "691e81e5-064c-44ee-b3df-8e5f18f8f31f" + }, + { + "cell_type": "markdown", + "source": "Features:\n\n- The app \n - proposes a single text form to formulate queries\n - displays three buttons with predicted last token text completions\n - displays all API calls in a separate window\n - displays search results on a map and a list\n - supports location-aware language preferences\n
\n- `/autosuggest` endpoint is called for each key-stroke.\n - Follow-up query suggestions are displayed in the list only\n - Location suggestions are displayed in the list and on the map\n - Query term suggestions are displayed in three buttons\n - Selected locations lead to a call to `/lookup` using the location record `id`.\n - Selected query suggestions lead to call to a http GET using the response `href` value\n
\n- `/discover` endpoint is called when a query submission is validated.\n - Validation happens when the [return] key or the button are hit\n - Location results are displayed in the list and on the map\n - Selected results lead to a call to `/lookup` using the location record `id`.\n- `/browse` endpoint is called when a place taxonomy button is selected.\n - Location results are displayed in the list and on the map\n - Selected results lead to a call to `/lookup` using the location record `id`.\n
\n- `/autosuggest`, `/discover` and `/browse` requests are sent using the map center as search center\n- Search requests are cached during the lifetime of the application\n\n\n", + "metadata": {}, + "id": "9924f7b8-e3e2-44ac-9ce2-dfca00211104" + }, + { + "cell_type": "code", + "source": "", + "metadata": {}, + "execution_count": null, + "outputs": [], + "id": "f36fb223-235c-4aaa-8fc1-066423a0fc72" + } + ] +} \ No newline at end of file