Metadata-Version: 2.1
Name: here-nagini
Version: 1.7
Summary: Python SDK for HERE Services, especially HERE platform
Home-page: https://here.com
Author: HERE Global B.V. and its affiliate(s)
License: HERE Proprietary License
Project-URL: Source, ssh://git@main.gitlab.in.here.com:3389/sdk/nagini-python-sdk.git
Keywords: HERE Technologies
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Dist: aiohttp (==3.6.2)
Requires-Dist: contextily (==1.0rc2)
Requires-Dist: deprecated
Requires-Dist: fastparquet (==0.3.3)
Requires-Dist: geographiclib
Requires-Dist: geopandas
Requires-Dist: ipykernel
Requires-Dist: ipyleaflet
Requires-Dist: matplotlib
Requires-Dist: pandas
Requires-Dist: protobuf
Requires-Dist: pyarrow
Requires-Dist: pyhocon
Requires-Dist: requests
Requires-Dist: requests-oauthlib
Requires-Dist: selenium
Requires-Dist: shapely
Requires-Dist: timeout-decorator
Requires-Dist: descartes
Requires-Dist: sidecar

Here Nagini — Python SDK for HERE Services
==========================================

.. contents:: **Table of Contents**
  :depth: 3

Introduction
------------

This repository contains the code for the project under the codename *Nagini*,
the emerging Python SDK intended primarily for HERE_ platform.
It also includes some little helpers to access other useful services,
like HERE Location Services.

The goal of this project is to provide an easier, more accessible way for using
HERE platform from the perspective of data scientists performing analytical tasks,
ideally with only a few lines of code and in a friendly, exploratory notebook
environment like Jupyter_.

The project is maintained by the newly formed HERE PySDK team (created in early
January 2019) with most members working in Berlin, and Emmanuel Argogast as
project leader.


Deliverables
------------

The Here-Nagini project will deliver a first release by the end of March 2019. The
target group will be internal users at HERE and selected clients outside HERE.
At this point there will be code ready to clone from this repository and a
Docker image containing this package as well as an interface to parts of the
HERE Common Location Library which can be installed using:

.. code-block:: console

    docker image rm -f docker-local.artifactory.in.here.com/olp/olp-pysdk

    docker run -p 8888:8888 -p 25333:25333 -e JUPYTER=YES -v $HOME/.here/:/home/nagini/.here/ docker-local.artifactory.in.here.com/olp/olp-pysdk

Formally released packages will follow later.


Directory layout
----------------

This is a rough overview of the top-level directory structure inside the
repository:

::

    +- docs             # documentation for the internal API.
    |
    +- examples         # examples, mini milestones, notebooks.
    |
    +- nagini
    |  |
    |  +- core
    |  |  |
    |  |  +- hls        # HLS
    |  |  |
    |  |  +- olp        # OLP
    |  |
    |  +- utils         # utilities and helpers.
    |
    +- tests
       |
       +- assets        # assets used in the tests
       |
       +- integration   # integration tests.
       |
       +- performance   # performance tests.
       |
       +- unit          # unit tests.


Development setup for end users
-------------------------------

Prerequisites
.............

Make sure you have a working installation of Python 3.6+. All commands below
are to be entered at a command prompt in the root directory of the unpacked
Here-Nagini repository.


Install instructions
....................

Python packages are usually installed via Pip_ or Conda_, where the former
can be considered Python's *standard* package installation tool, while the
latter has additional features and can install non-Python, system packages,
too.

For that reason Conda_ has become the tool of choice for complex system
set-ups, as they often appear in big data and scientific use-cases including
the geo-sciences. There, some important packages like GEOS_ (a dependency of
GeoPandas) cannot be installed with Pip_.

For Conda_ installation instructions, visit
`their website <https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html>`_.

