py_serializable
===============

.. py:module:: py_serializable


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/py_serializable/formatters/index
   /autoapi/py_serializable/helpers/index
   /autoapi/py_serializable/json/index
   /autoapi/py_serializable/xml/index


Attributes
----------

.. autoapisummary::

   py_serializable.logger


Classes
-------

.. autoapisummary::

   py_serializable.ViewType
   py_serializable.SerializationType
   py_serializable.XmlArraySerializationType
   py_serializable.XmlStringSerializationType
   py_serializable.ObjectMetadataLibrary


Functions
---------

.. autoapisummary::

   py_serializable.serializable_enum
   py_serializable.serializable_class
   py_serializable.type_mapping
   py_serializable.include_none
   py_serializable.json_name
   py_serializable.string_format
   py_serializable.view
   py_serializable.xml_attribute
   py_serializable.xml_array
   py_serializable.xml_string
   py_serializable.xml_name
   py_serializable.xml_sequence


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

.. py:data:: logger

   The logger. The thing that captures all this package has to say.
   Feel free to modify its level and attach handlers to it.


.. py:class:: ViewType

   Base of all views.


.. py:class:: SerializationType

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Enum to define the different formats supported for serialization and deserialization.


   .. py:attribute:: JSON
      :value: 'JSON'



   .. py:attribute:: XML
      :value: 'XML'



.. py:class:: XmlArraySerializationType

   Bases: :py:obj:`enum.Enum`


   Enum to differentiate how array-type properties (think Iterables) are serialized.

   Given a ``Warehouse`` has a property ``boxes`` that returns `List[Box]`:

   ``FLAT`` would allow for XML looking like:

   ``
   <warehouse>
       <box>..box 1..</box>
       <box>..box 2..</box>
   </warehouse>
   ``

   ``NESTED`` would allow for XML looking like:

   ``
   <warehouse>
       <boxes>
           <box>..box 1..</box>
           <box>..box 2..</box>
       </boxes>
   </warehouse>
   ``


   .. py:attribute:: FLAT
      :value: 1



   .. py:attribute:: NESTED
      :value: 2



.. py:class:: XmlStringSerializationType

   Bases: :py:obj:`enum.Enum`


   Enum to differentiate how string-type properties are serialized.


   .. py:attribute:: STRING
      :value: 1


      as raw string.
      see https://www.w3.org/TR/xmlschema-2/#string



   .. py:attribute:: NORMALIZED_STRING
      :value: 2


      as `normalizedString`.
      see http://www.w3.org/TR/xmlschema-2/#normalizedString



   .. py:attribute:: TOKEN
      :value: 3


      as `token`.
      see http://www.w3.org/TR/xmlschema-2/#token



