Metadata-Version: 2.1
Name: dateparsa
Version: 0.5.0
Summary: Date parsing for input whose format you do not control: format detection, ambiguity reported, 20 locales, natural language, column order, format strings.
Author: Kevin O'Neil
License: Apache-2.0
Project-URL: Source, https://github.com/kmoneil/dateparsa.zig
Project-URL: Changelog, https://github.com/kmoneil/dateparsa.zig/blob/main/CHANGELOG.md
Keywords: date,datetime,parser,dateparser,natural-language,locales,csv,format-detection
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# dateparsa

Date parsing for input whose format you do not control.

CSV imports, log lines, third-party APIs, user-typed strings: dateparsa works
out the format, parses the value, and tells you when it had to guess. It reads
32 structured formats, Unix timestamps by their digit count, dates written
around a month name in 20 languages, and natural language ("next friday at
5pm"). It never reads a clock: an input that needs a base time is an error
unless you pass one.

```sh
pip install dateparsa
```

Wheels for Linux (glibc and musl), macOS 13+ and Windows, on x86_64 and arm64,
for Python 3.9 and later. No dependencies, and nothing to compile.

```python
import dateparsa

r = dateparsa.parse("March 15, 2024")
r.datetime   # datetime(2024, 3, 15, 0, 0, tzinfo=timezone.utc)
r.label      # 'MONTH_DAY_YEAR'

# Ambiguity is reported, never hidden.
dateparsa.parse("01/02/2024").ambiguous                      # True: January 2nd was a guess
dateparsa.parse("01/02/2024", prefer_day_first=True)         # February 1st
try:
    dateparsa.parse("01/02/2024", strict=True)
except dateparsa.Ambiguous as e:
    e.interpretations                                         # the MM/DD/YYYY and DD/MM/YYYY readings

# A column settles what one value cannot.
column = ["01/02/2024", "05/06/2024", "13/02/2024"]
report = dateparsa.detect_column(column)
report.order                                                  # 'day_first', settled by row 2
[dateparsa.parse(v, **report.preferences) for v in column]   # each read day first

# A whole column in one call, each value as parse reads it.
col = dateparsa.parse_column(["2024-03-15", "N/A", "2024-03-17T10:30:00Z"])
col.failed                                                    # [1]
col.datetimes()                                               # [datetime(2024, 3, 15, ...), None, datetime(...)]

# Hand the format to pandas, Go or Java, or read one you were given.
dateparsa.parse("13/02/2024 10:30").layout.format_string()   # '%d/%m/%Y %H:%M'
dateparsa.Layout.from_format("%d/%m/%Y").parse("01/02/2024")  # February 1st, no detection

# Natural language and other languages, against a base time you choose.
from datetime import datetime, timezone
dateparsa.parse("vor 3 Tagen", base_time=datetime(2024, 3, 15, tzinfo=timezone.utc), locales=["de"])
```

`parse` takes keyword options: `base_time`, `timezone_offset`,
`prefer_day_first`, `prefer_year_first`, `prefer_future`, `strict` and
`locales`. A failed parse raises `NoMatch`, `Ambiguous` or `NoBaseTime`, all
`ValueError`s. `Parser` reads a column, reusing the first value's layout, and
`Layout.parse` reads a value with no detection at all; `Layout.from_format`
makes a layout from a strftime, Go or Java format string you already have.
`parse_column` reads a
whole column in one call into the library, several times as fast as one call
a value: `datetimes()`, `times()` and `failed` on what it returns, and
`datetime64()` for a numpy array pandas takes, with `NaT` where a value did not
parse (numpy is not a dependency).

This package is a thin `ctypes` binding to libdateparsa, the C interface of the
Zig library [dateparsa.zig](https://github.com/kmoneil/dateparsa.zig), whose
README has the full format table and how its answers are checked: they match
the Go original on 158,631 inputs. Apache-2.0; the locale data is derived from
the Unicode CLDR under the Unicode License v3 (see NOTICE).
