The ``utils.py`` module
=======================

.. py:module:: ansys.tools.versioning.utils


Summary
-------


















.. py:currentmodule:: utils
.. tab-set::




    .. tab-item:: Classes

        .. list-table::
          :header-rows: 0
          :widths: auto


          * - :py:obj:`~ansys.tools.versioning.utils.VersionMeta`
            - Metaclass for version comparison.


          * - :py:obj:`~ansys.tools.versioning.utils.SemanticVersion`
            - Class for semantic versioning.


          * - :py:obj:`~ansys.tools.versioning.utils.mystr`
            - Custom class to hold strings for versioning.


          * - :py:obj:`~ansys.tools.versioning.utils.myint`
            - Custom class to hold integers for versioning.


          * - :py:obj:`~ansys.tools.versioning.utils.VersionNumber`
            - Class for version comparison.





    .. tab-item:: Functions

        .. list-table::
          :header-rows: 0
          :widths: auto


          * - :py:obj:`~sanitize_version_string`
            - Sanitize a version string number by adding additional zeros.


          * - :py:obj:`~sanitize_version_tuple`
            - Sanitize a version number by adding additional zeros.


          * - :py:obj:`~version_string_as_tuple`
            - Convert a semantic version string into a tuple.


          * - :py:obj:`~version_tuple_as_string`
            - Convert a semantic version tuple into a string.


          * - :py:obj:`~server_meets_version`
            - Check if server meets the required version.


          * - :py:obj:`~requires_version`
            - Ensure the method called matches a certain version.


          * - :py:obj:`~valid_version_string`
            - Check if version string is valid.


          * - :py:obj:`~valid_semantic_version`
            - Check if a semantic version is valid.









.. toctree::
   :titlesonly:
   :maxdepth: 1
   :hidden:

    <span class="nf nf-cod-symbol_class"></span> VersionMeta</api/ansys/tools/versioning/utils/VersionMeta>
    <span class="nf nf-cod-symbol_class"></span> SemanticVersion</api/ansys/tools/versioning/utils/SemanticVersion>
    <span class="nf nf-cod-symbol_class"></span> mystr</api/ansys/tools/versioning/utils/mystr>
    <span class="nf nf-cod-symbol_class"></span> myint</api/ansys/tools/versioning/utils/myint>
    <span class="nf nf-cod-symbol_class"></span> VersionNumber</api/ansys/tools/versioning/utils/VersionNumber>









Description
-----------

A module containing various utilities.

..
    !! processed by numpydoc !!






Module detail
-------------

.. py:function:: sanitize_version_string(version_string)

   
   Sanitize a version string number by adding additional zeros.


   :Parameters:

       **version_string** : :class:`python:str`
           A string representing a semantic version.



   :Returns:

       :class:`python:str`
           A string representing a semantic version.










   .. rubric:: Examples

   >>> sanitize_version_string("0")
   '0.0.0'
   >>> sanitize_version_string("1.2")
   '1.2.0'
   >>> sanitize_version_string("0.3.4")
   '0.3.4'

   ..
       !! processed by numpydoc !!

.. py:function:: sanitize_version_tuple(version_tuple)

   
   Sanitize a version number by adding additional zeros.


   :Parameters:

       **version_tuple** : :class:`python:tuple`
           A tuple representing a semantic version.



   :Returns:

       :class:`python:tuple`
           A tuple representing a semantic version.










   .. rubric:: Examples

   >>> sanitize_version_tuple((0,))
   (0, 0, 0)
   >>> sanitize_version_tuple((1, 2))
   (1, 2, 0)
   >>> sanitize_version_tuple((0, 3, 4))
   (0, 3, 4)

   ..
       !! processed by numpydoc !!

.. py:function:: version_string_as_tuple(version_string)

   
   Convert a semantic version string into a tuple.


   :Parameters:

       **version_string** : :class:`python:str`
           A string representing a semantic version.



   :Returns:

       **version_tuple** : :class:`python:tuple`
           A tuple representing a semantic version.










   .. rubric:: Examples

   >>> version_string_as_tuple("0.3.4")
   (0, 3, 4)
   >>> version_string_as_tuple("1.2")
   (1, 2, 0)

   ..
       !! processed by numpydoc !!

.. py:function:: version_tuple_as_string(version_tuple)

   
   Convert a semantic version tuple into a string.


   :Parameters:

       **version_tuple** : :class:`python:tuple`
           A tuple representing a semantic version.



   :Returns:

       :class:`python:str`
           A string representing a semantic version.










   .. rubric:: Examples

   >>> version_tuple_as_string((0, 3, 4))
   '0.3.4'
   >>> version_tuple_as_string((1, 2))
   '1.2.0'

   ..
       !! processed by numpydoc !!

.. py:function:: server_meets_version(server_version, required_version)

   
   Check if server meets the required version.


   :Parameters:

       **server_version** : :class:`python:str`, :class:`python:tuple`, :obj:`obj`
           A string or tuple representing the server version.
           If it is an object different from the previous ones, it must have a '_server_version' attribute.

       **required_version** : :class:`python:str`, :class:`python:tuple`
           A string or tuple representing the version to be meet.



   :Returns:

       :ref:`bool <python:bltin-boolean-values>`
           ``True`` if server version meets required version, ``False`` if not.




   :Raises:

       :obj:`ValueError`
           If the 'server_version' object does not have '_server_version' attribute.






   .. rubric:: Examples

   >>> server_version, required_version = "1.2.0", "1.3.0"
   >>> server_meets_version(server_version, required_version)
   False
   >>> server_version, required_version = (1, 2, 0), (1, 3, 0)
   >>> server_meets_version(server_version, required_version)
   False
   >>> server_version, required_version = "2.3.0", "1.3.0"
   >>> server_meets_version(server_version, required_version)
   True
   >>> server_version, required_version = (2, 3, 0), (1, 3, 0)
   >>> server_meets_version(server_version, required_version)
   True
   >>> server_version, required_version = (0, 0, 0), (0, 0, 0)
   >>> server_meets_version(server_version, required_version)
   True
   >>> class MyServer:
           def __init__(self):
               self._server_version = "1.2.0"
   >>> server = MyServer()
   >>> server_version, required_version = server, "1.3.0"
   >>> server_meets_version(server, required_version)

   ..
       !! processed by numpydoc !!

.. py:function:: requires_version(version, VERSION_MAP=None)

   
   Ensure the method called matches a certain version.


   :Parameters:

       **version** : :class:`python:str`, :class:`python:tuple`
           A string or tuple representing the minimum required version.

       **VERSION_MAP** : :class:`python:dict`, :obj:`optional`
           A dictionary relating server version and ANSYS unified install version.







   :Raises:

       :obj:`AttributeError`
           Decorated class method requires ``_server_version`` attribute.

       :obj:`VersionError`
           Decorated class method is not supported by server version.







   ..
       !! processed by numpydoc !!

.. py:function:: valid_version_string(version)

   
   Check if version string is valid.
















   ..
       !! processed by numpydoc !!

.. py:function:: valid_semantic_version(iterable)

   
   Check if a semantic version is valid.
















   ..
       !! processed by numpydoc !!