.. py:class:: ObjectMetadataLibrary

   namespace-like

   The core Class in ``py_serializable`` that is used to record all metadata about classes that you annotate for
   serialization and deserialization.


   .. py:attribute:: custom_enum_klasses
      :type:  Set[Type[enum.Enum]]


   .. py:attribute:: klass_mappings
      :type:  Dict[str, ObjectMetadataLibrary]


   .. py:attribute:: klass_property_mappings
      :type:  Dict[str, Dict[str, ObjectMetadataLibrary]]


   .. py:class:: SerializableClass(*, klass: type, custom_name: Optional[str] = None, serialization_types: Optional[Iterable[SerializationType]] = None, ignore_during_deserialization: Optional[Iterable[str]] = None, ignore_unknown_during_deserialization: bool = False)

      Internal model class used to represent metadata we hold about Classes that are being included in
      (de-)serialization.


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



      .. py:property:: klass
         :type: type



      .. py:property:: custom_name
         :type: Optional[str]



      .. py:property:: serialization_types
         :type: Iterable[SerializationType]



      .. py:property:: ignore_during_deserialization
         :type: Set[str]



      .. py:property:: ignore_unknown_during_deserialization
         :type: bool




   .. py:class:: SerializableProperty(*, prop_name: str, prop_type: Any, custom_names: Dict[SerializationType, str], custom_type: Optional[Any] = None, include_none_config: Optional[Set[Tuple[Type[ViewType], Any]]] = None, is_xml_attribute: bool = False, string_format_: Optional[str] = None, views: Optional[Iterable[Type[ViewType]]] = None, xml_array_config: Optional[Tuple[XmlArraySerializationType, str]] = None, xml_string_config: Optional[XmlStringSerializationType] = None, xml_sequence_: Optional[int] = None)

      Internal model class used to represent metadata we hold about Properties that are being included in
      (de-)serialization.


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



      .. py:property:: custom_names
         :type: Dict[SerializationType, str]



      .. py:method:: custom_name(serialization_type: SerializationType) -> Optional[str]


      .. py:property:: type_
         :type: Any



      .. py:property:: concrete_type
         :type: Any



      .. py:property:: custom_type
         :type: Optional[Any]



      .. py:property:: include_none
         :type: bool



      .. py:property:: include_none_views
         :type: Set[Tuple[Type[ViewType], Any]]



      .. py:method:: include_none_for_view(view_: Type[ViewType]) -> bool


      .. py:method:: get_none_value_for_view(view_: Optional[Type[ViewType]]) -> Any


      .. py:property:: is_xml_attribute
         :type: bool



      .. py:property:: string_format
         :type: Optional[str]



      .. py:property:: views
         :type: Set[Type[ViewType]]



      .. py:property:: xml_array_config
         :type: Optional[Tuple[XmlArraySerializationType, str]]



      .. py:property:: is_array
         :type: bool



      .. py:property:: xml_string_config
         :type: Optional[XmlStringSerializationType]



      .. py:property:: is_enum
         :type: bool



      .. py:property:: is_optional
         :type: bool



      .. py:property:: xml_sequence
         :type: int



      .. py:method:: get_none_value(view_: Optional[Type[ViewType]] = None) -> Any


      .. py:method:: is_helper_type() -> bool


      .. py:method:: is_primitive_type() -> bool


      .. py:method:: parse_type_deferred() -> None



   .. py:method:: defer_property_type_parsing(prop: ObjectMetadataLibrary, klasses: Iterable[str]) -> None
      :classmethod:



   .. py:method:: is_klass_serializable(klass: Any) -> bool
      :classmethod:



   .. py:method:: is_property(o: Any) -> bool
      :classmethod:



   .. py:method:: register_enum(klass: Type[_E]) -> Type[_E]
      :classmethod:



   .. py:method:: register_klass(klass: Type[_T], custom_name: Optional[str], serialization_types: Iterable[SerializationType], ignore_during_deserialization: Optional[Iterable[str]] = None, ignore_unknown_during_deserialization: bool = False) -> Union[Type[_T], Type[_JsonSerializable], Type[_XmlSerializable]]
      :classmethod:



   .. py:method:: register_custom_json_property_name(qual_name: str, json_property_name: str) -> None
      :classmethod:



   .. py:method:: register_custom_string_format(qual_name: str, string_format: str) -> None
      :classmethod:



   .. py:method:: register_custom_xml_property_name(qual_name: str, xml_property_name: str) -> None
      :classmethod:



   .. py:method:: register_klass_view(klass: Type[_T], view_: Type[ViewType]) -> Type[_T]
      :classmethod:



   .. py:method:: register_property_include_none(qual_name: str, view_: Optional[Type[ViewType]] = None, none_value: Optional[Any] = None) -> None
      :classmethod:



   .. py:method:: register_property_view(qual_name: str, view_: Type[ViewType]) -> None
      :classmethod:



   .. py:method:: register_xml_property_array_config(qual_name: str, array_type: XmlArraySerializationType, child_name: str) -> None
      :classmethod:



   .. py:method:: register_xml_property_string_config(qual_name: str, string_type: Optional[XmlStringSerializationType]) -> None
      :classmethod:



   .. py:method:: register_xml_property_attribute(qual_name: str) -> None
      :classmethod:



   .. py:method:: register_xml_property_sequence(qual_name: str, sequence: int) -> None
      :classmethod:



   .. py:method:: register_property_type_mapping(qual_name: str, mapped_type: type) -> None
      :classmethod:



.. py:function:: serializable_enum(cls: Literal[None] = None) -> Callable[[Type[_E]], Type[_E]]
                 serializable_enum(cls: Type[_E]) -> Type[_E]

   Decorator


.. py:function:: serializable_class(cls: Literal[None] = None, *, name: Optional[str] = ..., serialization_types: Optional[Iterable[SerializationType]] = ..., ignore_during_deserialization: Optional[Iterable[str]] = ..., ignore_unknown_during_deserialization: bool = ...) -> Callable[[Type[_T]], Union[Type[_T], Type[_JsonSerializable], Type[_XmlSerializable]]]
                 serializable_class(cls: Type[_T], *, name: Optional[str] = ..., serialization_types: Optional[Iterable[SerializationType]] = ..., ignore_during_deserialization: Optional[Iterable[str]] = ..., ignore_unknown_during_deserialization: bool = ...) -> Union[Type[_T], Type[_JsonSerializable], Type[_XmlSerializable]]

   Decorator used to tell ``py_serializable`` that a class is to be included in (de-)serialization.

   :param cls: Class
   :param name: Alternative name to use for this Class
   :param serialization_types: Serialization Types that are to be supported for this class.
   :param ignore_during_deserialization: List of properties/elements to ignore during deserialization
   :param ignore_unknown_during_deserialization: Whether to ignore all properties/elements/attributes that are unknown
          to the class during deserialization
   :return:


.. py:function:: type_mapping(type_: type) -> Callable[[_F], _F]

   Decorator


.. py:function:: include_none(view_: Optional[Type[ViewType]] = None, none_value: Optional[Any] = None) -> Callable[[_F], _F]

   Decorator


.. py:function:: json_name(name: str) -> Callable[[_F], _F]

   Decorator


.. py:function:: string_format(format_: str) -> Callable[[_F], _F]

   Decorator


.. py:function:: view(view_: Type[ViewType]) -> Callable[[_F], _F]

   Decorator


.. py:function:: xml_attribute() -> Callable[[_F], _F]

   Decorator


.. py:function:: xml_array(array_type: XmlArraySerializationType, child_name: str) -> Callable[[_F], _F]

   Decorator


.. py:function:: xml_string(string_type: XmlStringSerializationType) -> Callable[[_F], _F]

   Decorator


.. py:function:: xml_name(name: str) -> Callable[[_F], _F]

   Decorator


.. py:function:: xml_sequence(sequence: int) -> Callable[[_F], _F]

   Decorator