Timestamp

class Timestamp

Pandas-compatible Timestamp representing a single moment in time.

Example

import pandasCore as pd

# Create Timestamp
obj = pd.Timestamp(...)

Attributes

Attribute	Description	Example
day	Return the day of the month (1-31)	View
day_of_week	Return the day of the week (0=Monday, 6=Sunday)
day_of_year	Return the day of the year (1-366)
dayofweek	Return the day of the week (0=Monday, 6=Sunday)	View
dayofyear	Return the day of the year (1-366)	View
days_in_month	Return the number of days in the month
fold	Return the fold value for DST disambiguation
hour	Return the hour (0-23)	View
is_leap_year	Return True if the year is a leap year
is_month_end	Return True if the date is the last day of the month
is_month_start	Return True if the date is the first day of the month
is_quarter_end	Return True if the date is the last day of the quarter
is_quarter_start	Return True if the date is the first day of the quarter
is_year_end	Return True if the date is the last day of the year
is_year_start	Return True if the date is the first day of the year
isnat	Return True if the Timestamp is NaT (Not a Timestamp)
microsecond	Return the microsecond (0-999999)	View
minute	Return the minute (0-59)	View
month	Return the month (1-12)	View
nanosecond	Return the nanosecond (0-999)	View
quarter	Return the quarter (1-4)	View
second	Return the second (0-59)	View
tz	Return the timezone name
tzinfo	Return the timezone name
value	Return the value as nanoseconds since epoch	View
week	Return the ISO week number (1-53)
weekofyear	Return the ISO week number (1-53)
year	Return the year	View

Construction

Method	Description	Example
__init__() (ts_input: object = None, year: object = None, month: object = None, day: object = None, hour: object = None, minute: object = None, second: object = None, microsecond: object = None, tzinfo: object = None, *, nanosecond: object = None, tz: object = None, unit: object = None, fold: object = None)	Create a Timestamp from various inputs (pandas-compatible).	View

Data Manipulation

Method	Description	Example
replace() (year: object = None, month: object = None, day: object = None, hour: object = None, minute: object = None, second: object = None, microsecond: object = None, nanosecond: object = None, tzinfo: object = None, fold: object = None)	Return Timestamp with fields replaced.	View

Arithmetic

Method	Description	Example
__add__() (*args, **kwargs) | (arg0: numpy::timedelta64) | (arg0: object)
__sub__() (*args, **kwargs) | (arg0: numpy::timedelta64) | (arg0: pandasCore.Timestamp) | (arg0: object)

Comparison

Method	Description	Example
__eq__() (arg0: pandasCore.Timestamp)
__ge__() (arg0: pandasCore.Timestamp)
__gt__() (arg0: pandasCore.Timestamp)
__le__() (arg0: pandasCore.Timestamp)
__lt__() (arg0: pandasCore.Timestamp)
__ne__() (arg0: pandasCore.Timestamp)

Time Series

Method	Description	Example
to_period() (freq: object = None)	Convert Timestamp to a Period.
tz_convert() (tz: str)	Convert tz-aware Timestamp to another timezone.
tz_localize() (tz: object, ambiguous: str = 'raise', nonexistent: str = 'raise')	Localize tz-naive Timestamp to a timezone.

I/O

Method	Description	Example
to_datetime64() ()	Return as numpy datetime64 value
to_julian_date() ()	Return the Julian Date
to_numpy() (dtype: object = None, copy: bool = False)	Return as numpy datetime64 value
to_pydatetime() (warn: bool = True)	Convert Timestamp to a Python datetime.datetime object.

Datetime Methods

Method	Description	Example
ceil() (freq: str, ambiguous: str = 'raise', nonexistent: str = 'raise')	Round up the Timestamp to the specified resolution.	View
floor() (freq: str, ambiguous: str = 'raise', nonexistent: str = 'raise')	Round down the Timestamp to the specified resolution.	View
normalize() ()	Normalize Timestamp to midnight, preserving tz information.	View
round() (freq: str, ambiguous: str = 'raise', nonexistent: str = 'raise')	Round the Timestamp to the specified resolution.	View
strftime() (format: str)	Return a string representing the Timestamp, controlled by a format …	View
weekday() ()	Return the day of the week (0=Monday, 6=Sunday)