To install Here-Nagini in a fresh environment, we therefore recommend to use
``conda`` (with the unpacked repository's ``environment.yml`` file). For
python3.7 use ``environment_37.yml``, and python3.6 use ``environment_36.yml``:

.. code-block:: console

    $ conda env create --name nagini -f environment_37.yml
    $ conda activate nagini

Alternatively, you can also install Here-Nagini with Pip_ (using the
here pip artifactory repository) :

.. code-block:: console

    $ pip install --extra-index-url https://repo.platform.here.com/artifactory/api/pypi/analytics-pypi/simple/ here-nagini

Alternatively, you can also install Here-Nagini with Pip_ (using the
``requirements.txt`` file) , but then you need to make sure that all
dependencies are installed correctly.

In this case it is recommended to use
Virtualenv_ to create an isolated environment, first.
Then, you can install the package using ``pip3`` from the unpacked archive's
root directory like this:

.. code-block:: console

    $ pip3 install -e .

In Gentoo-based distributions this should be:

.. code-block:: console

    $ pip3 install -e . --user

You can check if your installation succeeded by running the following command
(which will report failures if something is missing):

.. code-block:: console

    $ pytest -v -s scripts/validate_install.py


Add JupyterLab Extensions
.........................

If you work with the JupyterLab_ "desktop" instead of the "classic" Jupyter_
notebooks (and you should because this is much more convenient and powerful),
you will benefit from installing a few additional JupyterLab extensions. These
will either render files in some frequently used formats (e.g. HTML or GeoJSON)
or some computed output (like Leaflet map cells) directly inside JupyterLab:

.. code-block:: console 

    $ jupyter labextension install @mflevine/jupyterlab_html
    $ jupyter labextension install @jupyterlab/geojson-extension
    $ jupyter labextension install jupyter-leaflet
    $ jupyter labextension install @jupyter-widgets/jupyterlab-manager

You might also be able to install these inside JupyterLab using its
interactive `Extension Manager`_.


Update an already created env
.............................
If you've already created a working environment and want to update to the latest 
requirements you can do:

**With Conda and Python 3.6**

.. code-block:: console
    $ conda activate nagini
    $ conda env update   --file environment_36.yml

**Or with Conda and Python 3.7**

.. code-block:: console

    $ conda activate nagini
    $ conda env update   --file environment_37.yml

Documentation
.............

The available documentation consists of the example notebooks inside the
``examples`` directory, and the internal API reference which is auto-generated
during CI/CD builds and served online as static GitLab *pages* here:

https://sdk.pages.gitlab.in.here.com/nagini-python-sdk/

Later, when introducing formally released packages, it is planned to include
this into the existing ``docs/reference`` directory. Until then you can also
generate this documentation locally with the following Bash script from the
Here-Nagini package root directory (which builds from the local file tree and not
from any installed package):

.. code-block:: console

    $ PYTHONPATH=. ./scripts/make_reference_doc.sh

This will build the static API reference documentation in the ``reference``
directory as a set of static HTML pages from the docstrings in the code, and
open it in your default webbrowser.


Setting OLP_ and HLS_ credentials
.................................

In order to work with OLP_ and HLS_, credentials for both are required, which
can be specified in two ways, based on files or environment variables. The
easiest way to generate these credentials is as follows:

**For HERE platform credentials** you'll need to create a HERE application and put its
credentials file into ``$HOME/.here/credentials.properties``. You can do this by
visiting
`HERE platform Applications and keys <https://platform.here.com/profile/apps-and-keys>`_,
generating a set of app credentials, and then downloading the generated
``credentials.properties`` file.

The HERE platform generated app credentials ``$HOME/.here/credentials.properties`` should
look similar to the example below:

.. code-block:: console

  here.user.id = HERE-406d266b-73fc-45c1-a5e1-dd41fw3097de
  here.client.id = KkmnaPEA8jd59iKklJMJ
  here.access.key.id = IH8P5zPIYol51DjQMZAaA
  here.access.key.secret = Q_V0CzR6HyQueOxA_UMx4WpVXv9J70JwWQmfgAOpiJWPALpzluKlhsR5g2qlwaPFXw4y3m4t3rWgRf4q9IeIog
  here.token.endpoint.url = https://account.api.here.com/oauth2/token

**For HERE Location Service credentials** you'll need to generate a new App ID and App Code and
place these credentials in a file at ``$HOME/.here/hls_credentials.properties``.
You can do this by visiting the
`HERE Developer Site <https://developer.here.com/>`_,
signing up for a freemium account, generating a Javascript/REST App ID and
App Code, and then copying the APP ID and code into a
``hls.credentials.properties`` file.

This HERE Location Service credentials file, ``$HOME/.here/hls_credentials.properties`` should
look similar to this:

.. code-block:: console

  app_id = <example_here>
  app_code = <example_here>

An alternative way of using these credentials is by passing environment
variables. Please note that this approach requires Jupyter to be restarted if
it was already running!

- HERE platform:

  .. code-block:: console

    $ export HERE_USER_ID=<your_here_user_id>
    $ export HERE_CLIENT_ID=<your_here_client_id>
    $ export HERE_ACCESS_KEY=<your_here_access_key>
    $ export HERE_ACCESS_SECRET=<your_here_access_secret>
    $ export HERE_TOKEN_ENDPOINT=<your_here_token_endpoint>

- HERE Location Service:

  .. code-block:: console

    $ export HLS_APP_ID=<your_here_developer_app_id>
    $ export HLS_APP_CODE=<your_here_developer_app_code>


Test instructions
.................

To run the entire test suite you only need to execute the following command:

.. code-block:: console

    $ make test

The tests are operating on a list of existing HERE platform catalogs for which you must
have access permissions. At the moment these catalogs are:

- `hrn:here:data::olp-here:oma-3 <https://platform.here.com/data/hrn:here:data::olp-here:oma-3>`_
- `hrn:here:data::olp-here:rib-2 <https://platform.here.com/data/hrn:here:data::olp-here:rib-2>`_
- `hrn:here:data::olp-here:live-weather-eu <https://platform.here.com/data/hrn:here:data::olp-here:live-weather-eu>`_
- `hrn:here:data::olp-here:here-geojson-samples <https://platform.here.com/data/hrn:here:data::olp-here:here-geojson-samples>`_
- `hrn:here:data::olp-here:olp-sdii-sample-berlin-2 <https://platform.here.com/data/hrn:here:data::olp-here:olp-sdii-sample-berlin-2>`_


Code Style instructions
.................

To format code using black and isort, code formatting tools execute following command:

.. code-block:: console

    $ make format


Jupyter configuration
.....................

To enable ipyleaflet in JupyterLab, you also need to install the JupyterLab extension:

.. code-block:: console

    $ jupyter labextension install jupyter-leaflet

For some users it is also required to install the jupyterlab-manager extension

.. code-block:: console

    jupyter labextension install @jupyter-widgets/jupyterlab-manager

Running examples in the container
..................................

After your local credentials are installed, you can pass them to the container
to run the example notebooks.

.. code-block:: console

  $ docker run -it -p 8888:8888 -v $HOME/.here/:/root/.here/ docker-local.artifactory.in.here.com/nagini jupyter notebook --ip 0.0.0.0 --no-browser --allow-root

HERE Data SDK for Python API Reference
................................

Use the Python API Reference to leverage the full functionality of the SDK for Python. This reference includes a wealth of commands to help analyze, visualize and process data easily.

https://sdk.pages.gitlab.in.here.com/nagini-python-sdk/

Support
-------

The best way to get support is to create a GitLab Issue_,

.. _Issue: https://main.gitlab.in.here.com/sdk/nagini-python-sdk/issues/new?issue

Or for more general discussion you can subscribe the follow Nagini_ Yammer group:

.. _Nagini: https://www.yammer.com/here.com/#/threads/inGroup?type=in_group&feedId=17776308&view=all

Contribution
------------

See `CONTRIBUTING.rst`_

.. _CONTRIBUTING.rst: ./CONTRIBUTING.rst

Future
------

* Full Conda support.

License
-------

Copyright (C) 2019-2020 HERE Europe B.V.

See the LICENSE_ file in the root of this project for license details.


.. _Anaconda: https://www.anaconda.com/distribution/
.. _Conda: https://docs.conda.io/
.. _GEOS: https://trac.osgeo.org/geos
.. _HERE: https://www.here.com/
.. _HLS: https://developer.here.com/documentation/
.. _Jupyter: https://jupyter.org/
.. _JupyterLab: https://jupyterlab.readthedocs.io/
.. _Extension Manager: https://jupyterlab.readthedocs.io/en/stable/user/extensions.html#using-the-extension-manager
.. _LICENSE: ./LICENSE
.. _OLP: https://openlocation.here.com/
.. _Pip: https://pip.pypa.io/
.. _Virtualenv: https://virtualenv.pypa.io/


