Metadata-Version: 2.1
Name: datetoken
Version: 0.1.1
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
Description: 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/
        
        
Platform: any
Requires-Python: >=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*
Provides-Extra: dev
Provides-Extra: docs
