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 ofFrame
strings that have identical dimensions. That is to say, eachFrame
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 eachFrame
is terminated by backspace/up character such that printing theFrame
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 anAnimation
. - @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.
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:
For more examples, have a look at the clanim package!