API reference

The stable, backwards-compatible library surface lives in cowser.api (re-exported from cowser). All functions are pure: they perform no I/O, so they are safe to embed in other tools.

Table of Contents

Stable surface

Names exported by cowser.api.__all__:

COWS, Cow, build_speech_bubble, load_cowfile, load_cowfiles, load_packs, pack_dirs, parse_cowfile, register_cow, render, render_cow, render_pair, resolve_cow, search_cows, substitute_eyes, substitute_tongue, wrap_text.

Reference

Stable public API for Cowser.

Library users should import from here (or from cowser directly). The names in __all__ are the supported, backwards-compatible surface: they will not break between minor versions without a deprecation notice.

Cow dataclass

A single piece of animal art.

build_speech_bubble(text, art, think=False)

Wrap text in a speech (or thought) bubble above art.

With think=True the bubble uses a dotted thought-bubble style instead of the usual / ... \ speech bubble.

load_cowfile(path)

Load a single art file as a :class:Cow (None if unreadable).

load_cowfiles(paths)

Load and register every art file under paths.

Only files with a known art suffix (.cow, .txt, .art), and no leading dot, are considered. Duplicate names are skipped. Returns the list of newly registered cows.

load_packs(config=None)

Load all default packs and return how many new cows were added.

pack_dirs(config=None)

Return the list of pack directories to scan.

Combines the COWSER_COWS environment variable and the default ~/.config/neostore/cowser/cows/ directory. config may supply an extra cow_dir key.

parse_cowfile(text, name)

Parse a cowsay-style cowfile (or plain art text) into a :class:Cow.

$the_cow = <<"EOC"; ... EOC blocks are extracted; otherwise the whole text is used as the art. The $eyes placeholder becomes an {eyes} token and $tongue becomes {tongue|}.

register_cow(cow)

Register a custom cow at runtime.

Raises :class:ValueError if a cow with the same name already exists.

Example

register_cow(Cow("my-dragon", " ~\n (o.o)"))

render(text, cow=None, color=None, eyes=None, color_enabled=True, mode=None, tongue=None, think=False, rainbow=False, bold=False, wrap=None, no_wrap=False)

Render text with an animal, returning a ready-to-print string.

cow selects the animal (see :func:resolve_cow). color may be any key of :data:cowser.ansi.COLORS; rainbow and bold are additional styles. mode applies a preset eyes/tongue pair. wrap enables word-wrapping, disabled again by no_wrap. This is a pure function: it performs no I/O, so it is safe to embed in other tools.

Example

render("Hi!", cow="owl", eyes="0.0", color_enabled=False) ' _\n/ Hi! \ \_/\n __\n / 0.0 \n ( V )\n \_____/'

render_cow(art)

Trim trailing whitespace from every line of an art block.

Also drops fully-blank trailing lines so art blocks render cleanly.

render_pair(text, cow1, cow2, color=None, eyes=None, color_enabled=True, mode=None, tongue=None, think=False, rainbow=False, bold=False, wrap=None, no_wrap=False)

Render text with two animals standing side by side.

Accepts the same arguments as :func:render plus cow1/cow2 for the two animals.

resolve_cow(spec=None)

Pick a :class:Cow by object, index, exact name, or unique prefix.

spec may be a :class:Cow instance, an integer index into :data:COWS, an exact name, or a unique name prefix. None picks a random cow. Raises :class:ValueError for unknown or ambiguous specs.

search_cows(query=None, category=None)

Return cows matching a name/category/tag substring, optionally filtered by category.

The query is case-insensitive. category filters to a single category when given. Returns an empty list when nothing matches.

Example

search_cows(query="ocean") [Cow(name='fish', ...)] search_cows(category="mythical") [Cow(name='unicorn', ...), Cow(name='dragon', ...)]

substitute_eyes(art, eyes=None)

Replace the {eyes} token in art with eyes.

Example

substitute_eyes("( {eyes} )", "@.@") '( @.@ )'

substitute_tongue(art, tongue=None)

Replace a {tongue|default} token in art with tongue.

Without tongue the token's built-in default is used, so normal rendering is unaffected. Arts without the token are returned unchanged.

Example

substitute_tongue(" {tongue|}", "U ") ' U '

wrap_text(text, width=40, no_wrap=False)

Word-wrap text to width columns, preserving paragraphs.

Paragraphs (blank-line separated) are wrapped independently. With no_wrap=True the text is returned unchanged.

Example

wrap_text("one two three", width=7) 'one two\nthree'

Usage examples

from cowser import COWS, render, render_pair, register_cow, search_cows, Cow

print(render("Hello from my app", cow="owl", eyes="0.0"))
print(render("moo", cow="pig", mode="dead", think=True))
print(render_pair("best friends", "dog", "cat", rainbow=True))

for cow in search_cows(category="mythical"):
    print(cow.name, cow.tags)

register_cow(Cow("my-dragon", "   ~\n  (o.o)", category="mythical"))

See also: cli.md, configuration.md, architecture.md.

← Back to README