mt_metadata.utils.validators
============================

.. py:module:: mt_metadata.utils.validators

.. autoapi-nested-parse::

   =======================
   schema
   =======================

   Convenience Classes and Functions to deal with the base metadata standards
   described by the csv file.

   The hope is that only the csv files will need to be changed as the standards
   are modified.  The attribute dictionaries are stored in ATTRICT

   Created on Wed Apr 29 11:11:31 2020

   @author: jpeacock



Functions
---------

.. autoapisummary::

   mt_metadata.utils.validators.validate_doi
   mt_metadata.utils.validators.validate_header
   mt_metadata.utils.validators.validate_name
   mt_metadata.utils.validators.validate_station_name
   mt_metadata.utils.validators.validate_attribute
   mt_metadata.utils.validators.validate_required
   mt_metadata.utils.validators.validate_type
   mt_metadata.utils.validators.validate_units
   mt_metadata.utils.validators.validate_style
   mt_metadata.utils.validators.validate_description
   mt_metadata.utils.validators.validate_options
   mt_metadata.utils.validators.validate_alias
   mt_metadata.utils.validators.validate_example
   mt_metadata.utils.validators.validate_default
   mt_metadata.utils.validators.validate_value_type
   mt_metadata.utils.validators.validate_value_dict


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

.. py:function:: validate_doi(value)

   Validate a DOI string.

   :param value: The DOI string to validate.
   :type value: str

   :returns: The validated DOI string.
   :rtype: str

   :raises ValueError: If the DOI string is not valid.


.. py:function:: validate_header(header, attribute=False)

   validate header to make sure it includes the required keys:
       * 'attribute'
       * 'type'
       * 'required'
       * 'style'
       * 'units'

   :param header: list of header names
   :type header: list
   :param attribute: include attribute in test or not, by default False
   :type attribute: bool, optional

   :returns: validated header
   :rtype: list


.. py:function:: validate_name(name)

   validate the name to conform to the standards
   name must be:

       * all lower case {a-z; 1-9}
       * must start with a letter
       * categories are separated by '.'
       * words separated by '_'

   {object}.{name_name}

   '/' will be replaced with '.'
   converted to all lower case

   :param name: name name
   :type name: str

   :returns: valid name name
   :rtype: str


.. py:function:: validate_station_name(name)

   validate station name to conform to general standards

   - must be a string
   - must only contain letters, numbers, and underscores

   :param name: The station name to validate
   :type name: str | int | float

   :returns: The validated station name
   :rtype: str

   :raises MTValidatorError: If name is not a string or contains invalid characters


.. py:function:: validate_attribute(name)

   validate the name to conform to the standards
   name must be:

       * all lower case {a-z; 1-9}
       * must start with a letter
       * categories are separated by '.'
       * words separated by '_'

   {object}.{name_name}

   '/' will be replaced with '.'
   converted to all lower case

   :param name: name name
   :type name: str

   :returns: valid name name
   :rtype: str


.. py:function:: validate_required(value)

   Validate required, must be True or False

   :param value: required value
   :type value: str or bool

   :returns: validated required value
   :rtype: bool


.. py:function:: validate_type(value)

   Validate required type. Must be:
       * str
       * float
       * int
       * bool
       * list
       * dict
       * object

   :param value: required type
   :type value: type or str

   :returns: validated type
   :rtype: str


.. py:function:: validate_units(value)

   Validate units

   ..todo:: make a list of acceptable unit names

   :param value: unit value to be validated
   :type value: str

   :returns: validated units
   :rtype: str


.. py:function:: validate_style(value)

   Validate string style

   ..todo:: make list of accepted style formats

   :param value: style to be validated
   :type value: str

   :returns: validated style
   :rtype: str


.. py:function:: validate_description(description)

   make sure the description is a string

   :param description: detailed description of an attribute
   :type description: str

   :returns: validated string of description
   :rtype: str


.. py:function:: validate_options(options)

   turn options into a list of strings

   :param options: DESCRIPTION
   :type options: TYPE

   :returns: DESCRIPTION
   :rtype: TYPE


.. py:function:: validate_alias(alias)

   validate alias names

   :param alias: DESCRIPTION
   :type alias: TYPE

   :returns: DESCRIPTION
   :rtype: TYPE


.. py:function:: validate_example(example)

   Validate example values

   :param example: DESCRIPTION
   :type example: TYPE

   :returns: DESCRIPTION
   :rtype: TYPE


.. py:function:: validate_default(value_dict)

   validate default value

   :param value_dict: DESCRIPTION
   :type value_dict: TYPE

   :returns: DESCRIPTION
   :rtype: TYPE


.. py:function:: validate_value_type(value, v_type, style=None)

   validate type from standards

   :param value: DESCRIPTION
   :type value: TYPE
   :param v_type: DESCRIPTION
   :type v_type: TYPE
   :param style: DESCRIPTION, by default None
   :type style: TYPE, optional

   :returns: DESCRIPTION
   :rtype: TYPE


.. py:function:: validate_value_dict(value_dict)

   Validate an input value dictionary

   Must be of the form:
       {'type': str, 'required': True, 'style': 'name', 'units': units}

   :param value_dict: DESCRIPTION
   :type value_dict: TYPE
   :return: DESCRIPTION
   :rtype: TYPE