Metadata-Version: 2.1
Name: datetoken
Version: 0.1.0b0
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.04)
Requires-Dist: python-dateutil (==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. Surprisingly, 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

Simple tokens are defined as dates with zero or one modifiers. In case
you disallow the usage of several modifiers, simple tokens will
automatically read the first (if any) and discard the remaining ones.

Howe

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



