ClockDuration

ClockDuration(microseconds: int | Fraction)

A duration measured in microseconds of real time.

The stored value may be a Fraction so that conversions from metrical time (e.g. a triplet eighth at quarter = 100) stay exact; the accessors (whole_microseconds, seconds, str()) present ordinary numbers.

>>> ClockDuration.from_seconds(90)
ClockDuration(microseconds=90000000)
>>> str(ClockDuration.from_seconds(90))
'00:01:30.000000'
>>> ClockDuration.from_seconds(1) + ClockDuration.from_milliseconds(500) == ClockDuration(1_500_000)
True

A float is refused, since it cannot hold most lengths exactly; a fractional length is a Fraction:

>>> ClockDuration.from_seconds(Fraction(3, 2))
ClockDuration(microseconds=Fraction(1500000, 1))

Raises

Name	Type	Description
	TypeError	if `microseconds` is a float, however the duration is built (`from_seconds(1.5)`, `ClockDuration(5) * 1.5`).
	>>> ClockDuration.from_seconds(1.5)
	Traceback (most recent call last):
	…
	TypeError: A ClockDuration cannot hold a float (1500000.0); use an int or a Fraction.

Attributes

Name	Description
`__slots__`
microseconds
rational_length	The microseconds, as a Fraction.
temporal_system
hours	>>> ClockDuration.from_minutes(90).hours
minutes	>>> ClockDuration.from_seconds(90).minutes
seconds	>>> ClockDuration.from_milliseconds(1500).seconds
milliseconds	>>> ClockDuration(1500).milliseconds
whole_microseconds	The microseconds rounded to an int, for a Fraction-valued duration.
timedelta	The same length as a standard-library `timedelta`, to whole microseconds.

Methods

Name	Description
`__eq__`
`__lt__`	Shorter than `other`, by rational length, within compatible systems.
`__hash__`
scale	The same operation as `*`; exact for a Fraction scalar.
`__add__`	Clock time adds only to clock time.
`__radd__`	Lets `sum(clock_durations)` work from its default start value of 0.
`__sub__`	The signed difference of two clock durations.
`__neg__`	The same length backwards.
`__mul__`	>>> ClockDuration(5) * 3
`__truediv__`	Exact for any rational divisor: the result is a Fraction, never a float.
`__str__`
from_minutes	>>> ClockDuration.from_minutes(2).seconds
from_seconds	>>> ClockDuration.from_seconds(2).whole_microseconds
from_milliseconds	>>> ClockDuration.from_milliseconds(2).whole_microseconds
from_timedelta	>>> ClockDuration.from_timedelta(timedelta(minutes=1)) == ONE_MINUTE
from_duration	Convert any Measurable (a note value, a TemporalUnit,

`eq`

__eq__(other)

`lt`

__lt__(other)

Shorter than other, by rational length, within compatible systems.

>>> from openmusickit.systems.wsmn.temporal.symbols import quarter, dotted_quarter
>>> quarter < dotted_quarter, dotted_quarter < quarter
(True, False)

`hash`

__hash__()

scale

scale(scalar: int | Fraction)

The same operation as *; exact for a Fraction scalar.

>>> ClockDuration.from_seconds(1).scale(Fraction(1, 4)).milliseconds
Fraction(250, 1)

Raises

Name	Type	Description
	ScalingError	if `scalar` is not a positive rational.
	>>> ClockDuration(7).scale(0)
	Traceback (most recent call last):
	…
	openmusickit.errors.ScalingError: A ClockDuration can only be scaled by a positive scalar.

`add`

__add__(other)

Clock time adds only to clock time.

>>> ClockDuration(1) + ClockDuration(2)
ClockDuration(microseconds=3)

`radd`

__radd__(other)

Lets sum(clock_durations) work from its default start value of 0.

>>> sum([ClockDuration(1), ClockDuration(2)])
ClockDuration(microseconds=3)

`sub`

__sub__(other)

The signed difference of two clock durations.

>>> ClockDuration(5) - ClockDuration(7)
ClockDuration(microseconds=-2)

`neg`

__neg__()

The same length backwards.

>>> -ClockDuration(5)
ClockDuration(microseconds=-5)

`mul`

__mul__(scalar)

>>> ClockDuration(5) * 3
ClockDuration(microseconds=15)

`truediv`

__truediv__(scalar)

Exact for any rational divisor: the result is a Fraction, never a float.

>>> ClockDuration(6) / Fraction(3)
ClockDuration(microseconds=Fraction(2, 1))
>>> ClockDuration(7) / 3
ClockDuration(microseconds=Fraction(7, 3))

`str`

__str__()

from_minutes

from_minutes(n: int | Fraction)

>>> ClockDuration.from_minutes(2).seconds
120.0

from_seconds

from_seconds(n: int | Fraction)

>>> ClockDuration.from_seconds(2).whole_microseconds
2000000

from_milliseconds

from_milliseconds(n: int | Fraction)

>>> ClockDuration.from_milliseconds(2).whole_microseconds
2000

from_timedelta

from_timedelta(td: timedelta)

>>> ClockDuration.from_timedelta(timedelta(minutes=1)) == ONE_MINUTE
True

from_duration

from_duration(duration: Measurable, ratio: TemporalRatio)

Convert any Measurable (a note value, a TemporalUnit, a time signature, a tied duration…) into clock time.

ratio relates metrical time to clock time; it is usually built with Tempo:

>>> from openmusickit.systems.wsmn.temporal.symbols import quarter, dotted_half
>>> ClockDuration.from_duration(dotted_half, Tempo(120, quarter)).seconds
Fraction(3, 2)

Raises

Name	Type	Description
	TemporalCompatibilityError	if the contextual side of `ratio` is not clock time.