Metadata-Version: 1.1
Name: edtf
Version: 0.9.3
Summary: Python implementation of Library of Congress EDTF (Extended Date Time Format) specification
Home-page: https://github.com/ixc/python-edtf
Author: Greg Turner
Author-email: greg@interaction.net.au
License: MIT
Description: ===========
        python-edtf
        ===========
        
        A partial implementation of EDTF format in Python.
        
        See <http://www.loc.gov/standards/datetime/> for the draft specification.
        
        To install
        
            pip install edtf
        
        Includes:
        =========
        
        Level 0 ISO 8601 Features
        -------------------------
        * Date
        * Interval (start/end)
        
        Level 1 Extensions
        ------------------
        * Uncertain/Approximate dates
        * Unspecified dates
        * Year exceeding four digits
        * Season
        
        Level 2 Extensions
        ------------------
        * Partial unspecified
        * Masked precision
        
        Also
        ----
        * A rough and ready plain text parser
        * Basic conversion to python dates for sorting and range testing
        
        Does not include (ie still to be implemented):
        ==============================================
        
        Level 0 ISO 8601 Features
        -------------------------
        * Times
        * Interval (start/end)
        
        Level 1 Extensions
        ------------------
        * L1 Extended Interval
        
        Level 2 Extensions
        ------------------
        * partial uncertain/approximate
        * one of a set
        * multiple dates
        * L2 extended Interval
        * Year requiring more than 4 digits - Exponential form
        
        Usage
        =====
        
        >>> from edtf import EDTF
        >>> e = EDTF('1898-uu~')  # approximately a month in 1898
        >>> e.date_earliest()  # approximate dates get a bit of padding
        datetime.date(1897, 12, 16)
        >>> e.date_latest()
        datetime.date(1899, 1, 16)
        >>> e.sort_date_earliest() # defaults to be at the start of the range
        datetime.date(1898, 01, 01)
        >>> e.sort_date_latest() # defaults to be at the end of the range
        datetime.date(1898, 12, 31)
        >>> e.is_interval
        False
        
        >>> i = EDTF('1898/1903-08-30')  # between 1898 and August 30th 1903
        >>> i.earliest_date()
        datetime.date(1898, 1, 1)
        >>> i.date_latest()
        datetime.date(1903, 8, 30)
        >>> i.sort_date_earliest()
        datetime.date(1898, 01, 01)
        >>> i.sort_date_latest()
        datetime.date(1903, 08, 30)
        >>> i.is_interval
        True
        
        >>> p = EDTF.from_natural_text("circa April 1912")
        >>> unicode(p)
        u'1912-04~'
        >>> p.sort_date_earliest()
        datetime.date(1912, 4, 01)
        >>> p.sort_date_latest()
        datetime.date(1912, 4, 30)
        
        What is the difference between earliest_date and sort_date_earliest?
        --------------------------------------------------------------------
        
        ``sort_date_earliest`` and ``sort_date_latest`` are the "if you had to pick one day what would it be" values. So for
        circa dates, they're normally the first or last day in the circa'd range.
        
        In the example above, ``EDTF.from_natural_text("circa April 1912")`` produces ``1912-04-01`` or ``1912-04-30`` depending
        on whether earliest or latest. Which one you choose depends on whether you want circa dates to appear before or after
        more precise results in a sorted list.
        
        ``date_earliest`` and ``date_latest`` are the earliest/latest dates an EDTF date could reasonably be. These are
        intended to be used for filtering for imprecise dates that may overlap a given range (ie "show me works that might
        have been made in 1818").
        
        The meaning of 'could reasonably be' is **arbitrarily defined**. If a date is approximate *xor* uncertain, we add about
        50% of the precision in each direction. So for months that are approximate, we +/- half a month to the earliest and
        latest dates. E.g.
        
        >>> i = EDTF('2004-06?')  # approx june 2004
        >>> i.earliest_date()  # half a month earlier than the specified month
        datetime.date(2004, 5, 16)
        >>> i.date_latest()  # half a month later than the specified month
        datetime.date(2004, 7, 16)
        
        If an EDTF is both approximate *and* uncertain, we add 100% of the precision in each direction. So for months that are
        both approximate and uncertain, we +/- a whole month, e.g:
        
        >>> i = EDTF('1984?~')  # approx 1984, but uncertain
        >>> i.earliest_date()  # a whole year earlier than the specified year
        datetime.date(1983, 1, 1)
        >>> i.date_latest()  # a whole year later than the specified year
        datetime.date(1985, 12, 31)
        
        
        See ``tests.py`` for more.
        
        What assumptions does ``from_natural_text`` make when interpreting an ambiguous date?
        --------------------------------------------------------//---------------------------
        
        - We're interpreting "1800s" to be a century, and "ca. 1800s" to be a decade.
        - We imply the century to be "19" if it's not given, and the year is less than the current year.
        
        
Keywords: edtf
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