Other Methods

Method	Description	Example
__hash__() ()
__repr__() ()
__str__() ()
as_unit() (unit: str, round_ok: bool = True)	Convert Timestamp to target unit resolution.
astimezone() (tz: str)	Convert tz-aware Timestamp to another timezone
ctime() ()	Return ctime() style string
date() ()	Return a datetime.date object
day_name() (locale: object = None)	Return the name of the day of the week	View
dst() ()	Return the daylight saving time (DST) offset.
isocalendar() ()	Return a tuple containing ISO year, week number, and weekday.	View
isoformat() (sep: str = 'T', timespec: str = 'auto')	Return the time formatted according to ISO 8601.	View
isoweekday() ()	Return the ISO weekday (1=Monday, 7=Sunday)
month_name() (locale: object = None)	Return the name of the month	View
time() ()	Return a datetime.time object
timestamp() ()	Return POSIX timestamp as float (seconds since epoch).	View
timetuple() ()	Return time tuple, compatible with time.localtime().
timetz() ()	Return a datetime.time object with timezone info
toordinal() ()	Return the proleptic Gregorian ordinal
tzname() ()	Return the timezone abbreviation
utcoffset() ()	Return the UTC offset.
utctimetuple() ()	Return UTC time tuple

Code Examples

The following examples are extracted from the test suite.

day (test_timestamp.py:51)

            return False

        # Check month
        if ts.month == 1:
            f_print_success(f"month is correct: {ts.month}")
        else:
            f_print_error(f"month is wrong: {ts.month}, expected 1")
            return False

        # Check day
        if ts.day == 15:
            f_print_success(f"day is correct: {ts.day}")
        else:
            f_print_error(f"day is wrong: {ts.day}, expected 15")
            return False

        # Check hour
        if ts.hour == 12:
            f_print_success(f"hour is correct: {ts.hour}")
        else:
            f_print_error(f"hour is wrong: {ts.hour}, expected 12")

dayofweek (test_timestamp.py:192)

def test_derived_properties():
    """Test Timestamp derived properties"""
    f_print_header("Test: Timestamp Derived Properties")

    try:
        # Create a Timestamp for 2021-01-15 (Friday)
        ts = pandasCore.Timestamp(2021, 1, 15, 12, 0, 0)

        # dayofweek (0=Monday, 6=Sunday) - Friday is 4
        if ts.dayofweek == 4:
            f_print_success(f"dayofweek is correct: {ts.dayofweek} (Friday)")
        else:
            f_print_error(f"dayofweek is wrong: {ts.dayofweek}, expected 4 (Friday)")
            return False

        # dayofyear - Jan 15 is day 15
        if ts.dayofyear == 15:
            f_print_success(f"dayofyear is correct: {ts.dayofyear}")
        else:
            f_print_error(f"dayofyear is wrong: {ts.dayofyear}, expected 15")

dayofyear (test_timestamp.py:199)

        ts = pandasCore.Timestamp(2021, 1, 15, 12, 0, 0)

        # dayofweek (0=Monday, 6=Sunday) - Friday is 4
        if ts.dayofweek == 4:
            f_print_success(f"dayofweek is correct: {ts.dayofweek} (Friday)")
        else:
            f_print_error(f"dayofweek is wrong: {ts.dayofweek}, expected 4 (Friday)")
            return False

        # dayofyear - Jan 15 is day 15
        if ts.dayofyear == 15:
            f_print_success(f"dayofyear is correct: {ts.dayofyear}")
        else:
            f_print_error(f"dayofyear is wrong: {ts.dayofyear}, expected 15")
            return False

        # quarter
        if ts.quarter == 1:
            f_print_success(f"quarter is correct: {ts.quarter}")
        else:
            f_print_error(f"quarter is wrong: {ts.quarter}, expected 1")

