render Module

Classes

RenderIterator

An iterator for efficient iteration over rendered frames of an animated renderable.

class term_image.render.RenderIterator(renderable, render_args=None, padding=ExactPadding(left=0, top=0, right=0, bottom=0, fill=' '), loops=1, cache=100)

Bases: object

An iterator for efficient iteration over rendered frames of an animated renderable.

Parameters:

• renderable (Renderable) – An animated renderable.

• render_args (RenderArgs | None) – Render arguments.

• padding (Padding) – Render output padding.

• loops (int) –

  The number of times to go over all frames.

  • < 0 -> loop infinitely.

  • 0 -> invalid.

  • > 0 -> loop the given number of times.

  Note

  The value is ignored and taken to be 1 (one), if renderable has INDEFINITE frame count.

• cache (bool | int) –

  Determines if rendered frames are cached.

  If the value is True or a positive integer greater than or equal to the frame count of renderable, caching is enabled. Otherwise i.e False or a positive integer less than the frame count, caching is disabled.

  Note

  The value is ignored and taken to be False, if renderable has INDEFINITE frame count.

Raises:

• ValueError – An argument has an invalid value.

• IncompatibleRenderArgsError – Incompatible render arguments.

The iterator yields a Frame instance on every iteration.

Note

• Seeking the underlying renderable (via Renderable.seek()) does not affect an iterator, use RenderIterator.seek() instead. Likewise, the iterator does not modify the underlying renderable’s current frame number.

• Changes to the underlying renderable’s render size does not affect an iterator’s render outputs, use set_render_size() instead.

• Changes to the underlying renderable’s frame_duration does not affect the value yiedled by an iterator, the value when initializing the iterator is what it will use.

See also

Renderable.__iter__()

Renderables are iterable

RenderIterator

RenderIterator‘s Extension API

Attributes:

loop	Iteration loop countdown

Instance Methods:

close	Finalizes the iterator and releases resources used.
seek	Sets the frame to be rendered on the next iteration, without affecting the loop count.
set_frame_duration	Sets the frame duration.
set_padding	Sets the render output padding.
set_render_args	Sets the render arguments.
set_render_size	Sets the render size.

loop: int

Iteration loop countdown

• A negative integer, if iteration is infinite.

• Otherwise, the current iteration loop countdown value.

  • Starts from the value of the loops constructor argument,

  • decreases by one upon rendering the first frame of every loop after the first,

  • and ends at zero after the iterator is exhausted.

Note

Modifying this doesn’t affect the iterator.

close()

Finalizes the iterator and releases resources used.

Note

This method is automatically called when the iterator is exhausted or garbage-collected but it’s recommended to call it manually if iteration is ended prematurely (i.e before the iterator itself is exhausted), especially if frames are cached.

This method is safe for multiple invocations.

seek(offset, whence=Seek.START)

Sets the frame to be rendered on the next iteration, without affecting the loop count.

Parameters:

• offset (int) – Frame offset (relative to whence).

• whence (Seek) – Reference position for offset.

Raises:

• FinalizedIteratorError – The iterator has been finalized.

• ValueError – offset is out of range.

The value range for offset depends on the frame_count of the underlying renderable and whence:

definite frame count

whence	Valid value range for offset
START	0 <= offset < frame_count
CURRENT	-next_frame_number [1] <= offset < frame_count - next_frame_number
END	-frame_count < offset <= 0

INDEFINITE frame count

whence	Valid value range for offset
START	0 <= offset
CURRENT	any value
END	offset <= 0

Note

If the underlying renderable has definite frame count, seek operations have immeditate effect. Hence, multiple consecutive seek operations, starting with any kind and followed by one or more with whence = CURRENT, between any two consecutive renders have a cumulative effect. In particular, any seek operation with whence = CURRENT is relative to the frame to be rendered next [1].

Example

>>> animated_renderable.frame_count
10
>>> render_iter = RenderIterator(animated_renderable)  # next = 0
>>> render_iter.seek(5)  # next = 5
>>> next(render_iter).number  # next = 5 + 1 = 6
5
>>> # cumulative
>>> render_iter.seek(2, Seek.CURRENT)  # next = 6 + 2 = 8
>>> render_iter.seek(-4, Seek.CURRENT)  # next = 8 - 4 = 4
>>> next(render_iter).number  # next = 4 + 1 = 5
4
>>> # cumulative
>>> render_iter.seek(7)  # next = 7
>>> render_iter.seek(1, Seek.CURRENT)  # next = 7 + 1 = 8
>>> render_iter.seek(-5, Seek.CURRENT)  # next = 8 - 5 = 3
>>> next(render_iter).number  # next = 3 + 1 = 4
3
>>> # NOT cumulative
>>> render_iter.seek(3, Seek.CURRENT)  # next = 4 + 3 = 7
>>> render_iter.seek(2)  # next = 2
>>> next(render_iter).number  # next = 2 + 1 = 3
2

