Metadata-Version: 1.1
Name: django-unixtimestampfield
Version: 0.3.3
Summary: Unix timestamp (POSIX type) field
Home-page: https://github.com/myyang/django-unixtimestampfield
Author: Garfield.Yang
Author-email: ymy1019@gmail.com
License: MIT
Description: django-unixtimestampfield
        ===========================
        
        .. image:: https://img.shields.io/travis/myyang/django-unixtimestampfield.svg
                 :target: https://travis-ci.org/myyang/django-unixtimestampfield
        
        .. image:: https://img.shields.io/pypi/v/django-unixtimestampfield.svg
                 :target: https://pypi.python.org/pypi/django-unixtimestampfield/0.3
        
        
        Provide a custom field that is stored as float and used as datetime instance.
        
        
        Requirements
        ------------
        
        * Database that supports **Float** type is compatible
        * Python2.7, Python3.4 with Django >= 1.8
          
        **Note**: Since the 1.8 is LTS version, I choose to supports from 1.8. 
        `SubClassing will be removed in 2.0`_ , so I handle *from_db_value()* only.
        If you could help version <= 1.7, welcome~~ :D
        
        .. _`SubClassing will be removed in 2.0`: https://github.com/django/django/blob/1.8/django/db/models/fields/subclassing.py#L21
        
        Install
        -------
        
        .. code-block:: shell
        
           pip install django-unixtimestampfield
        
        Usage
        -----
        
        
        Used in model as:
        
        .. code-block:: python
        
           from django.db import models
           
           from unixtimestampfield.fields import UnixTimeStampField
        
           class ModelA(models.Model):
        
                created = UnixTimeStampField(auto_now_add=True)
                modified = UnixTimeStampField(auto_now=True)
                str_ini = UnixTimeStampField(default='0.0')
                float_ini = UnixTimeStampField(default=0.0)
                int_ini = UnixTimeStampField(default=0.0)
                dt_ini = UnixTimeStampField(default=timezone.now)
                num_field = UnixTimeStampField(use_numeric=True, default=0.0)
        
        
        Behavior exmpale:
        
        .. code-block:: python
        
            >>> m = modelA.objects.create()
            >>> m.created
            datetime.datetime(2015, 9, 2, 10, 41, 41, 937257, tzinfo=<UTC>)
            >>> m.int_ini
            datetime.datetime(1970, 1, 1, 0, 0, tzinfo=<UTC>)
            >>> m.int_ini = 3
            >>> m.save()
            >>> m.int_ini
            datetime.datetime(1970, 1, 1, 0, 3, tzinfo=<UTC>)
            >>> m.num_field
            0.0
        
        Field Options
        ~~~~~~~~~~~~~
        
        * **auto_now**: Set as True to refresh while saving, just like DatetimeField
        * **auto_now_add**: set as True to add while creating, just like DatetimeField
        * **round_to**: percision (*num*)  of round(value, *num*), default: **6**
        * **use_float**: **DEPRECATED in v0.3**, see use_numeric
        * **use_numeric**: set as True that instance attribute would be numeric, default as **False**
        
        
        Django settings
        ~~~~~~~~~~~~~~~
        
        
        If `USE_TZ` is set to `False`, there is no **tzinfo** while accessing attribute
        
        Example:
        
        .. code-block:: python
        
           # In settings.py
           USE_TZ = False
        
           >>> m = modelA.objects.create()
           >>> m.created
           datetime.datetime(2015, 9, 2, 10, 41, 41, 937257)
        
        
        Template Tags
        ~~~~~~~~~~~~~
        
        Load with:
        
        .. code-block:: html
        
           {% load unixtimestampfield %}
        
        
        Two django template filter tags are available:
        
        * **to_datetime**: Filter value as datetime
        * **to_timestamp**: Filter value as timestamp
        
        
        Tricky Sub-middleware
        ~~~~~~~~~~~~~~~~~~~~~
        
        Due to values stored as float, it's hard for recognizing and leads to these tricky middleware.
        
        Here are 3 mode to show data:
        
        * **usf_default**: Show data by default, according to use_numeric option of field. This is also default setting.
        * **usf_datetime**: Always convert to datetime object
        * **usf_timestamp**: Always convert to timestamp
        
        Use `USF_FORMAT` to indicate display police in `settings.py`.  Following comes to several demos. 
        
        Assume ModelB as:
        
        .. code-block:: python
        
           class ModelB(models.Model):
        
                num_field = UnixTimeStampField(use_numeric=True, default=0.0)
                dt_field = UnixTimeStampField(default=0.0)
        
        Then getting field value what you want:
        
        .. code-block:: python
        
           >>> m = ModelB()
           # with USF_FORMAT='usf_default' in settings.py 
           >>> m.num_field, m.dt_field
           (0.0, datetime.datetime(1970, 1, 1, 0, 0))
        
           # with USF_FORMAT='usf_datetime' in settings.py 
           >>> m.num_field, m.dt_field
           (datetime.datetime(1970, 1, 1, 0, 0), datetime.datetime(1970, 1, 1, 0, 0))
        
           # with USF_FORMAT='usf_timestamp' in settings.py 
           >>> m.num_field, m.dt_field
           (0.0, 0.0)
        
        
        Version
        -------
        
        *V0.3.3* -- Add sub-middleware and template tags
        
        *v0.3* -- Add ordinal time field and change field options **use_float** to **use_numeric**!!!
        
        *v0.2* -- Handle formfield and add options while init
        
        *v0.1* -- Added UnixTimeStampField 
        
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Framework :: Django