hour (test_timestamp.py:58)

            return False

        # Check day
        if ts.day == 15:
            f_print_success(f"day is correct: {ts.day}")
        else:
            f_print_error(f"day is wrong: {ts.day}, expected 15")
            return False

        # Check hour
        if ts.hour == 12:
            f_print_success(f"hour is correct: {ts.hour}")
        else:
            f_print_error(f"hour is wrong: {ts.hour}, expected 12")
            return False

        # Check minute
        if ts.minute == 30:
            f_print_success(f"minute is correct: {ts.minute}")
        else:
            f_print_error(f"minute is wrong: {ts.minute}, expected 30")

microsecond (test_timestamp.py:79)

            return False

        # Check second
        if ts.second == 45:
            f_print_success(f"second is correct: {ts.second}")
        else:
            f_print_error(f"second is wrong: {ts.second}, expected 45")
            return False

        # Check microsecond
        if ts.microsecond == 123456:
            f_print_success(f"microsecond is correct: {ts.microsecond}")
        else:
            f_print_error(f"microsecond is wrong: {ts.microsecond}, expected 123456")
            return False

        # Check nanosecond
        if ts.nanosecond == 789:
            f_print_success(f"nanosecond is correct: {ts.nanosecond}")
        else:
            f_print_error(f"nanosecond is wrong: {ts.nanosecond}, expected 789")

minute (test_timestamp.py:65)

            return False

        # Check hour
        if ts.hour == 12:
            f_print_success(f"hour is correct: {ts.hour}")
        else:
            f_print_error(f"hour is wrong: {ts.hour}, expected 12")
            return False

        # Check minute
        if ts.minute == 30:
            f_print_success(f"minute is correct: {ts.minute}")
        else:
            f_print_error(f"minute is wrong: {ts.minute}, expected 30")
            return False

        # Check second
        if ts.second == 45:
            f_print_success(f"second is correct: {ts.second}")
        else:
            f_print_error(f"second is wrong: {ts.second}, expected 45")

month (test_timestamp.py:44)

        f_print_success("Created Timestamp from components")

        # Check year
        if ts.year == 2021:
            f_print_success(f"year is correct: {ts.year}")
        else:
            f_print_error(f"year is wrong: {ts.year}, expected 2021")
            return False

        # Check month
        if ts.month == 1:
            f_print_success(f"month is correct: {ts.month}")
        else:
            f_print_error(f"month is wrong: {ts.month}, expected 1")
            return False

        # Check day
        if ts.day == 15:
            f_print_success(f"day is correct: {ts.day}")
        else:
            f_print_error(f"day is wrong: {ts.day}, expected 15")

nanosecond (test_timestamp.py:86)

            return False

        # Check microsecond
        if ts.microsecond == 123456:
            f_print_success(f"microsecond is correct: {ts.microsecond}")
        else:
            f_print_error(f"microsecond is wrong: {ts.microsecond}, expected 123456")
            return False

        # Check nanosecond
        if ts.nanosecond == 789:
            f_print_success(f"nanosecond is correct: {ts.nanosecond}")
        else:
            f_print_error(f"nanosecond is wrong: {ts.nanosecond}, expected 789")
            return False

        # Check repr
        repr_str = repr(ts)
        f_print_info(f"repr: {repr_str}")

        return True

quarter (test_timestamp.py:206)

            return False

        # dayofyear - Jan 15 is day 15
        if ts.dayofyear == 15:
            f_print_success(f"dayofyear is correct: {ts.dayofyear}")
        else:
            f_print_error(f"dayofyear is wrong: {ts.dayofyear}, expected 15")
            return False

        # quarter
        if ts.quarter == 1:
            f_print_success(f"quarter is correct: {ts.quarter}")
        else:
            f_print_error(f"quarter is wrong: {ts.quarter}, expected 1")
            return False

        # Create a Timestamp for leap year check (2020)
        ts_leap = pandasCore.Timestamp(2020, 2, 29, 0, 0, 0)
        if ts_leap.is_leap_year:
            f_print_success("is_leap_year is correct: True for 2020")
        else:

