Welcome to clanimtk’s documentation!

Core concepts

clanimtk works with a few, simple core concepts that revolve around certain object types. It is beneficial to keep these in the back of the head when using the toolkit.

  • Frame: A string with fixed linelength. I.e., Either there is only one line in the string, or each newline character is preceeded by the exact same amount of characters.
  • FrameGenerator: A FrameGenerator is any generator that has no sendtype nor returntype, and yields any number of Frame strings that have identical dimensions. That is to say, each Frame yielded by the generator must have the same amount of lines, and same linelength, as all of the others.
  • FrameFunction: Any function that returns a FrameGenerator.
  • AnimationGenerator: A generator that yields an endless amount of Frame strings, but each Frame is terminated by backspace/up character such that printing the Frame results in the cursor ending up at its start position.
  • Animation: Any function that returns an AnimationGenerator.

All of these types, along with some other types used in the package, are type-defined in the :py:module::~clanimtk.types module. Do note that several of the types are simply aliases of each other, or other existing types.

Knowing about these concepts, we can turn to the main functionality of clanimtk, which is provided in the form of two decorators.

  • @animation: Turns a FrameFunction into an Animation.
  • @animate: Given an AnimationGenerator, @animate will print frames to stdout as long as the decorated function is running.

Using clanimtk, the only thing you need to write yourself to create a custom animation is a FrameFunction. Decorating a FrameFunction with the @animation decorator will transform the function into an Animation. Below is a minimal example with the default animation of clanimtk.

from clanimtk import animation

@animation
def hashes():
    return (("#" * i).ljust(4) for i in range(5))

The function returns a generator which yields the strings "    ", "# ", "## ", "### " and "####". Each has one line and is 4 characters wide, so by definition the generator is a FrameGenerator, making the function a FrameFunction. Applying the @animation decorator transforms it into an Animation. The AnimationGenerator it returns can be used with the @animate decorator:

from clanimtk import animate
import time

# note that `hashes` is called to produce an AnimationGenerator
@animate(animation=hashes())
def sleep(duration):
    time.sleep(duration)
    return 42

You can see the not-too-impressive results in the gif below.

An example animation

Creating a multiline animation is similarly simple, you simply create Frame strings that each have the same number of lines.

import time
from clanimtk import animation, animate

# note that there is invisible whitespace to the right
# of some characters. For example, the first line in the
# A actually looks like `_XXX_`, where `_` is a space.
a = """
 XXX
X   X
XXXXX
X   X
X   X""".strip('\n')

b = """
XXXX
X   X
XXXX
X   X
XXXX """.strip('\n')

@animation
def ab():
    return iter([a, b])

# `step` is approx seconds between frames
@animate(animation=ab(), step=.5)
def func():
    time.sleep(10)

This ends up looking like this:

Simple multiline animation

For more examples, have a look at the clanim package!