casagui.utils
=============

.. py:module:: casagui.utils

.. autoapi-nested-parse::

   General utility functions used by the ``casagui`` tools and applications.



Functions
---------

.. autoapisummary::

   casagui.utils.path_to_url
   casagui.utils.find_ws_address
   casagui.utils.partition
   casagui.utils.error_msg
   casagui.utils.warn_import
   casagui.utils.have_network
   casagui.utils.ranges
   casagui.utils.contiguous_ranges
   casagui.utils.expand_range_incl
   casagui.utils.index_to_stokes
   casagui.utils.convert_masks
   casagui.utils.set_attributes


Package Contents
----------------

.. py:function:: path_to_url(path)

   Convert a single filesystem path to a URL.

   If the string specified in the ``path`` parameter exists. It is turned into a
   fully qualified path and converted to a URL and returned. If ``path`` does not
   exist, ``path`` is returned unchanged.

   :param path: path to be checked and expanded
   :type path: str

   :returns: ``path`` converted to a URL if ``path`` exists, otherwise ``path`` unchanged
   :rtype: str


.. py:function:: find_ws_address(address='127.0.0.1')

   Find free port on ``address`` network and return a tuple with ``address`` and port number

   This function uses the low level socket function to find a free port and return
   a tuple representing the address plus port number.

   :param address: network to be probed for an available port
   :type address: str

   :returns: network address (`str`) and port number (`int`)
   :rtype: tuple of str and int


.. py:function:: partition(pred, iterable)

   Split ``iterable`` into two lists based on ``pred`` predicate.



.. py:function:: error_msg(*args, **kwargs)

   standard method for reporting errors which do not result in aborting out of python

   This function takes the standard set of arguments that the python ``print`` function takes.
   The primary difference is that the output will go to ``stderr`` and perhaps other error
   logs.


.. py:function:: warn_import(package)

   standard method for reporting (optional) package import failure

   :param package: name of a package whose attempted import failed
   :type package: str


.. py:function:: have_network()

   check to see if an active network with general internet connectivity
   is available. returns ``True`` if we have internet connectivity and
   ``False`` if we do not.


.. py:function:: ranges(iterable, order=sorted, key=lambda x: x)

   collect elements of ``iterable`` into tuple ranges where each tuple represents
   a concesecutive range within the iterable. ``key`` can be used to provide ranges
   for other objects where ``key(element)`` returns the key to be used for sorting
   into ranges


.. py:function:: contiguous_ranges(iterable, order=sorted, key=lambda x: x)

   split iterable into contiguous index sequence, i.e. reduce consecutive index runs
   to a tuple containing the first and last. ``iterable`` can be a sequence of values that
   can be subtracted or a list of more complex values where the function ``key`` returns
   the key to be used for ordering. ``iterable`` is ordered by ``order`` which by default
   sorts ``iterable``.


.. py:function:: expand_range_incl(r)

   expand the tuple supplied as ``r`` into a range which *includes* the first
   and last element ``r``


.. py:function:: index_to_stokes(index: int)

   Convert stokes axis index to alphabetic value.

   :param index: enumerated index defining stokes value.
   :type index: int

   :returns: String indicating stokes value.
   :rtype: str


.. py:function:: convert_masks(masks: dict, coord='pixel', cdesc=None) -> list

   Convert masks in standard format (as defined by ``CubeMask.jsmask_to_raw``) into
   other formats like list of CRTF, single region, etc.

   :param masks: Dictionary containing ``masks`` and ``polys`` keys. The values for ``masks`` are the polygon
                 references for each channel and the values for ``polys`` contain the points making up each
                 polygon.
   :type masks: dict
   :param coord: Coordinate system that should be used in the returned masks. Allowed values are 'pixel'.
   :type coord: str
   :param cdesc: Dictionary containing ``csys`` and ``shape`` which describes the coordinate system to be
                 used for creating world coordinate coordinates. The ``shape`` is required along with the
                 coordinate system for coordinate conversion.
   :type cdesc: dict


.. py:function:: set_attributes(obj, **kw)

   Given an object and a set of keyword arguments, set the attributes
   in the object that correspond to the keywords to the specified values.

   :param obj: Object whose attributes should be set
   :type obj: object
   :param kw: Attributes to be set
   :type kw: keyword and object

   :returns: ``obj`` parameter
   :rtype: object