second (test_timestamp.py:72)

            return False

        # Check minute
        if ts.minute == 30:
            f_print_success(f"minute is correct: {ts.minute}")
        else:
            f_print_error(f"minute is wrong: {ts.minute}, expected 30")
            return False

        # Check second
        if ts.second == 45:
            f_print_success(f"second is correct: {ts.second}")
        else:
            f_print_error(f"second is wrong: {ts.second}, expected 45")
            return False

        # Check microsecond
        if ts.microsecond == 123456:
            f_print_success(f"microsecond is correct: {ts.microsecond}")
        else:
            f_print_error(f"microsecond is wrong: {ts.microsecond}, expected 123456")

value (test_date_range_comp.py:42)

# Helpers
# =============================================================================

def _compare_lengths(pd_idx, pc_idx, label):
    """Compare index lengths between pandas and pandasCore."""
    ctx.assert_equal(len(pd_idx), len(pc_idx), f"{label} length")


def _pd_to_ns(ts):
    """Convert pandas Timestamp to nanoseconds since epoch."""
    return int(ts.value)


def _compare_first_last(pd_idx, pc_idx, label):
    """Compare first/last values by nanosecond epoch."""
    pd_first = _pd_to_ns(pd_idx[0])
    pd_last = _pd_to_ns(pd_idx[len(pd_idx) - 1])
    pc_first = int(pc_idx[0])
    pc_last = int(pc_idx[len(pc_idx) - 1])
    ctx.assert_equal(pd_first, pc_first, f"{label} first value")
    ctx.assert_equal(pd_last, pc_last, f"{label} last value")

year (test_timestamp.py:37)

def test_construction_from_components():
    """Test Timestamp construction from date/time components"""
    f_print_header("Test: Timestamp Construction from Components")

    try:
        # Create Timestamp from components
        ts = pandasCore.Timestamp(2021, 1, 15, 12, 30, 45, 123456, 789)
        f_print_success("Created Timestamp from components")

        # Check year
        if ts.year == 2021:
            f_print_success(f"year is correct: {ts.year}")
        else:
            f_print_error(f"year is wrong: {ts.year}, expected 2021")
            return False

        # Check month
        if ts.month == 1:
            f_print_success(f"month is correct: {ts.month}")
        else:
            f_print_error(f"month is wrong: {ts.month}, expected 1")

__init__ (test_dateoffset_comp.py:42)

# ==================== apply() Tests ====================
# Note: pandas 2.x removed public .apply() on offsets.
# We compare pandasCore apply() results against ts + offset in pandas.

def test_day_apply():
    """Test Day.apply() matches pandas ts + offset"""
    f_print_header("Test: Day.apply()")

    pc_day = pandasCore.Day(n=1)
    pc_ts = pandasCore.Timestamp('2023-01-15')
    pc_result = pc_day.apply(pc_ts)

    pd_ts = pd.Timestamp('2023-01-15')
    pd_result = pd_ts + pd.offsets.Day(n=1)

    ctx.assert_equal(str(pd_result)[:10], str(pc_result)[:10], "Day(1).apply(Jan 15)")

    # Multi-day
    pc_day5 = pandasCore.Day(n=5)
    pc_r5 = pc_day5.apply(pc_ts)

replace (test_timestamp.py:412)

def test_replace_method():
    """Test Timestamp replace method"""
    f_print_header("Test: Timestamp replace Method")

    try:
        ts = pandasCore.Timestamp(2021, 1, 15, 12, 30, 45)

        # Replace year
        ts_new_year = ts.replace(year=2022)
        if ts_new_year.year == 2022 and ts_new_year.month == 1 and ts_new_year.day == 15:
            f_print_success(f"replace(year=2022) correct: {ts_new_year.year}-{ts_new_year.month}-{ts_new_year.day}")
        else:
            f_print_error(f"replace(year=2022) wrong")
            return False

        # Replace month and day
        ts_new_date = ts.replace(month=6, day=20)
        if ts_new_date.year == 2021 and ts_new_date.month == 6 and ts_new_date.day == 20:
            f_print_success(f"replace(month=6, day=20) correct: {ts_new_date.year}-{ts_new_date.month}-{ts_new_date.day}")

