hio.help.naming
===============

.. py:module:: hio.help.naming

.. autoapi-nested-parse::

   hio.help.naming Module

   Mixin Base Class for one-to-one mapping with inverse: name-to-addr and addr-to-name
   that add support for MemoGrams to datagram based transports.

   Provide mixin classes.
   Takes of advantage of multiple inheritance to enable mixtures of behaviors
   with minimal code duplication (more DRY).

   New style python classes use the C3 linearization algorithm. Multiple inheritance
   forms a directed acyclic graph called a diamond graph. This graph is linarized
   into the method resolution order.
   Use class.mro() or class.__mro__

   (see https://www.geeksforgeeks.org/method-resolution-order-in-python-inheritance/)
   Basically:
   * children always precede their parents
   * immediate parent classes of a child are visited in the order listed in the
   child class statement.
   * a super class is visited only after all sub classes have been visited
   * linearized graph is monotonic (a class is only visted once)





Module Contents
---------------

.. py:class:: Namer(entries=None, **kwa)

   Bases: :py:obj:`hio.hioing.Mixin`


   Namer mixin class for adding support for mappings between names and addresses.
   May be used to provide in-memory lookup of mapping and its inverse of
   address from name and name from address.



   .. py:property:: addrByName

      Property that returns copy of ._addrByName


   .. py:property:: nameByAddr

      Property that returns copy of ._nameByAddr


   .. py:property:: countNameAddr

      Property that returns count of entries in .addrByName


   .. py:method:: clearAllNameAddr()

      Clears all entries





   .. py:method:: getAddr(name)

      Returns addr for given name or None if non-existant

      :param name: name
      :type name: str



   .. py:method:: getName(addr)

      Returns name for given addr or None if non-existant

      :param addr: address
      :type addr: str



   .. py:method:: addNameAddr(name, addr)

      Add mapping and inverse mapping entries for
      name to addr and addr to name
      All mappings must be one-to-one

      :returns: True if a new entry was added; False if matching entry already
                exists. Raises NamerError for conflicting partial matches.
      :rtype: bool

      :param name: name of entry
      :type name: str
      :param addr: address of entry
      :type addr: str

      Raise error if preexistant



   .. py:method:: remNameAddr(name=None, addr=None)

      Delete both name to addr and addr to name mapping entries.
         When an entry is found for either name or addr or both.
         When both provided must be matching one-to-one entries.
         All mappings must be one-to-one

      :returns: True if matching entry was deleted; False when no matching
                entry exists.
      :rtype: bool

      :param name: name of remote to delete or None if delete by addr
      :type name: str | None
      :param addr: addr of remote to delete or None if delete by name
      :type addr: str | None

      .. rubric:: Notes

      When both name and addr are provided, delete by name.

      Raise error when at least one of name or addr is not None and no mappings
      exist.



   .. py:method:: changeAddrAtName(*, name=None, addr=None)

      Changes existing name to addr mapping to new addr. Replaces
      inverse mapping of addr to name.
      All mappings must be one-to-one

      :returns: True if existing entries were updated; False if no change.
                Raises NamerError for conflicts.
      :rtype: bool

      :param name: name of entry
      :type name: str
      :param addr: address of entry
      :type addr: str

      Raise error if preexistant



   .. py:method:: changeNameAtAddr(*, addr=None, name=None)

      Changes existing addr to name mapping to new name. Replaces
      inverse mapping of name to addr.
      All mappings must be one-to-one

      :returns: True if existing entries were updated; False if no change.
                Raises NamerError for conflicts.
      :rtype: bool

      :param addr: address of entry
      :type addr: str
      :param name: name of entry
      :type name: str

      Raise error if preexistant