Metadata-Version: 1.1
Name: froshki
Version: 0.3
Summary: simple and poor object data mapper library
Home-page: https://github.com/drowse314-dev-ymat/froshki
Author: drowse314-dev-ymat
Author-email: drowse314@gmail.com
License: BSD
Description: Froshki
        =======
        
        Froshki is a simple and poor object data mapper library.
        
        Looking quite similar to `WTForms
        <http://wtforms.simplecodes.com/>`_,
        rather intended to focus on data input/output abstraction,
        separating validation or conversion functions as APIs & extensions.
        
        Instead of integrating with web forms etc., designed to achieve more flexible attribute sourcing.
        
        Features
        ........
        
        * Define data schema as class definition.
        * Supply data inputs by keyword arguments, dict, or both.
        * Convert and validate data inputs with user defined methods or built-in integration with 3rd party libraries.
        * Access validated data as attributes / mapping.
        * Easy to hook your functions on validation.
        
        Simple usage
        ------------
        
        Primitive demo:: 
        
            >>> from froshki import Froshki, Attribute
            >>>
            >>> class ResourceId(Attribute):
            ...     @classmethod
            ...     def transform(klass, input_value):
            ...         return int(input_value)
            ...     @classmethod
            ...     def validate(klass, input_value):
            ...         if input_value in (1,5,7,9):
            ...             return True, input_value
            ...         else:
            ...             return False, 'resource id not found'
            >>>
            >>> class Filetype(Attribute):
            ...     @classmethod
            ...     def transform(klass, input_value):
            ...         return input_value.lower()
            ...     @classmethod
            ...     def validate(klass, input_value):
            ...         if input_value in ('pdf', 'txt', 'mobi'):
            ...             return True, input_value
            ...         else:
            ...             return False, 'filetype unavailable'
            >>>
            >>> class Download(Froshki):
            ...     resource_id = ResourceId()
            ...     filetype = Filetype()
            >>>
            >>> download = Download(resource_id='9', filetype='PDF')
            >>> download.validate()
            True
            >>> download.resource_id
            9
            >>> download.filetype
            'pdf'
         
        To use any functions of Froshki, extend ``froshki.Froshki`` to define data model schema.
        Attributes are represented by attaching ``froshki.Attribute`` subclasses onto the model.
        
        You can add any data conversion (``Attribute.transform``) or validation (``Attribute.validate``) methods for attributes.
        ``Froshki.validate`` converts and validates all attributes as defined.
        But it's a bit bothersome, and you can use a built-in extension supporting attribute definition.
        
        Using trafaret extension
        ------------------------
        
        You need to pre-install `trafaret
        <https://github.com/Deepwalker/trafaret>`_ to use the extension.
        Usage::
        
            >>> from froshki import Froshki
            >>> import trafaret
            >>> from froshki.ext import trafaret_attr
            >>>
            >>> class SendInquiry(Froshki):
            ...     user_name = trafaret_attr(trafaret.String())()
            ...     user_contact = trafaret_attr(trafaret.Email())()
            ...     message = trafaret_attr(trafaret.String(regex=r'\w{10,400}'))()
            >>>
            >>> send_inquiry = SendInquiry(user_name='yu mat', user_contact='drowse314@gmail.com', message='cannot post messages to my group')
            >>> send_inquiry.validate()
            True
        
        If you prefer other validation libraries,
        you will find it so easy to extend ``froshki.Attribute.validate``.
        Or some more libraries are built-in supported:
        
        * `voluptuous <https://github.com/alecthomas/voluptuous>`_
        
        See ``froshki/ext/*_attr.py`` for documentation or details of extension wrinting.
        
        Other features
        --------------
        
        Data as mappings
        ................
        
        Some utility properties are available for accessing validated data::
        
            (...)
            >>> send_inquiry.data
            {'user_name': 'yu mat', 'user_contact': 'drowse314@gmail.com', 'message': 'cannot post messages to my group'}
            >>> send_inquiry.errors  # error messages are registered if validation failed
            {}
        
        Further, you can initialize ``froshki.Froshki`` with mappings::
        
            (...)
            >>> data = {'user_name': 'ymat', 'user_contact': 'drowse314.gmail.com', 'message': 'cannot post messages to my group'}
            >>> another_inquiry = SendInquiry(source=data)
            >>> another_inquiry.validate()
            False
        
        Source attributes with alias names
        ..................................
        
        You can use the names differring from the class attribute names for sourcing attributes::
        
            >>> class ResourceAccess(Froshki):
            ...     resource_id = Attribute()
            ...     user_id = Attribute()
            ...     resource_key = Attribute(key_alias='password')
            >>> access = ResourceAccess(resource_id='1276', user_id='ymat', password='VXFPF93')
            >>> access.resource_key
            'VXFPF93'
        
        Extra validation
        ................
        
        You can add attribute dependent extra validator methods for attribute relations etc., using ``validation_hook`` decorator::
        
            >>> from froshki import Froshki, Attribute, validation_hook
            >>>
            >>> class SendInquiry(Froshki):
            ...     user_name = Attribute()
            ...     user_contact = Attribute()
            ...     user_contact_confirmation = Attribute()
            ...     message = Attribute()
            ...     @validation_hook
            ...     def confirm_email(self):
            ...         return self.user_contact == self.user_contact_confirmation
            >>>
            >>> send_inquiry = SendInquiry(user_name='yu mat', user_contact='drowse314@gmail.com', user_contact_confirmation='drose@gmail.com', message='cannot post messages to my group')
            >>> send_inquiry.validate()
            False
        
        If you need error information with these extra validators, extend the decorator as following::
        
            (...)
            >>> class SendInquiryExt(SendInquiry):
            ...     @validation_hook.extend(error='inconsistent email inputs')
            ...     def confirm_email(self):
            ...         return self.user_contact == self.user_contact_confirmation
            >>>
            >>> send_inquiry = SendInquiry(user_name='yu mat', user_contact='drowse314@gmail.com', user_contact_confirmation='drose@gmail.com', message='cannot post messages to my group')
            >>> send_inquiry.validate()
            False
            >>> send_inquiry.errors
            {'confirm_email': 'inconsistent email inputs'}
        
        Other options
        .............
        
        ``froshki.Froshki`` class has some useful options.
        
        * ``Froshki.default_values``: provide attribute defaults as dict.
        * ``Froshki.ignore_unkown_keys``: control if ``source`` argument accepts names that are not defined as attributes, or not (True/False).
        
        Also some options for ``froshki.Attribute``.
        
        * (As argument) ``Attribute(nullable=<bool>)``: allows ``None`` in validation (with any validation methods set).
        
Keywords: form forms object data mapper schema validation
Platform: any
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
