cftime_rs#

Subpackages#

Submodules#

Package Contents#

Classes#

PyCFCalendar

PyCFCalendar represents a calendar object.

PyCFDuration

PyCFDuration is a wrapper around Rust CFDuration.

PyCFDatetime

PyCFDatetime is a wrapper around Rust CFDatetime.

Functions#

num2date(→ List[PyCFDatetime])

Convert a list of numbers to PyCFDatetime objects based on the specified calendar.

num2pydate(→ List[datetime.datetime])

Convert a list of numbers to datetime objects based on the specified calendar.

date2num(→ Union[int, float])

Convert a list of PyCFDatetime objects to a list of numbers based on calendar, units, and dtype.

pydate2num(→ Union[int, float])

Convert a list of python datetime to a list of numbers based on calendar, units, and dtype.
class cftime_rs.PyCFCalendar[source]#

PyCFCalendar represents a calendar object.

static from_str(s: str) → PyCFCalendar[source]#

Create a PyCFCalendar from a string representation.

Parameters:

s (str) – The string representation of the calendar.

Returns:

A PyCFCalendar object.

Return type:

PyCFCalendar

Raises:

ValueError – If the calendar string cannot be parsed.

class cftime_rs.PyCFDuration[source]#

PyCFDuration is a wrapper around Rust CFDuration.

All the methods depend on the Calendar definitions found in [udunits package](nco/nco).

This duration can be added to a PyCFDatetime. The result of the subtraction between two PyCFDatetime objects gives a PyCFDuration.

classmethod from_years(years: int, calendar: PyCFCalendar) → PyCFDuration[source]#

Makes a new PyCFDuration with the given number of years and specific calendar.

Parameters:

  • years (int) – Number of years.

  • calendar (PyCFCalendar) – The calendar for the duration.

Returns:

A new PyCFDuration object.

Return type:

PyCFDuration

classmethod from_month(month: int, calendar: PyCFCalendar) → PyCFDuration[source]#

Makes a new PyCFDuration with the given number of month and specific calendar.

Parameters:

  • month (int) – Number of month.

  • calendar (PyCFCalendar) – The calendar for the duration.

Returns:

A new PyCFDuration object.

Return type:

PyCFDuration

classmethod from_weeks(weeks: int, calendar: PyCFCalendar) → PyCFDuration[source]#

Makes a new PyCFDuration with the given number of weeks and specific calendar.

Parameters:

  • weeks (int) – Number of weeks.

  • calendar (PyCFCalendar) – The calendar for the duration.

Returns:

A new PyCFDuration object.

Return type:

PyCFDuration

classmethod from_days(days: int, calendar: PyCFCalendar) → PyCFDuration[source]#

Makes a new PyCFDuration with the given number of days and specific calendar.

Parameters:

  • days (int) – Number of days.

  • calendar (PyCFCalendar) – The calendar for the duration.

Returns:

A new PyCFDuration object.

Return type:

PyCFDuration

classmethod from_hours(hours: int, calendar: PyCFCalendar) → PyCFDuration[source]#

Makes a new PyCFDuration with the given number of hours and specific calendar.

Parameters:

  • hours (int) – Number of hours.

  • calendar (PyCFCalendar) – The calendar for the duration.

Returns:

A new PyCFDuration object.

Return type:

PyCFDuration

classmethod from_minutes(minutes: int, calendar: PyCFCalendar) → PyCFDuration[source]#

Makes a new PyCFDuration with the given number of minutes and specific calendar.

Parameters:

  • minutes (int) – Number of minutes.

  • calendar (PyCFCalendar) – The calendar for the duration.

Returns:

A new PyCFDuration object.

Return type:

PyCFDuration

classmethod from_seconds(seconds: int, calendar: PyCFCalendar) → PyCFDuration[source]#

Makes a new PyCFDuration with the given number of seconds and specific calendar.

Parameters:

  • seconds (int) – Number of seconds.

  • calendar (PyCFCalendar) – The calendar for the duration.

Returns:

A new PyCFDuration object.

Return type:

PyCFDuration

classmethod from_milliseconds(milliseconds: int, calendar: PyCFCalendar) → PyCFDuration[source]#

Makes a new PyCFDuration with the given number of milliseconds and specific calendar.

Parameters:

  • milliseconds (int) – Number of milliseconds.

  • calendar (PyCFCalendar) – The calendar for the duration.

Returns:

A new PyCFDuration object.

Return type:

PyCFDuration

classmethod from_microseconds(microseconds: int, calendar: PyCFCalendar) → PyCFDuration[source]#

Makes a new PyCFDuration with the given number of microseconds and specific calendar.

Parameters:

  • microseconds (int) – Number of microseconds.

  • calendar (PyCFCalendar) – The calendar for the duration.

Returns:

A new PyCFDuration object.

Return type:

PyCFDuration

classmethod from_nanoseconds(nanoseconds: int, calendar: PyCFCalendar) → PyCFDuration[source]#

Makes a new PyCFDuration with the given number of nanoseconds and specific calendar.

