Source code for naginterfaces.kusari

"""
Module Summary
--------------
Python functions for interacting with the NAG Kusari licence-management system.

If invoked directly as a module (i.e., using ``python -m naginterfaces.kusari``
or equivalent) this module calls :func:`lcheck` and then if a licence was
unavailable either calls :func:`key_gui` if on Windows or displays the Kusari
hostid otherwise.

The use of the `naginterfaces` package is controlled by the Kusari licence
management system, version |kver|.

In order to enable the software, NAG will issue you with a
licence key as follows. The licence key is contained in a text file
consisting of details of the software that will be enabled.

For evaluation purposes a trial licence may be used.

Before obtaining a full licence you need to know the Kusari
hostid of the system on which you intend to use this product. How
to do this is described below.

Linux and Mac

  To request a licence key, run the :func:`hostid` function.

  Return the information that it displays by email to NAG.

Windows

  To request a licence key, run the ``key_gui`` function.
  This will help you to build a standard message requesting either
  a trial key or a full key which can be pasted into an email to
  the NAG Technical Support Service. This message will include the
  Kusari hostid.

  Run ``key_gui`` and click on the Request New Licence button to bring
  up the New Licence Request form. Fill in your details. Note that the
  value required in the Product Code box will be pre-filled. Click on
  Generate Licence Request, then paste the generated information into
  your email client and send it to the NAG address given at the top of
  the generated information.

  If for any reason it is impractical to use this GUI licence request
  generator, please contact NAG for information on alternative
  command-line access to the licensing utilities.

See :ref:`Technical Support <support>` for information on contacting
the NAG Technical Support Service.

The NAG support team will send you the Kusari licence key by email.

A short term (demonstration or trial) licence key contains one or more
lines like the following::

   <PRODUCT_CODE> TRIAL <EXPIRY_DATE> "EMnxidA3oeoj0F1Yvi5ibxPjB7"

Specifically, it has a line containing the word ``TRIAL``.

Longer term licence keys must be locked to a specific computer,
i.e. they will enable the software on one computer only.

These licence keys typically include the word ``NODE`` or ``FULL``
instead of the word ``TRIAL`` above and may contain extra fields.

Once you have obtained one of the above licence keys it can be
installed as follows.

Linux and Mac

  The easiest way to install the key is to store the text in a file, ::

     $HOME/nag.key

  or ::

     /opt/NAG/nag.key

  or ::

     /usr/local/NAG/nag.key

  The licence software in this product automatically looks
  for these particular files and reads the first one found, so no
  further action is necessary.

  Alternatively, store the licence in a file with a name and
  location of your choice, say, ::

     [INSTALL_DIR]/licence.lic

  The location of the licence file, if it is not one of the default
  places listed above, must be made known to the NAG application by
  setting the environment variable ``NAG_KUSARI_FILE`` to the full
  pathname of the file before the application is invoked.

  For example, in the C shell, type::

     setenv NAG_KUSARI_FILE [INSTALL_DIR]/licence.lic

  or in the Bourne shell, type::

     NAG_KUSARI_FILE=[INSTALL_DIR]/licence.lic
     export NAG_KUSARI_FILE

Windows

  Once you have obtained one of the above licence keys, the ``key_gui``
  function may be used to install the key in the Windows
  Registry. Paste the key into the edit box on the main
  dialog and then click on the Install Licence Key button
  to install it.

Notes
-----
Further details about Kusari and how it may be configured to suit
your local circumstances (e.g. how to install the licence key on
a server) are online at

https://www.nag.com/content/kusari-licence-management
"""

# NAG Copyright 2017-2020.

import socket as _socket
import subprocess as _subprocess

from .base import utils as b_utils
from .base.info import impl_details as b_impl_details
from . import _THE_SYSTEM

_PRODUCT_CODE = b_impl_details()['product_code']
_KPRODUCT_CODE = _PRODUCT_CODE[:7] + 'X' + _PRODUCT_CODE[8:]

def _has_lic():
    """
    Return a Boolean for when klcheck reports that a licence is available.
    """
    return b_utils._capture_lcheck( # pylint: disable=protected-access
        _KPRODUCT_CODE, quiet=True,
    ).startswith('Licence available')

def hostid():
    """
    Display the Kusari hostid and NAG Library product code.

    The underlying ``khostid`` utility is run via the ``subprocess`` module.

    Examples
    --------
    >>> from naginterfaces.kusari import hostid
    >>> hostid()
    KUSARI ID = ...
    NAG Library product licensing code = ...
    Host name = ...
    """
    # pylint: disable=superfluous-parens
    if _KPRODUCT_CODE.endswith('L'):
        print(b_utils._capture_hostid()) # pylint: disable=protected-access
    else:
        print(
            'KUSARI ID = not required, '
            'because this product is not licence managed.'
        )
    print('NAG Library product licensing code = ' + _KPRODUCT_CODE)
    print('Host name = ' + _socket.gethostname())

def key_gui(): # pragma: no cover
    """
    Run the Kusari key GUI if licence managed and on Windows,
    otherwise do nothing.

    The underlying ``kusari_key_gui.exe`` is run via the ``subprocess`` module.
    """

    if _THE_SYSTEM != 'Windows' and not _THE_SYSTEM.startswith('CYGWIN'): # pylint: disable=protected-access
        return

    if not _KPRODUCT_CODE.endswith('L'):
        return

    no_l_pcode = _KPRODUCT_CODE[:9]
    print(
        'For a new licence request, the request form will be prefilled with'
    )
    print(no_l_pcode)
    print('as the product code.')
    _subprocess.check_call(
        (
            b_utils._resolve_kpath('kusari_key_gui') + # pylint: disable=protected-access
            ' ' + no_l_pcode
        )
    )

def lcheck(quiet=False):
    """
    Display availability of a NAG licence.

    The underlying ``klcheck`` utility is run via the ``subprocess`` module.

    Parameters
    ----------
    quiet : bool, optional
        If ``True`` a brief summary is printed, otherwise extended details of
        how the licence was located are also given.

    Examples
    --------
    >>> from naginterfaces.kusari import lcheck
    >>> lcheck(quiet=True)
    Licence available; ...
    """
    print('\n'.join(b_utils._lcheck_lines(_KPRODUCT_CODE, quiet=quiet))) # pylint: disable=protected-access,superfluous-parens

def _main():
    """
    Main function.
    """
    if _has_lic():
        lcheck(quiet=True)
        return
    lcheck()
    if _THE_SYSTEM == 'Windows' or _THE_SYSTEM.startswith('CYGWIN'): # pylint: disable=protected-access
        key_gui() # pragma: no cover
    else:
        print(b_utils._capture_hostid()) # pylint: disable=protected-access,superfluous-parens

if __name__ == '__main__':
    _main()