bluemira.base.parameter_frame._parameter
========================================

.. py:module:: bluemira.base.parameter_frame._parameter


Attributes
----------

.. autoapisummary::

   bluemira.base.parameter_frame._parameter.ParameterValueType


Classes
-------

.. autoapisummary::

   bluemira.base.parameter_frame._parameter.ParamDictT
   bluemira.base.parameter_frame._parameter.ParameterValue
   bluemira.base.parameter_frame._parameter.Parameter


Functions
---------

.. autoapisummary::

   bluemira.base.parameter_frame._parameter.type_fail


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

.. py:function:: type_fail(exc, memo)

   :raises TypeError: Wrong type

   .. rubric:: Notes

   typeguard by default raises a TypeCheckError
   may want to have a custom checker in future


.. py:data:: ParameterValueType

.. py:class:: ParamDictT

   Bases: :py:obj:`TypedDict`

   .. autoapi-inheritance-diagram:: bluemira.base.parameter_frame._parameter.ParamDictT
      :parts: 1
      :private-bases:


   Typed dictionary for a Parameter.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: value
      :type:  ParameterValueType


   .. py:attribute:: unit
      :type:  str


   .. py:attribute:: source
      :type:  str


   .. py:attribute:: description
      :type:  str


   .. py:attribute:: long_name
      :type:  str


.. py:class:: ParameterValue

   Bases: :py:obj:`Generic`\ [\ :py:obj:`ParameterValueType`\ ]

   .. autoapi-inheritance-diagram:: bluemira.base.parameter_frame._parameter.ParameterValue
      :parts: 1
      :private-bases:


   Holds parameter value information.


   .. py:attribute:: value
      :type:  ParameterValueType


   .. py:attribute:: source
      :type:  str


.. py:class:: Parameter(name: str, value: ParameterValueType, unit: str = '', source: str = '', description: str = '', long_name: str = '', _value_types: tuple[type, Ellipsis] | None = None)

   Bases: :py:obj:`Generic`\ [\ :py:obj:`ParameterValueType`\ ]

   .. autoapi-inheritance-diagram:: bluemira.base.parameter_frame._parameter.Parameter
      :parts: 1
      :private-bases:


   Represents a parameter with physical units.

   :param name: The name of the parameter.
   :param value: The parameter's value.
   :param unit: The parameter's unit.
   :param source: The origin of the parameter's value.
   :param description: A description of the parameter.
   :param long_name: A longer name for the parameter.


   .. py:attribute:: _name


   .. py:attribute:: _value


   .. py:attribute:: _unit


   .. py:attribute:: _source
      :value: ''



   .. py:attribute:: _description
      :value: ''



   .. py:attribute:: _long_name
      :value: ''



   .. py:attribute:: _history
      :type:  list[ParameterValue[ParameterValueType]]
      :value: []



   .. py:method:: _type_check(name: str, value: ParameterValueType, value_types: tuple[type, Ellipsis] | None) -> ParameterValueType
      :staticmethod:



   .. py:method:: __repr__() -> str

      String repr of class instance.

      :returns: The string representation of the class instance.



   .. py:method:: __eq__(o: object, /) -> bool

      Check if this parameter is equal to another.

      Parameters are equal if their names and values (with matching
      units) are equal.

      :returns: True if the parameters are equal, False otherwise.



   .. py:method:: __hash__() -> int


   .. py:method:: history() -> list[ParameterValue[ParameterValueType]]

      Return the history of this parameter's value.

      :returns: A list of ParameterValue objects, the history of this parameter's value.



   .. py:method:: set_value(new_value: ParameterValueType, source: str = '')

      Set the parameter's value and update the source.



   .. py:method:: to_dict(*, use_last: bool = False) -> dict[str, Any]

      Serialise the parameter to a dictionary.

      :returns: A dictionary representation of the parameter.



   .. py:property:: name
      :type: str


      Return the name of the parameter.


   .. py:property:: value
      :type: ParameterValueType


      Return the current value of the parameter.


   .. py:method:: value_as(unit: str | pint.Unit) -> ParameterValueType | None

      Return the current value in a given unit

      :param unit: The unit to convert the value to

      :returns: The value in the new unit

      :raises ValueError: Unit conversion failed
      :raises TypeError: If the wrong unit type is passed in

      .. rubric:: Notes

      If the current value of the parameter is None the function checks for
      a valid unit conversion



   .. py:property:: unit
      :type: str


      Return the physical unit of the parameter.


   .. py:property:: source
      :type: str


      Return the source that last set the value of this parameter.


   .. py:property:: long_name
      :type: str


      Return a long name for this parameter.


   .. py:property:: description
      :type: str


      Return a description for the parameter.


   .. py:method:: _add_history_record()


   .. py:property:: _last_param
      :type: ParameterValue



   .. py:property:: last
      :type: ParameterValue


      Get the last value that isnt None from a parameter

      :raises ValueError: All values in history are None