Parameters:

  • nanoseconds (int) – Number of nanoseconds.

  • calendar (PyCFCalendar) – The calendar for the duration.

Returns:

A new PyCFDuration object.

Return type:

PyCFDuration

num_years() → float[source]#

Returns the total number of years in the duration.

Returns:

Number of years.

Return type:

float

num_months() → float[source]#

Returns the total number of months in the duration.

Returns:

Number of months.

Return type:

float

num_weeks() → float[source]#

Returns the total number of weeks in the duration.

Returns:

Number of weeks.

Return type:

float

num_days() → float[source]#

Returns the total number of days in the duration.

Returns:

Number of days.

Return type:

float

num_hours() → float[source]#

Returns the total number of hours in the duration.

Returns:

Number of hours.

Return type:

float

num_minutes() → float[source]#

Returns the total number of minutes in the duration.

Returns:

Number of minutes.

Return type:

float

num_seconds() → float[source]#

Returns the total number of seconds in the duration.

Returns:

Number of seconds.

Return type:

float

num_milliseconds() → float[source]#

Returns the total number of milliseconds in the duration.

Returns:

Number of milliseconds.

Return type:

float

num_microseconds() → float[source]#

Returns the total number of microseconds in the duration.

Returns:

Number of microseconds.

Return type:

float

num_nanoseconds() → float[source]#

Returns the total number of nanoseconds in the duration.

Returns:

Number of nanoseconds.

Return type:

float

class cftime_rs.PyCFDatetime[source]#

PyCFDatetime is a wrapper around Rust CFDatetime.

It represents a date in a specific calendar.

All the methods depend on the Calendar definitions found in [udunits package](nco/nco).

classmethod new(year: int, month: int, day: int, hour: int, minute: int, second: float, calendar: PyCFCalendar) → PyCFDatetime[source]#

Makes a new PyCFDatetime with given year, month, day, hour, minute, second, and specific calendar.

Parameters:

  • year (int) – The year.

  • month (int) – The month.

  • day (int) – The day.

  • hour (int) – The hour.

  • minute (int) – The minute.

  • second (float) – The second.

  • calendar (PyCFCalendar) – The calendar for the datetime.

Returns:

A new PyCFDatetime object.

Return type:

PyCFDatetime

ymd() → Tuple[int, int, int][source]#

Returns the year, month, and day of the date.

Returns:

A tuple of (year, month, day).

Return type:

Tuple[int, int, int]

hms() → Tuple[int, int, int][source]#

Returns the hour, minute, and second of the time.

Returns:

A tuple of (hour, minute, second).

Return type:

Tuple[int, int, int]

ymd_hms() → Tuple[int, int, int, int, int, int][source]#

Returns the year, month, day, hour, minute, and second of the datetime.

Returns:

A tuple of (year, month, day, hour, minute, second).

Return type:

Tuple[int, int, int, int, int, int]

classmethod from_ymd_hms(year: int, month: int, day: int, hour: int, minute: int, second: float, calendar: PyCFCalendar) → PyCFDatetime[source]#

Makes a new PyCFDatetime with given year, month, day, hour, minute, second, and specific calendar.

Parameters:

  • year (int) – The year.

  • month (int) – The month.

  • day (int) – The day.

  • hour (int) – The hour.

  • minute (int) – The minute.

  • second (float) – The second.

  • calendar (PyCFCalendar) – The calendar for the datetime.

Returns:

A new PyCFDatetime object.

Return type:

PyCFDatetime

classmethod from_hms(hour: int, minute: int, second: float, calendar: PyCFCalendar) → PyCFDatetime[source]#

Makes a new PyCFDatetime with given hour, minute, second, and specific calendar. The year, month, and day are set to 1970-01-01.

Parameters:

  • hour (int) – The hour.

  • minute (int) – The minute.

  • second (float) – The second.

  • calendar (PyCFCalendar) – The calendar for the datetime.

Returns:

A new PyCFDatetime object.

Return type:

PyCFDatetime

classmethod from_ymd(year: int, month: int, day: int, calendar: PyCFCalendar) → PyCFDatetime[source]#

Makes a new PyCFDatetime with given year, month, day, and specific calendar. The hour, minute, and second are set to 0.

Parameters:

  • year (int) – The year.

  • month (int) – The month.

  • day (int) – The day.

  • calendar (PyCFCalendar) – The calendar for the datetime.

Returns:

A new PyCFDatetime object.

Return type:

PyCFDatetime

classmethod from_timestamp(timestamp: int, nanoseconds: int, calendar: PyCFCalendar) → PyCFDatetime[source]#

Makes a new PyCFDatetime with given timestamp, nanoseconds, and specific calendar.

Parameters:

  • timestamp (int) – The timestamp.

  • nanoseconds (int) – The nanoseconds.

  • calendar (PyCFCalendar) – The calendar for the datetime.

Returns:

A new PyCFDatetime object.

Return type:

PyCFDatetime

change_calendar(calendar: PyCFCalendar) → PyCFDatetime[source]#

