core.bones.phone
================

.. py:module:: core.bones.phone


Attributes
----------

.. autoapisummary::

   core.bones.phone.DEFAULT_REGEX


Classes
-------

.. autoapisummary::

   core.bones.phone.PhoneBone


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

.. py:data:: DEFAULT_REGEX
   :value: '^\\+?(\\d{1,3})[-\\s]?(\\d{1,4})[-\\s]?(\\d{1,4})[-\\s]?(\\d{1,9})$'


.. py:class:: PhoneBone(*, test = DEFAULT_REGEX, max_length = 15, default_country_code = None, **kwargs)

   Bases: :py:obj:`viur.core.bones.string.StringBone`


   The PhoneBone class is designed to store validated phone/fax numbers in configurable formats.
   This class provides a number validation method, ensuring that the given phone/fax number conforms to the
   required/configured format and structure.

   Initializes the PhoneBone with an optional custom regex for phone number validation, a default country code,
   and a flag to apply the default country code if none is provided.

   :param test: An optional custom regex pattern for phone number validation.
   :param max_length: The maximum length of the phone number. Passed to "StringBone".
   :param default_country_code: The default country code to apply (with leading +) for example "+49"
   If None is provided the PhoneBone will ignore auto prefixing of the country code.
   :param kwargs: Additional keyword arguments. Passed to "StringBone".
   :raises ValueError: If the default country code is not in the correct format for example "+123".


   .. py:attribute:: type
      :type:  str
      :value: 'str.phone'


      A string representing the type of the bone, in this case "str.phone".



   .. py:attribute:: test
      :type:  Pattern[str]


   .. py:attribute:: default_country_code
      :type:  Optional[str]
      :value: None



   .. py:method:: _extract_digits(value)
      :staticmethod:


      Extracts and returns only the digits from the given value.

      :param value: The input string from which to extract digits.
      :return: A string containing only the digits from the input value.



   .. py:method:: isInvalid(value)

      Checks if the provided phone number is valid or not.

      :param value: The phone number to be validated.
      :return: An error message if the phone number is invalid or None if it is valid.

      The method checks if the provided phone number is valid according to the following criteria:
      1. The phone number must not be empty.
      2. The phone number must match the provided or default phone number format.
      3. The phone number cannot exceed 15 digits, or the specified maximum length if provided (digits only).



   .. py:method:: singleValueFromClient(value, skel, bone_name, client_data)

      Processes a single value from the client, applying the default country code if necessary and validating the
      phone number.

      :param value: The phone number provided by the client.
      :param skel: Skeleton data (not used in this method).
      :param bone_name: The name of the bone (not used in this method).
      :param client_data: Additional client data (not used in this method).
      :return: A tuple containing the processed phone number and an optional list of errors.



   .. py:method:: structure()

      Returns the structure of the PhoneBone, including the test regex pattern.

      :return: A dictionary representing the structure of the PhoneBone.