ceil (test_timestamp.py:312)

        # Floor to hour
        ts_floor = ts.floor("H")
        if ts_floor.hour == 14 and ts_floor.minute == 0 and ts_floor.second == 0:
            f_print_success(f"floor('H') correct: {ts_floor.hour}:{ts_floor.minute}:{ts_floor.second}")
        else:
            f_print_error(f"floor('H') wrong: {ts_floor.hour}:{ts_floor.minute}:{ts_floor.second}")
            return False

        # Ceil to hour
        ts_ceil = ts.ceil("H")
        if ts_ceil.hour == 15 and ts_ceil.minute == 0:
            f_print_success(f"ceil('H') correct: {ts_ceil.hour}:{ts_ceil.minute}:{ts_ceil.second}")
        else:
            f_print_error(f"ceil('H') wrong: {ts_ceil.hour}:{ts_ceil.minute}:{ts_ceil.second}")
            return False

        # Round to hour (37 minutes rounds down)
        ts_round = ts.round("H")
        if ts_round.hour == 15:
            f_print_success(f"round('H') correct: {ts_round.hour}:{ts_round.minute}")

floor (test_timestamp.py:304)

def test_rounding_methods():
    """Test Timestamp rounding methods"""
    f_print_header("Test: Timestamp Rounding Methods")

    try:
        # Create a Timestamp with all components
        ts = pandasCore.Timestamp(2021, 1, 15, 14, 37, 45, 123456, 789)

        # Floor to hour
        ts_floor = ts.floor("H")
        if ts_floor.hour == 14 and ts_floor.minute == 0 and ts_floor.second == 0:
            f_print_success(f"floor('H') correct: {ts_floor.hour}:{ts_floor.minute}:{ts_floor.second}")
        else:
            f_print_error(f"floor('H') wrong: {ts_floor.hour}:{ts_floor.minute}:{ts_floor.second}")
            return False

        # Ceil to hour
        ts_ceil = ts.ceil("H")
        if ts_ceil.hour == 15 and ts_ceil.minute == 0:
            f_print_success(f"ceil('H') correct: {ts_ceil.hour}:{ts_ceil.minute}:{ts_ceil.second}")

normalize (test_timestamp.py:328)

        # Round to hour (37 minutes rounds down)
        ts_round = ts.round("H")
        if ts_round.hour == 15:
            f_print_success(f"round('H') correct: {ts_round.hour}:{ts_round.minute}")
        else:
            f_print_error(f"round('H') wrong: {ts_round.hour}")
            return False

        # Normalize (floor to day)
        ts_norm = ts.normalize()
        if ts_norm.hour == 0 and ts_norm.minute == 0 and ts_norm.second == 0:
            f_print_success("normalize() correct: midnight")
        else:
            f_print_error(f"normalize() wrong: {ts_norm.hour}:{ts_norm.minute}:{ts_norm.second}")
            return False

        return True

    except Exception as e:
        f_print_error(f"Exception: {e}")

round (test_timestamp.py:320)

        # Ceil to hour
        ts_ceil = ts.ceil("H")
        if ts_ceil.hour == 15 and ts_ceil.minute == 0:
            f_print_success(f"ceil('H') correct: {ts_ceil.hour}:{ts_ceil.minute}:{ts_ceil.second}")
        else:
            f_print_error(f"ceil('H') wrong: {ts_ceil.hour}:{ts_ceil.minute}:{ts_ceil.second}")
            return False

        # Round to hour (37 minutes rounds down)
        ts_round = ts.round("H")
        if ts_round.hour == 15:
            f_print_success(f"round('H') correct: {ts_round.hour}:{ts_round.minute}")
        else:
            f_print_error(f"round('H') wrong: {ts_round.hour}")
            return False

        # Normalize (floor to day)
        ts_norm = ts.normalize()
        if ts_norm.hour == 0 and ts_norm.minute == 0 and ts_norm.second == 0:
            f_print_success("normalize() correct: midnight")