Change the calendar of the PyCFDatetime.

This can be considered as safe as this method try to recreate the datetime with the same year, month, day, hour, minute, second and nanoseconds.

Parameters:

calendar (PyCFCalendar) – The calendar for the datetime.

Returns:

A new PyCFDatetime object.

Return type:

PyCFDatetime

Raises:

ValueError – If the date is not possible in the target calendar.

change_calendar_from_timestamp(calendar: PyCFCalendar) → PyCFDatetime[source]#

Change the calendar of the CFDatetime using the timestamp

Be aware that there is highly chance that the two dates do not correspond. However their distances from epoch are the same.

Parameters:

calendar (PyCFCalendar) – The calendar for the datetime.

Returns:

A new PyCFDatetime object.

Return type:

PyCFDatetime

Raises:

ValueError – If the date is not possible in the target calendar.

to_pydatetime() → datetime.datetime[source]#

Converts the object to a Python datetime object using year, month, day, hour, minute, and second

Returns:

A datetime object representing the same date and time as the object.

Raises:

ValueError – If the date cannot be converted to a datetime

to_pydatetime_from_timestamp() → datetime.datetime[source]#

Converts the object to a Python datetime object using the timestamp

Returns:

A datetime object representing the same underlying timestamp

Raises:

ValueError – If the date cannot be converted to a datetime

cftime_rs.num2date(arr: Iterable[int | float], units: str, calendar: str) → List[PyCFDatetime][source]#

Convert a list of numbers to PyCFDatetime objects based on the specified calendar.

Parameters:

  • arr – Iterable[Union[int, float]] Array of numbers to convert to PyCFDatetime

  • units – str Valid CF units

  • calendar – str CF calendar name. Should be one of “standard”, “gregorian”, “proleptic_gregorian”, “julian”, “all_leap”, “no_leap”, “360_day”, “365_day”, “366_day”. If the calendar is not recognized, “standard” will be used

Raises:

ValueError – If the date is not valid in the calendar

Returns:

List[PyCFDatetime]

List of PyCFDatetime objects

cftime_rs.num2pydate(arr: Iterable[int | float], units: str, calendar: str, from_timestamp: bool = False) → List[datetime.datetime][source]#

Convert a list of numbers to datetime objects based on the specified calendar.

Parameters:

  • arr – Iterable[Union[int, float]] Array of numbers to convert to datetime

  • units – str Valid CF units

  • calendar – str CF calendar name. Should be one of “standard”, “gregorian”, “proleptic_gregorian”, “julian”, “all_leap”, “no_leap”, “360_day”, “365_day”, “366_day”. If the calendar is not recognized, “standard” will be used

  • from_timestamp – bool If True, the date will be converted using timestamp value from epoch and python datetime .from_timestamp method will be used. This method guarantee that the date is valid if no overflow occurs. While the distance from epoch is the same, the date are likely to be different. If False, the date will be converted using python datetime constructor method : the year, month, day, hour, minute, second and nanoseconds will be extyracted from PyCFDatetime object and given back to python datetime constructor. There is no guarantee that the date is valid in the calendar. This method is also considerably slower than using the timestamp. Default value is False.

Raises:

ValueError – If the date is not valid in the calendar

Returns:

List[datetime.datetime]

List of datetime.datetime objects

cftime_rs.date2num(datetimes: List[PyCFDatetime], units: str, calendar: str, dtype: str) → int | float[source]#

Convert a list of PyCFDatetime objects to a list of numbers based on calendar, units, and dtype.

Parameters:

  • datetimes – List[PyCFDatetime] List of PyCFDatetime objects

  • units – str Valid CF units

  • calendar – str CF calendar name. Should be one of “standard”, “gregorian”,

  • dtype – str 32 bit integer : “i32” 64 bit integer : “i64”, “i”, “integer”, “int” 32 bit float : “f32” 64 bit float : “f64”, “f”, “float”

Raises:

  • ValueError – If the date is not valid in the calendar

  • ValueError – If the dtype is not recognized

Returns:

Union[int, float]

List of numbers based on calendar, units, and dtype

cftime_rs.pydate2num(datetimes: List[datetime.datetime], units: str, calendar: str, dtype: str) → int | float[source]#

Convert a list of python datetime to a list of numbers based on calendar, units, and dtype.

Since the backend is implemented in Rust, we need to call python datetimes arguments in order to convert them to rust object. This inevitably leads to a lot of overhead and lower performance thant using num2date.

Parameters:

  • datetimes – List[datetime.datetime] List of python datetime.datetime objects

  • units – str Valid CF units

  • calendar – str CF calendar name. Should be one of “standard”, “gregorian”,

  • dtype – str 32 bit integer : “i32” 64 bit integer : “i64”, “i”, “integer”, “int” 32 bit float : “f32” 64 bit float : “f64”, “f”, “float”

Raises:

  • ValueError – If the date is not valid in the calendar

  • ValueError – If the dtype is not recognized

Returns:

Union[int, float]

List of numbers based on calendar, units, and dtype