django-unixtimestampfield 1.0.3
Django Unix timestamp (POSIX type) field
License: MIT

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/

.. image:: https://coveralls.io/repos/myyang/django-unixtimestampfield/badge.svg?service=github
        :target: https://coveralls.io/github/myyang/django-unixtimestampfield

Provide a custom field that is stored as float (UTC POSIX timestamp) and used as datetime instance.


Requirements and Compatibility
------------------------------

Database that supports **Float** type is compatible.
  
Currently tested with metrics:

+---------------+-----+-----+-----+-----+-----+-------+-------+-------+
| Django/Python | 3.5 | 3.6 | 3.7 | 3.8 | 3.9 | 3.10  | 3.11  | 3.12  |
+---------------+-----+-----+-----+-----+-----+-------+-------+-------+
| 2.2.x         |  v  |  v  |  v  |     |     |       |       |       |
+---------------+-----+-----+-----+-----+-----+-------+-------+-------+
| 3.0.x         |     |  v  |  v  |  v  |  v  |       |       |       |
+---------------+-----+-----+-----+-----+-----+-------+-------+-------+
| 4.0.x         |     |  v  |  v  |  v  |  v  |   v   |       |       |
+---------------+-----+-----+-----+-----+-----+-------+-------+-------+
| 5.0.x         |     |     |     |     |  v  |   v   |   v   |   v   |
+---------------+-----+-----+-----+-----+-----+-------+-------+-------+

* Note: for Python2 and Django1.X, please use v0.3.9 or previous version.


Install
-------

.. code-block:: shell

   pip install django-unixtimestampfield

Usage
-----


Used in model as following:

.. 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)


Operation 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 to True for updating while saving, just like DatetimeField
* **auto_now_add**: set to True for updating 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`, return current datetime (in UTC timezone) info without **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 template tags:

.. 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 value is stored as float, it's hard for recognizing and leads to this tricky middleware.

Here are 3 modes 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`. Let's see examples.

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.4.0* -- Fix Python and Django compatiblity, check related section

*v0.3.9* -- Fix packages including in setup.py

*v0.3.8* -- Bugs fixed: Apply submiddleware to auto_now field and check format in submiddleware

*V0.3.7* -- Check minimum value.

*V0.3.6* -- Fix timezone problem. All records are stored UTC timezone and convert while retrive.

*V0.3.5.1* -- Integer compatibility and fix timezone problem

*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 

LICENSE
-------

MIT