Metadata-Version: 1.2
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
Description: 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/
        
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
