# The duration module

Functions to deal with LilyPond’s musical durations.

A duration is a `Fraction` or an integer, where a whole note is 1. A duration can be split in two values, log and dot-count, where the log value is 0 for a whole note, 1 for a half note, 2 for a crotchet, -1 for a `\breve`, etc. This is the same way LilyPond handles durations.

Durations can be scaled using multiplying, e.g. with a Fraction.

class Transform(log=0, dotcount=0, scale=1)[source]

Bases: `object`

Combine modifications of a duration (shift and/or scale).

Use it to calculate the real length of musical items. Transforms can be added. A Transform that doesn’t modify anything evaluates to False.

log

the log to shift

dotcount

the dots to shift

scale

the scaling

length(duration, scaling=1)[source]

Return the actual musical length of the duration and scaling values.

transform(duration, scaling=1)[source]

Return a transformed two-tuple (duration, scaling).

log_dotcount(value)[source]

Return the integer two-tuple (log, dotcount) for the duration value.

The `value` may be a Fraction, integer or floating point value.

The returned log is 0 for a whole note, 1 for a half note, 2 for a crotchet, -1 for a `\\breve`, etc. This is the same way LilyPond handles durations. For example:

```>>> from quickly.duration import log_dotcount
>>> log_dotcount(1)
(0, 0)
>>> log_dotcount(1/2)
(1, 0)
>>> log_dotcount(4)
(-2, 0)
>>> log_dotcount(1/4)
(2, 0)
>>> log_dotcount(3/4)
(1, 1)
>>> log_dotcount(7/16)
(2, 2)
>>> to_string(duration(*log_dotcount(Fraction(3, 4))))
'2.'
```

The value is truncated to a duration that can be expressed by a note length and a number of dots. For example:

```>>> to_string(duration(*log_dotcount(1)))
'1'
>>> to_string(duration(*log_dotcount(1.4)))
'1'
>>> to_string(duration(*log_dotcount(1.5)))
'1.'
>>> to_string(duration(*log_dotcount(0.9999)))
'2............'
```
duration(log, dotcount=0)[source]

Return the duration as a Fraction.

See for an explanation of the `log` and `dotcount` values `log_dotcount()`.

shift_duration(value, log, dotcount=0)[source]

Shift the duration.

This function is analogous to LilyPond’s `\shiftDurations` command. It modifies a duration by shifting the log and the number of dots. Adding 1 to the log halves the note length, and adding a dot mutiplies the note length with `(1 + 1/2**<dots>)`. Subtracting 1 from the log doubles the note length.

The `value` should be a duration that is expressable by a note length and a number of dots. A Fraction is returned. `log` is the scaling as a power of 2; and `dotcount` the number of dots to be added (or removed, by specifying a negative value).

For example:

```>>> shift_duration(Fraction(1, 8), -1)
Fraction(1, 4)
>>> shift_duration(Fraction(1, 8), -2)
Fraction(1, 2)
>>> shift_duration(Fraction(1, 4), 1, 1)
Fraction(3, 16)
>>> to_string(shift_duration(Fraction(1,4), 1, 1))
'8.'
>>> to_string(shift_duration(from_string('2'), 1, 1))
'4.'
>>> shift_duration(Fraction(7, 8), 0, -2)
Fraction(1, 2)
>>> shift_duration(Fraction(7, 8), 0, -1)
Fraction(3, 4)
```

The number of dots in a duration will never drop below zero:

```>>> shift_duration(1/4, 0, -1)
Fraction(1, 4)
```
to_string(value)[source]

Convert the value (most times a Fraction) to a LilyPond string notation.

The value is truncated to a duration that can be expressed by a note length and a number of dots. For example:

```>>> from fractions import Fraction
>>> from quickly.duration import to_string
>>> to_string(Fraction(3, 2))
'1.'
>>> to_string(4)
'\\longa'
>>> to_string(7.75)
'\\longa....'
```

Raises an IndexError if the base duration is too long (longer than `\maxima`).

from_string(text, dotcount=None)[source]

Convert a LilyPond duration string (e.g. `'4.'`) to a Fraction.

The durations `\breve`, `\longa` and `\maxima` may be used with or without backslash. If `dotcount` is None, the dots are expected to be in the `text`.

For example:

```>>> from quickly.duration import from_string
>>> from_string('8')
Fraction(1, 8)
>>> from_string('8..')
Fraction(7, 32)
>>> from_string('8', dotcount=2)
Fraction(7, 32)
```

Raises a ValueError if an invalid duration is specified.

is_writable(value)[source]

Return True if the value can be exactly expressed in a log and dotcount value, without loss.

The value should be >= 1/1024 and < 16, because LilyPond can’t display more than 8 flags and `\maxima` is the longest available duration name.