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.5* -- Parse time format: YYYY-mm-dd HH:MM:SS[.FFFFFF]

*V0.3.4* -- Bugs fixed.

*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 
