datespan 0.2.1

Effortless date span parsing and management.

datespan - effortless date span parsing and management

---

A Python package for effortless date span parsing and management. Aimed for data analysis and processing, useful in any context requiring date & time spans.

pip install datespan

import pandas as pd
from datespan import parse, DateSpan
df = pd.DataFrame({"date": pd.date_range("2024-01-01", "2024-12-31")})

dss = parse("April 2024 ytd") # Create a DateSpanSet object
dss.add("May")                # Add a full month of the current year (e.g. 2024 in 2024)
dss.add("today")              # Add the current day from 00:00:00 to 23:59:59
dss += "previous week"        # Add a full week from Monday 00:00:00 to Sunday 23:59
dss -= "January"              # Remove the full month of January 2024

print(len(dss))               # returns the number of nonconsecutive DateSpans
print(dss.to_sql("date"))     # returns an SQL WHERE clause fragment
print(dss.filter(df, "date")) # returns filtered DataFrame # vectorized filtering of column 'date' of a DataFrame

Classes

DateSpan represents a single date or time span, defined by a start and an end datetime. Provides methods to create, compare, merge, parse, split, shift, expand & intersect DateSpan objects and /or datetime, dateor time objects.

DateSpanSet represents an ordered and redundancy free collection of DateSpan objects, where consecutive or overlapping DateSpan objects get automatically merged into a single DateSpan object. Required for fragmented date span expressions like every 2nd Friday of next month.

DateSpanParser provides parsing for arbitrary date, time and date span strings in english language, ranging from simple dates like '2021-01-01' up to complex date span expressions like 'Mondays to Wednesday last month'. For internal DateTime parsing and manipulation, the DateUtil library is used.

Part of the CubedPandas Project

The 'dataspan' package has been carved out from the CubedPandas project, a library for easy, fast & fun data analysis with Pandas dataframes, as DataSpan serves a broader scope and purpose and can be used independently of CubedPandas.