readdate(datestr=None, *args, dateformat=None, return_defaults=False, verbose=False)[source]

Convenience function for loading a date from a string. If dateformat is None, this function tries a list of standard date types.

By default, a numeric date is treated as a POSIX (Unix) timestamp. This can be changed with the dateformat argument, specifically:

  • ‘posix’/None: treat as a POSIX timestamp, in seconds from 1970

  • ‘ordinal’/’matplotlib’: treat as an ordinal number of days from 1970 (Matplotlib default)

  • datestr (int, float, str or list) – the string containing the date, or the timestamp (in seconds), or a list of either

  • args (list) – additional dates to convert

  • dateformat (str or list) – the format for the date, if known; if ‘dmy’ or ‘mdy’, try as day-month-year or month-day-year formats; can also be a list of options

  • return_defaults (bool) – don’t convert the date, just return the defaults

  • verbose (bool) – return detailed error messages


a datetime object

Return type

dateobj (date)


dateobj  = sc.readdate('2020-03-03') # Standard format, so works
dateobj  = sc.readdate('04-03-2020', dateformat='dmy') # Date is ambiguous, so need to specify day-month-year order
dateobj  = sc.readdate(1611661666) # Can read timestamps as well
dateobj  = sc.readdate(16166, dateformat='ordinal') # Or ordinal numbers of days, as used by Matplotlib
dateobjs = sc.readdate(['2020-06', '2020-07'], dateformat='%Y-%m') # Can read custom date formats
dateobjs = sc.readdate('20200321', 1611661666) # Can mix and match formats