datetime64("now") is undocumented #10003

Activity

1. eric-wieser

   added

   04 - Documentation

   on Nov 12, 2017
2. shoyer commented on Nov 12, 2017

   

   shoyer

   on Nov 12, 2017

   Member

   More actions

   See here for the underlying C-function:
   

   numpy/numpy/core/src/multiarray/datetime_strings.c

   Lines 189 to 219 in 6582813

   	/*
   	* Parses (almost) standard ISO 8601 date strings. The differences are:
   	*
   	* + The date "20100312" is parsed as the year 20100312, not as
   	* equivalent to "2010-03-12". The '-' in the dates are not optional.
   	* + Only seconds may have a decimal point, with up to 18 digits after it
   	* (maximum attoseconds precision).
   	* + Either a 'T' as in ISO 8601 or a ' ' may be used to separate
   	* the date and the time. Both are treated equivalently.
   	* + Doesn't (yet) handle the "YYYY-DDD" or "YYYY-Www" formats.
   	* + Doesn't handle leap seconds (seconds value has 60 in these cases).
   	* + Doesn't handle 24:00:00 as synonym for midnight (00:00:00) tomorrow
   	* + Accepts special values "NaT" (not a time), "Today", (current
   	* day according to local time) and "Now" (current time in UTC).
   	*
   	* 'str' must be a NULL-terminated string, and 'len' must be its length.
   	* 'unit' should contain -1 if the unit is unknown, or the unit
   	* which will be used if it is.
   	* 'casting' controls how the detected unit from the string is allowed
   	* to be cast to the 'unit' parameter.
   	*
   	* 'out' gets filled with the parsed date-time.
   	* 'out_bestunit' gives a suggested unit based on the amount of
   	* resolution provided in the string, or -1 for NaT.
   	* 'out_special' gets set to 1 if the parsed time was 'today',
   	* 'now', or ''/'NaT'. For 'today', the unit recommended is
   	* 'D', for 'now', the unit recommended is 's', and for 'NaT'
   	* the unit recommended is 'Y'.
   	*
   	* Returns 0 on success, -1 on failure.
   	*/

   Note that it also supports the string "today" indicating a local time.

   If we're going to document it, we should probably make sure that the functionality makes sense. In the most recent version of datetime64, we aim for compatibility with Python's datetime module (without timezones). So it's a little strange that "now" means UTC rather than local time (see https://docs.python.org/2/library/datetime.html#datetime.datetime.now) Arguably, we should use something different like "utcnow" for UTC.

   The precision issue could potentially be improved, possibly by switching to rely on Python's time.time() rather than our own implementation. For now it would indeed make sense to document the (potentially) limited precision.
3. mohdsanadzakirizvi commented on Dec 24, 2017

   

   mohdsanadzakirizvi

   on Dec 24, 2017

   More actions

   Would like to work on this as my first contribution, is it open ?
4. shoyer commented on Dec 24, 2017

   

   shoyer

   on Dec 24, 2017

   Member

   More actions

   As noted above, I think we should probably clean up this functionality before documenting it, which would encourage more people to rely on functionality that would likely change.
5. mattip

   added

   01 - Enhancement

   component: numpy.datetime64(and timedelta64)(and timedelta64)

   on Sep 4, 2018
6. gosuto-inzasheru commented on Feb 9, 2020

   

   gosuto-inzasheru

   on Feb 9, 2020

   More actions

   Yeah the precision thing is quite misleading I think, passing 'ms' only increases the size of the float.
7. Shreyjaradi commented on May 20, 2024

   

   Shreyjaradi

   on May 20, 2024

   More actions

   I have raised an PR to add the example of np.datetime64("now", "ms")
   #26477