strftime (test_timestamp.py:358)

        # isoformat
        iso_str = ts.isoformat()
        if "2021-01-15" in iso_str and "12:30:45" in iso_str:
            f_print_success(f"isoformat() correct: {iso_str}")
        else:
            f_print_error(f"isoformat() wrong: {iso_str}")
            return False

        # strftime
        str_time = ts.strftime("%Y/%m/%d")
        if str_time == "2021/01/15":
            f_print_success(f"strftime() correct: {str_time}")
        else:
            f_print_error(f"strftime() wrong: {str_time}, expected '2021/01/15'")
            return False

        # isocalendar
        iso_cal = ts.isocalendar()
        if len(iso_cal) == 3:
            f_print_success(f"isocalendar() correct: {iso_cal}")

day_name (test_timestamp.py:382)

        # timestamp (POSIX)
        posix_ts = ts.timestamp()
        if posix_ts > 0:
            f_print_success(f"timestamp() correct: {posix_ts}")
        else:
            f_print_error(f"timestamp() wrong: {posix_ts}")
            return False

        # day_name
        day_name = ts.day_name()
        if day_name == "Friday":
            f_print_success(f"day_name() correct: {day_name}")
        else:
            f_print_error(f"day_name() wrong: {day_name}, expected 'Friday'")
            return False

        # month_name
        month_name = ts.month_name()
        if month_name == "January":
            f_print_success(f"month_name() correct: {month_name}")

isocalendar (test_timestamp.py:366)

        # strftime
        str_time = ts.strftime("%Y/%m/%d")
        if str_time == "2021/01/15":
            f_print_success(f"strftime() correct: {str_time}")
        else:
            f_print_error(f"strftime() wrong: {str_time}, expected '2021/01/15'")
            return False

        # isocalendar
        iso_cal = ts.isocalendar()
        if len(iso_cal) == 3:
            f_print_success(f"isocalendar() correct: {iso_cal}")
        else:
            f_print_error(f"isocalendar() wrong format")
            return False

        # timestamp (POSIX)
        posix_ts = ts.timestamp()
        if posix_ts > 0:
            f_print_success(f"timestamp() correct: {posix_ts}")

isoformat (test_timestamp.py:350)

def test_conversion_methods():
    """Test Timestamp conversion methods"""
    f_print_header("Test: Timestamp Conversion Methods")

    try:
        ts = pandasCore.Timestamp(2021, 1, 15, 12, 30, 45)

        # isoformat
        iso_str = ts.isoformat()
        if "2021-01-15" in iso_str and "12:30:45" in iso_str:
            f_print_success(f"isoformat() correct: {iso_str}")
        else:
            f_print_error(f"isoformat() wrong: {iso_str}")
            return False

        # strftime
        str_time = ts.strftime("%Y/%m/%d")
        if str_time == "2021/01/15":
            f_print_success(f"strftime() correct: {str_time}")

month_name (test_timestamp.py:390)

        # day_name
        day_name = ts.day_name()
        if day_name == "Friday":
            f_print_success(f"day_name() correct: {day_name}")
        else:
            f_print_error(f"day_name() wrong: {day_name}, expected 'Friday'")
            return False

        # month_name
        month_name = ts.month_name()
        if month_name == "January":
            f_print_success(f"month_name() correct: {month_name}")
        else:
            f_print_error(f"month_name() wrong: {month_name}, expected 'January'")
            return False

        return True

    except Exception as e:
        f_print_error(f"Exception: {e}")

timestamp (test_timestamp.py:374)

        # isocalendar
        iso_cal = ts.isocalendar()
        if len(iso_cal) == 3:
            f_print_success(f"isocalendar() correct: {iso_cal}")
        else:
            f_print_error(f"isocalendar() wrong format")
            return False

        # timestamp (POSIX)
        posix_ts = ts.timestamp()
        if posix_ts > 0:
            f_print_success(f"timestamp() correct: {posix_ts}")
        else:
            f_print_error(f"timestamp() wrong: {posix_ts}")
            return False

        # day_name
        day_name = ts.day_name()
        if day_name == "Friday":
            f_print_success(f"day_name() correct: {day_name}")