apache_beam.utils.timestamp module

Timestamp utilities.

For internal use only; no backwards-compatibility guarantees.

class apache_beam.utils.timestamp.Timestamp(seconds: Union[int, float] = 0, micros: Union[int, float] = 0)

Bases: object

Represents a Unix second timestamp with microsecond granularity.

Can be treated in common timestamp arithmetic operations as a numeric type.

Internally stores a time interval as an int of microseconds. This strategy is necessary since floating point values lose precision when storing values, especially after arithmetic operations (for example, 10000000 % 0.1 evaluates to 0.0999999994448885).

static of(seconds: Union[int, float, Timestamp]) → apache_beam.utils.timestamp.Timestamp

Return the Timestamp for the given number of seconds.

If the input is already a Timestamp, the input itself will be returned.

Parameters:seconds – Number of seconds as int, float, long, or Timestamp. Returns:Corresponding Timestamp object.

static now() → apache_beam.utils.timestamp.Timestamp

classmethod from_utc_datetime(dt: datetime.datetime) → apache_beam.utils.timestamp.Timestamp

Create a Timestamp instance from a datetime.datetime object.

Parameters:dt – A datetime.datetime object in UTC (offset-aware).

classmethod from_rfc3339(rfc3339: str) → apache_beam.utils.timestamp.Timestamp

Create a Timestamp instance from an RFC 3339 compliant string.

Note

All timezones are implicitly converted to UTC.

Parameters:rfc3339 – String in RFC 3339 form.

seconds() → int

Returns the timestamp in seconds.

predecessor() → apache_beam.utils.timestamp.Timestamp

Returns the largest timestamp smaller than self.

successor() → apache_beam.utils.timestamp.Timestamp

Returns the smallest timestamp larger than self.

to_utc_datetime(has_tz: bool = False) → datetime.datetime

Returns a datetime.datetime object of UTC for this Timestamp.

Note that this method returns a datetime.datetime object without a timezone info by default, as builtin datetime.datetime.utcnow method. If this is used as part of the processed data, one should set has_tz=True to avoid offset due to default timezone mismatch.

Parameters:has_tz – whether the timezone info is attached, default to False. Returns:a datetime.datetime object of UTC for this Timestamp.

to_rfc3339() → str

to_proto() → google.protobuf.timestamp_pb2.Timestamp

Returns the google.protobuf.timestamp_pb2 representation.

static from_proto(timestamp_proto: google.protobuf.timestamp_pb2.Timestamp) → apache_beam.utils.timestamp.Timestamp

Creates a Timestamp from a google.protobuf.timestamp_pb2.

Note that the google has a sub-second resolution of nanoseconds whereas this class has a resolution of microsends. This class will truncate the nanosecond resolution down to the microsecond.

class apache_beam.utils.timestamp.Duration(seconds: Union[int, float] = 0, micros: Union[int, float] = 0)

Bases: object

Represents a second duration with microsecond granularity.

Can be treated in common arithmetic operations as a numeric type.

Internally stores a time interval as an int of microseconds. This strategy is necessary since floating point values lose precision when storing values, especially after arithmetic operations (for example, 10000000 % 0.1 evaluates to 0.0999999994448885).

static of(seconds: Union[int, float, Duration]) → apache_beam.utils.timestamp.Duration

Return the Duration for the given number of seconds since Unix epoch.

If the input is already a Duration, the input itself will be returned.

Parameters:seconds – Number of seconds as int, float or Duration. Returns:Corresponding Duration object.

to_proto() → google.protobuf.duration_pb2.Duration

Returns the google.protobuf.duration_pb2 representation.

static from_proto(duration_proto: google.protobuf.duration_pb2.Duration) → apache_beam.utils.timestamp.Duration

Creates a Duration from a google.protobuf.duration_pb2.

Note that the google has a sub-second resolution of nanoseconds whereas this class has a resolution of microsends. This class will truncate the nanosecond resolution down to the microsecond.