wrapper_python

Python Wrapper

Python bindings for the Universal Timestamp Library using ctypes FFI.

Installation

1. Install the C library:

   make build_c
   sudo make install_c

2. Install the Python package:

   cd wrappers/python
   pip install .

Requirements

• Python 3.9+
• Universal Timestamp C library (libuniversal_timestamp)

Usage

from universal_timestamp import Timestamp

# Get current time
ts = Timestamp.now()
print(ts)  # 2024-12-14T12:00:00.123456789Z

# Parse a timestamp
ts = Timestamp.parse("2024-12-14T03:13:21Z")
print(ts.nanos)  # Nanoseconds since epoch

# Lenient parsing (missing Z allowed)
ts = Timestamp.parse_lenient("2024-12-14T03:13:21")

# Comparison
if Timestamp.now() > ts:
    print("now is after ts")

API Reference

Timestamp

Method	Description
Timestamp(nanos)	Construct from nanoseconds
Timestamp.now()	Get current UTC time
Timestamp.now_monotonic()	Get monotonic timestamp
Timestamp.parse(s, lenient=False)	Parse ISO-8601 string
Timestamp.parse_strict(s)	Parse ISO-8601 (strict)
Timestamp.parse_lenient(s)	Parse ISO-8601 (lenient)
ts.format(include_nanos=True)	Format to ISO-8601 string
ts.nanos	Get underlying nanoseconds
ts.to_iso_week()	Get (year, week, day) tuple
ts.to_japanese_era()	Get (era, year, name) tuple

Comparison operators: ==, !=, <, <=, >, >=

TimestampError / ParseError

Exception classes thrown on parse/validation errors.

Attribute	Description
code	Error enum value
args[0]	Error message

Calendar Functions

Function	Description
gregorian_to_thai(year)	Convert to Thai year (+543)
thai_to_gregorian(year)	Convert from Thai year
gregorian_to_dangi(year)	Convert to Dangi year (+2333)
dangi_to_gregorian(year)	Convert from Dangi year
gregorian_to_minguo(year)	Convert to Minguo year (-1911)
minguo_to_gregorian(year)	Convert from Minguo year

get_clock_precision()

Returns hardware clock precision level as Precision enum (NANOSECOND, MICROSECOND, MILLISECOND, SECOND).

Enums

• Error — Error codes (OK, INVALID_FORMAT, INVALID_DATE, etc.)
• Precision — Clock precision levels
• Calendar — Calendar types
• JapaneseEra — Japanese era identifiers (REIWA, HEISEI, SHOWA, TAISHO, MEIJI)