Metadata-Version: 2.1
Name: datetoken
Version: 0.1.2
Summary: Convert relative string tokens into datetime objects
Home-page: https://pypi.org/project/datetoken/
Author: Marcos Sanchez
Author-email: marsanben92@gmail.com
Maintainer: Marcos Sanchez
Maintainer-email: marsanben92@gmail.com
License: MIT
Project-URL: Code, https://github.com/sonirico/datetoken/
Project-URL: Issue tracker, https://github.com/sonirico/datetoken/issues
Platform: any
Requires-Python: >=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*
Requires-Dist: pytz (<=2018.7,>=2018.04)
Requires-Dist: python-dateutil (<=2.7.5,>=2.7.3)
Provides-Extra: dev
Requires-Dist: pytest (>=3); extra == 'dev'
Requires-Dist: coverage; extra == 'dev'
Requires-Dist: tox; extra == 'dev'
Provides-Extra: docs

Project description
-------------------

This package aims to solve a set of needs present in applications where
dates need to be represented in a relative fashion, like background
periodic tasks, datetime range pickers… in a compact and stringified
format. This enables the programmer to persist these tokens during the
lifetime of a process or even longer, since calculations are performed
in the moment of re-evaluation

Some common examples of relative tokens:

-  Today: ``now/d``, ``now``
-  Yesterday: ``now-d/d``, ``now-d@d``
-  Last 24 hours: ``now-1d``, ``now``. Also writable as: ``now-24h``,
   ``now``
-  Last business week: ``now-w/bw``, ``now-w@bw``
-  This business week: ``now/bw``, ``now@bw``
-  Last month: ``now-1M/M``, ``now-1M@M``

As you may have noticed, token follow a pattern:

-  The word ``now``. It means the point in the future timeline when
   tokens are parsed to their datetime form.
-  Optionally, modifiers to add and/or subtract the future value of
   ``now`` can be used. Unsurprisingly, additions are set via ``+``, while
   ``-`` mean subtractions. These modifiers can be chained as many times
   as needed. E.g: ``now-1M+3d+2h``. Along with the arithmetical sign
   and the amount, the unit of time the amount refers to must be
   specified. Currently, the supported units are:

   -  ``s`` seconds
   -  ``m`` minutes
   -  ``h`` hours
   -  ``d`` days
   -  ``w`` weeks
   -  ``M`` months

-  Optionally, there exist two extra modifiers to snap dates to the
   start or the end of any given snapshot unit. Those are:

   -  ``/`` Snap the date to the start of the snapshot unit.
   -  ``@`` Snap the date to the end of the snapshot unit.

   Snapshot units are the same as arithmetical modifiers, plus ``bw``,
   meaning *business week*. With this, we achieve a simple way to define
   canonical relative date ranges, such as *Today* or *Last month*. As
   an example of the later:

   -  String representation: ``now-1M/M``, ``now-1M@M``
   -  Being today *15 Jan 2018*, the result range should be: *2018-01-01
      00:00:00 / 2018-01-31 23:59:59*


Installing
----------

Install and update via either `pipenv`_ or `pip`_

.. code:: shell

    pipenv install datetoken

or

.. code:: shell

    pip install datetoken


Examples and usage
------------------

Most probably you will be dealing with simple presets such as
*yesterday* or the *last 24 hours*.

.. code:: python

   >>> from datetoken.utils import simple_token_to_date
   >>> from datetime import datetime
   >>> print(datetime.utcnow())
   2018-10-18 14:08:47
   >>> simple_token_to_date('now-d/d')  # Start of yesterday
   2018-10-17 00:00:00
   >>> simple_token_to_date('now-d@d')  # End of yesterday
   2018-10-17 23:59:59

.. _pipenv: https://pipenv.readthedocs.io/en/latest/
.. _pip: https://pip.pypa.io/en/stable/quickstart/



