This package emulates most of the main functions of Python's datetime lib to simplify datetime handling in TypeScript that is notoriously cumbersome in this regard. It tries to stay as close to the python API as possible - ideal if you are working with both Python and TS projects. Hope you'll find it useful!
This project is a fork of py-datetime. It ports the project to TypeScript and adds many more functions and constants from the Python datetime module.
For format string specifier directives, see the d3-time-format documentation.
npm install ts-py-datetime
This package provides a dt object which wraps all classes and constants into one object, and can be used to intantiate new dates, times, datetimes, and timedeltas with Pythonic syntax.
import dt from 'ts-py-datetime';
// const { default: dt } = await import("./src/index.ts"); in a REPL
const now = dt.datetime.now();
const today = dt.datetime.combine(now, dt.time());
console.log('Now:', now.strftime('%Y-%m-%d %H:%M:%S'));
console.log('Today:', today.strftime('%Y-%m-%d'));
console.log(
'Minutes since midnight:',
dt.timedelta(now - today).valueOf() / 60,
);You can also import the classes and constants directly, but you will have to use the new operator to instantiate them.
import { date, time, datetime, timedelta } from 'ts-py-datetime';
// const { date, time, datetime, timedelta } = await import("./src/index.ts"); in a REPL
const then = new datetime(2022, 12, 11, 10, 30, 22);
const now = datetime.now(); // static functions do not need the new operatorJavaScript/TypeScript does not support keyword arguments like Python does. As an alternative for any function that has multiple optional inputs, the first input can instead be an object with keys with the same names as the arguments.
In order to be as close to the Python datetime module as possible, any externally exposed variables, properties, and methods use Python style naming conventions instead of JavaScript/TypeScript ones. Such as date_string instead of dateString or total_seconds() instead of totalSeconds().
The smallest year number allowed in date and datetime objects. Because of JavaScript Date limitations, it's value is 100.
The largest year number allowed in date and datetime objects. It's value is 9999.
An idealized date, assuming the current Gregorian calendar always was, and always will be, in effect.
Attributes: year, month, day.
An idealized time, independent of any particular day, assuming that every day has exactly 24*60*60 seconds (There is no notion of "leap seconds" here).
Attributes: hour, minute, second, millisecond.
A combination of a date and time.
Attributes: year, month, day, hour, minute, second, millisecond, and utc.
A duration expressing the difference between two datetime or date instances to millisecond resolution.
A timedelta object represents a duration, the difference betwee two datetime or date instances.
All arguments are optional and default to 0. Arguments may be integers or floats, and may be positive or negative.
Only days, seconds, and milliseconds are stored internally. Arguments are converted to those units:
- A minute is converted to 60 seconds.
- An hour is conveted to 3600 seconds.
- A week is converted to 7 days.
and days, seconds, and milliseconds are then normalized so that the representation is unique, with
0 <= milliseconds < 10000 <= seconds < 36000*24-999999999 <= days < 999999999
The following example illustrates how any arguments besides days, seconds and milliseconds are "merged" and normalized into those three resulting attributes:
import dt from 'ts-py-datetime';
const delta = dt.timedelta({
days: 50,
seconds: 27,
milliseconds: 29100,
minutes: 5,
hours: 8,
weeks: 2,
});
// Only days, seconds, and microseconds remain
console.log(delta);
...
timedelta { days: 64, seconds: 29156, milliseconds: 100 }Any fractional milliseconds are lost, as JavaScript Date objects only support millisecond precision.
If the normalized total seconds lies outside the min and max timedelta range, RangeError is thrown.
Because of JavaScript Date limitations, the minimum and maximum timedelta values differ from Python.
The most negative timedelta object, timedelta(-100000000)
The most positive timedelta object, timedelta(100000000)
The smallest possible difference between non-equal timedelta objects, timedelta({ milliseconds: 1 })
Between -100,000,000 and 100,000,000 inclusive.
Between 0 and 86,399 inclusive.
Between 0 and 999 inclusive.
Timedelta objects can be added or subtracted to each other or to date, time, or datetime objects. Any of these operations will return a number, which can then be cast back to one of these objects using their constructors or static methods.
const delta = dt.timedelta({ days: 31 });
const datetime = dt.datetime(2013, 10, 1, 12, 11, 10);
console.log(datetime.fromtimestamp(datetime + delta));
...
datetime {
year: 2013,
month: 11,
day: 1,
hour: 12,
minute: 11,
second: 10,
millisecond: 0,
utc: false
}Return the total number of seconds contained in the duration.
For a timedelta delta, delta.valueOf() is equivalent to delta.total_seconds().
Return the days, hours, minutes, seconds, and milliseconds of the timedelta in a string format. If the timedelta is less than one day then days is not included. If the timedelta does not have a millisecond component then it is also not included.
A date object represents a date (year, month, and day) in an idealized calendar, the current Gregorian calendar indefinitely extended in both directions.
January 1 of year 1 is called day number 1, January 2 of year 1 is called day number 2, and so on.
All arguments are required. Arguments must be integers, in the following ranges:
MINYEAR <= year < MAXYEAR1 <= month <= 121 <= day <= number of days in the given month and year
If an argument is outside those ranges is given, RangeError is thrown.
Return the current local date.
Return the local date corresponding to the POSIX timestamp.
Return the date corresponding to the proleptic Gregorian ordinal, where January 1 of year 1 has ordinal 1.
The MINYEAR restriction of year 100 still applies, and any ordinal below 36160 or above 3652059 wil throw a RangeError.
Return a date corresponding to a date_string given in the ISO 8601 format YYYY-MM-DD.
Return a date corresponding to the ISO calendar date specified by year, week, and day. This is the inverse of the function date.isocalendar()
This function does not seem to work correctly, possibly due to an issue with d3-time-format.
The earliest representable date, date(MINYEAR, 1, 1).
The latest representable date, date(MAXYEAR, 12, 31).
The smallest possible difference between non-equal date objects, `timedelta({ days: 1 }).
Between MINYEAR and MAXYEAR exclusive.
Between 1 and 12 inclusive.
Between 1 and the number of days in the given month of the given year.
Date objects can be added or subtracted with timedelta objects or logically compared to other date objects. As said above all timedelta object arithmetic returns seconds which can be used to construct other objects.
const delta = dt.timedelta({ days: 1000 })
const date = dt.date( 2006, 6, 11 )
console.log(dt.date.fromtimestamp(date - delta))
...
date { year: 2003, month: 9, day: 15 }const date1 = dt.date( 2006, 6, 11 )
const date2 = dt.date( 2007, 7, 2 )
console.log(date1 < date2)
...
trueReturn a date with the same value, except for those parameters given new values by whichever arguments are specified.
Return the proleptic Gregorian ordinal ofthe date, where January 1 of year 1 has ordinal 1. For any date object d, dt.date.fromordinal(d.toordinal()) == d
The MINYEAR restriction of year 100 still applies, and any ordinal below 36160 or above 3652059 wil throw a RangeError.
Return the day of the week as an integer, where Monday is 0 and Sunday is 6. For example, dt.date(2002, 12, 4).weekday() == 2, a Wednesday.
Return the day of the week as an integer, where Monday is 1 and Sunday is 7. For example, dt.date(2002, 12, 4).isoweekday() == 3, a Wednesday.
Return an array with three components: year, week, and weekday.
The ISO calendar is a widely used variant of the Gregorian calendar.
The ISO year consists of 52 or 53 full weeks, and where a week starts on a Monday and ends on a Sunday. The first week of an ISO year is the first (Gregorian) calendar week of a year containing a Thursday. This is called week number 1, and the ISO year of that Thursday is the same as its Gregorian year.
This function does not seem to work correctly, possibly due to an issue with d3-time-format.
Return a string representing the date in ISO 8601 format, YYYY-MM-DD.
Return the POSIX timestamp of the date, assuming it's time is midnight.
For a date d, d.toString() is equivalent to d.isoformat().
Return a string representing the date, such as Wed Dec 4 00:00:00 2002.
Return a string representing the date, controlled by an explicit format string. Format codes referring to hours, minutes, or seconds will see 0 values.
A datetime object is a single object containing all the information from a date object and a time object.
Like a date object, datetime assumes the current Gregorian calendar extended in both directions; like a time object, datetime assumes there are exactly 3600*24 seconds in every day.
The year, month, and day arguments are required. The remaining arguments must be integers in the following ranges:
MINYEAR <= year <= MAXYEAR1 <= month <= 121 <= day <= number of days in the given month and year0 <= hour < 240 <= minute < 600 <= second < 600 <= millisecond < 1000
If utc is set to true, then the datetime will be treated as UTC. Otherwise it will use the local time.
Return the current local date and time.
Return the current local date and time. Functionally equivalent to dt.datetime.today() but is considered the preferred syntax.
Return the current UTC date and time.
Return the local date and time corresponding to the POSIX timestamp.
Return the UTC datetime corresponding to the POSIX timestamp.
Return the local date and time corresponding to the JS Date object.
Return the UTC datetime corresponding to the JS Date object.
Return the datetime corresponding to the proleptic Gregorian ordinal, where January 1 of year 1 has oridinal 1.
The MINYEAR restriction of year 100 still applies, and any ordinal below 36160 or above 3652059 wil throw a RangeError.
Return a new datetime object whose date components are equal to the given date object's, and whose time components are equal to the given time object's. If the date argument is a datetime object, its time components are ignored.
Return a datetime corresponding to a date_string in any valid ISO 8601 format.
Return a datetime corresponding to the ISO calendar date specified by the year, week, and day. The non-date components of the datetime are populated with their normal default values.
This function does not seem to work correctly, possibly due to an issue with d3-time-format.
Return a datetime corresponding to date_string, parsed according to format.
The earliest representable datetime, datetime(MINYEAR, 1, 1).
The latest representable datetime, datetime(MAXYEAR, 12, 31, 23, 59, 59, 999).
The smallest possible difference between non-equal datetime objects, timedelta({ milliseconds: 1 })
Between MINYEAR and MAXYEAR inclusive.
Between 1 and 12 inclusive.
Between 1 and the number of days in the given month of the given year.
Between 0 and 23 inclusive.
Between 0 and 59 inclusive.
Between 0 and 59 inclusive.
Between 0 and 999 inclusive.
Datetime objects can be added or subtracted with timedelta objects or logically compared to other datetime objects. As said above all timedelta object arithmetic returns seconds which can be used to construct other objects.
const delta = dt.timedelta({ days: 31 });
const datetime = dt.datetime(2013, 10, 1, 12, 11, 10);
console.log(datetime.fromtimestamp(datetime + delta));
...
datetime {
year: 2013,
month: 11,
day: 1,
hour: 12,
minute: 11,
second: 10,
millisecond: 0,
utc: false
}const datetime1 = dt.datetime(2006, 6, 11, 5, 2, 30)
const datetime2 = dt.datetime(2007, 7, 2, 22, 30, 7, 332)
console.log(datetime1 < datetime2)
...
trueReturn date object with same year, month, and day.
Return time object with same hour, minute, second, and millisecond.
datetime.replace({ year: this.year, month: this.month, day: this.day, hour: this.hour, minute: this.minute, second: this.second, millisecond: this.millisecond, utc: this.utc })
Return a datetime with the same attributes, except for those attributes given new values by whichever arguments are specified.
Return the proleptic Gregorian ordinal of the date.
Return the POSIX timestamp corresponding to the datetime instance.
Return the day of the week as an integer, where Monday is 0 and Sunday is 6.
Return the day of the week as an integer, where Monday is 1 and Sunday is 7.
Return an array with three components: year, week, and weekday.
This function does not seem to work correctly, possibly due to an issue with d3-time-format.
Return a string representing the date and time in ISO 8601 format.
The optional argument sep is a one-character separator, placed between the date and time portions of the result.
The optional argument timespec specifies the number of additional components of the time to include. It can be one of the following:
auto: Same assecondsif millisecond is 0, same asmillisecondsotherwise.hours: Include thehourin the two-digitHHformat.minutes: IncludehourandminuteinHH:MMformat.seconds: Includehour,minute, andsecondinHH:MM:SSformat.milliseconds: Include full time inHH:MM:SS.fffformat.
For a datetime instance d, d.valueOf() is equivalent to d.timestamp().
For a datetime instance d, d.toString() is equivalent to d.isoformat(' ').
Return a string representing the date and time, such as Wed Dec 4 20:30:40 2002.
Return a string representing the date and time, controlled by an explicit format string.
A time object represents a (local) time of day, independent of any particular day.
All arguments are optional. The remaining arguments must be integers in the following range:
0 <= hour < 240 <= minute < 600 <= second < 600 <= millisecond < 1000
If an argument outside those ranges is given, RangeError is thrown. All default to 0.
The earliest representable time, time(0, 0, 0, 0).
The latest representable time, time(23, 59, 59, 999).
The smallest possible difference between non-equal time objects, timedelta({ microseconds: 1 }).
Between 0 and 23 inclusive.
Between 0 and 59 inclusive.
Between 0 and 59 inclusive.
Between 0 and 999 inclusive.
Return a time corresponding to a time_string in any valid ISO 8601 format.
time.replace({ hour: this.hour, minute: this.minute, second: this.second, millisecond: this.millisecond })
Return a time with the ame value, except for those attributes given new values by whichever arguments are specified.
Return a string representing the time in ISO 8601 format. The optional argument timespec specifies the number of additional components of the time to include (the default is auto). It can be one of the following:
auto: Same assecondsifmillisecondis 0, same asmillisecondsotherwise.hours: Include thehourin the two-digitHHformat.minutes: IncludehourandminuteinHH:MMformat.seconds: Includehour,minute, andsecondinHH:MM:SSformat.milliseconds: Include full time inHH:MM:SS.fffformat.
Return the time in seconds.
For a time t, t.valueOf() is equivalent to t.isoformat().
Return a string representing the time, controlled by an explicit format string.