ESM: Subscriber management
==========================

The system provides a Python object :data:`alc.esm`, which is an instance of class :data:`alc.Esm`, to set a list of attributes on a subscriber host or session in setup. It also provides :data:`alc.esm.derivedId` to achieve flexible LUDB lookups.

   .. note::
      Only the pre-provided :data:`alc.esm` object should be used in script, the class :data:`alc.Esm` should not be used directly.

:data:`alc.esm` APIs only apply during a host and session setup phase. 

.. _alc_dot_esm:

The :data:`alc.Esm` class
--------------------------

Instance Attributes
^^^^^^^^^^^^^^^^^^^

.. attribute:: derivedId

   The `derivedId` attribute is an attribute which can be set by a Python script and used as an LUDB match criterion. The current value can be read from this attribute. A new value for the derivedId can be set by assigning a new value to this attribute.

   The type of this attribute is `str`.

   If the derivedId is not supported, a RuntimeException is raised when retrieving or setting this attribute.

   If no derivedId is set, `None` is returned.
   This behavior has :ref:`changed<breaking-esm-no-derived-id>` with respect to the Python 2 implementation.

Methods
^^^^^^^

.. method:: set(key, value, /)

    Sets an attribute on the current subscriber to a specific value.

    :param int key: Integer representing which attribute to set.
                    See :ref:`esm_constants` for an enumeration of all supported attributes.
    :param value: value to set the attribute to.
    :raises: KeyError if the key is not valid
    :raises: ValueError if the type of the value or the actual value is not valid for the specified key.


.. _esm_constants:

Constants
^^^^^^^^^

The :data:`alc.esm` object provides a list of constants which can be used as a key parameter to choose which attribute to set.
The following table lists all attributes and the supported object-types for the corresponding value.

.. list-table::
   :header-rows: 1
   
   * - Attribute
     - Types
   * - subIdent
     - str 
   * - subProfileString
     - str 
   * - slaProfileString
     - str 
   * - ancpString
     - str 
   * - appProfileString
     - str 
   * - intDestId
     - str 
   * - catMapString
     - str 
   * - msapGroupInterface
     - str 
   * - msapPolicy
     - str 
   * - msapServiceId
     - str | int
   * - retailServiceId
     - str  | int
   * - ipAddress
     - str 
   * - ipv6Address
     - str 
   * - ipv6DelegatedPrefix
     - str 
   * - ipv6DelegatedPrefixLength
     - int
   * - ipv6SlaacPrefix
     - str 
   * - ipv6WanPool
     - str 
   * - ipv6PrefixPool
     - str 
   * - accountingPolicy
     - str 
   * - dhcpv4ServerAddr
     - str 
   * - dhcpv4GIAddr
     - str 
   * - dhcpv4SrcAddr
     - str 
   * - dhcpv4Pool
     - str 
   * - dhcpv6LinkAddr
     - str 
   * - dhcpv6ServerAddr
     - str 
   * - dhcpv6SrcAddr
     - str 
   * - defGw
     - str 
   * - subnetMask
     - str 
   * - ipv4LeaseTime
     - int 
   * - ipv4PrimDns
     - str 
   * - ipv4SecDns
     - str 
   * - primNbns
     - str 
   * - secNbns
     - str 
   * - ipv6PrimDns
     - str 
   * - ipv6SecDns
     - str 
   * - dhcpv6PreferredLifetime
     - int 
   * - dhcpv6RebindTimer
     - int 
   * - dhcpv6RenewTimer
     - int 
   * - dhcpv6ValidLifetime
     - int 
   * - padoDelay
     - int 
   * - pppAuthProtocol
     - str 
   * - pppMTU
     - int 
   * - aaSubScope
     - int 
   * - spiSharingGroupId
     - int 

.. _breaking-esm:

Breaking changes
----------------

.. _breaking-esm-no-derived-id:

Derived Id
^^^^^^^^^^
.. warning:: With Python 2 API, reading a derived-id which is not set raises a RuntimeError. With Python 3, the value `None` is returned.