On the other hand, if the underlying renderable has INDEFINITE frame count, seek operations don’t take effect until the next render. Hence, multiple consecutive seek operations between any two consecutive renders do not have a cumulative effect; rather, only the last one takes effect. In particular, any seek operation with whence = CURRENT is relative to the frame after that which was rendered last.

Example

>>> animated_renderable.frame_count is FrameCount.INDEFINITE
True
>>> # iterating normally without seeking
>>> [frame.render_output for frame in animated_renderable]
['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', ...]
>>>
>>> # Assuming the renderable implements all kinds of seek operations
>>> render_iter = RenderIterator(animated_renderable)  # next = 0
>>> render_iter.seek(5)  # next = 5
>>> next(render_iter).render_output  # next = 5 + 1 = 6
'5'
>>> render_iter.seek(2, Seek.CURRENT)  # next = 6 + 2 = 8
>>> render_iter.seek(-4, Seek.CURRENT)  # next = 6 - 4 = 2
>>> next(render_iter).render_output  # next = 2 + 1 = 3
'2'
>>> render_iter.seek(7)  # next = 7
>>> render_iter.seek(3, Seek.CURRENT)  # next = 3 + 3 = 6
>>> next(render_iter).render_output  # next = 6 + 1 = 7
'6'

A renderable with INDEFINITE frame count may not support/implement all kinds of seek operations or any at all. If the underlying renderable doesn’t support/implement a given seek operation, the seek operation should simply have no effect on iteration i.e the next frame should be the one after that which was rendered last. See each render class that implements INDEFINITE frame count for the seek operations it supports and any other specific related details.

set_frame_duration(duration)

Sets the frame duration.

Parameters:

duration (int | FrameDuration) – Frame duration (see frame_duration).

Raises:

• FinalizedIteratorError – The iterator has been finalized.

• ValueError – duration is out of range.

Note

Takes effect from the next [1] rendered frame.

set_padding(padding)

Sets the render output padding.

Parameters:

padding (Padding) – Render output padding.

Raises:

FinalizedIteratorError – The iterator has been finalized.

Note

Takes effect from the next [1] rendered frame.

set_render_args(render_args)

Sets the render arguments.

Parameters:

render_args (RenderArgs) – Render arguments.

Raises:

• FinalizedIteratorError – The iterator has been finalized.

• IncompatibleRenderArgsError – Incompatible render arguments.

Note

Takes effect from the next [1] rendered frame.

set_render_size(render_size)

Sets the render size.

Parameters:

render_size (Size) – Render size.

Raises:

FinalizedIteratorError – The iterator has been finalized.

Note

Takes effect from the next [1] rendered frame.

Exceptions

RenderIteratorError	Base exception class for errors specific to RenderIterator.
FinalizedIteratorError	Raised if certain operations are attempted on a finalized iterator.

exception term_image.render.RenderIteratorError

Bases: TermImageError

Base exception class for errors specific to RenderIterator.

exception term_image.render.FinalizedIteratorError

Bases: RenderIteratorError

Raised if certain operations are attempted on a finalized iterator.

Extension API

Note

The following definitions are provided and required only for extended use of the interfaces defined above.

Everything required for normal usage should typically be exposed in the public API.

RenderIterator

class term_image.render.RenderIterator

See RenderIterator for the public API.

Class Methods:

_from_render_data_

Constructs an iterator with pre-generated render data.

classmethod _from_render_data_(renderable, render_data, render_args=None, padding=ExactPadding(left=0, top=0, right=0, bottom=0, fill=' '), *args, finalize=True, **kwargs)

Constructs an iterator with pre-generated render data.

Parameters:

• renderable (Renderable) – An animated renderable.

• render_data (RenderData) – Render data.

• render_args (RenderArgs | None) – Render arguments.

• args (Any) – Other positional arguments accepted by the class constructor.

• finalize (bool) – Whether render_data is finalized along with the iterator.

• kwargs (Any) – Other keyword arguments accepted by the class constructor.

Returns:

A new iterator instance.

Return type:

Self

Raises the same exceptions as the class constructor.

Note

render_data may be modified by the iterator or the underlying renderable.

Footnotes

[1] (1,2,3,4,5,6)

The frame to be rendered next is:

• the first frame, if no seek operation or render has occurred;

• otherwise, the frame after that which was rendered last, if no seek operation has occurred since the last render;

• otherwise, the frame set by the latest seek operation since the last render.