Skip to content

Usage

The basics

All Dahlia formatting is done through instances of the Dahlia class. Different instances transform1 strings through their convert method—so that each instance can have its own settings.

from dahlia import Dahlia

dahlia = Dahlia()
print(dahlia.convert("&4hello &lthere"))

hello there

See the Syntax section of the Dahlia specification for a list of all Dahlia codes.

The Dahlia class also exposes print and input methods that wrap their built-in counterparts, transforming1 the provided arguments: 

from dahlia import Dahlia

dahlia = Dahlia()
dahlia.print("&e&nunderlined&rn yellow")


underlined yellow
from dahlia import Dahlia

dahlia = Dahlia()
name = dahlia.input("&cWhat is your name? ")
print(f"Oh, hi {name}!")

What is your name? Mark
Oh, hi Mark!

The Dahlia class accepts three optional arguments:

  • the color depth2,
  • the marker, a character that marks the beginning of a Dahlia code,
  • the auto_reset flag, which specifies whether to automatically reset the formatting at the end of a string.

When not specified, Dahlia will try to detect the color depth2 of the current terminal emulator. The detected depth can be accessed through the depth property. If it can't be detected, Dahlia will fall back to Depth.LOW. If colors are disabled (either through NO_COLOR=1 or TERM=dumb), the depth will stay None. You can run the Dahlia package with python -m dahlia to see your current terminal's capabilities.

The default marker is &, and the default value for auto_reset is True. Disabling auto_reset can be useful, for example, when you want to apply the formatting to the user's input: 

from dahlia import Dahlia

dahlia = Dahlia(marker="§", auto_reset=False)
ans = dahlia.input("§9What's §l9+10§rl? ")
if ans == "21":
    dahlia.print("§2Correct!")


What's 9+10? 21
Correct!
from dahlia import Dahlia

Dahlia().print("&ehi", "&othere")
Dahlia(auto_reset=False).print("&ehi", "&othere")

hi there
hi there

Cleaning utilities

Dahlia provides three utility functions:

  • clean for removing Dahlia codes from strings
  • clean_ansi for removing ANSI codes from strings
  • escape for escaping Dahlia codes in strings
from dahlia import Dahlia, clean, clean_ansi, escape

dahlia = Dahlia()
a = "&aa &b&lbunch &c&nof &d&ostyles &e&mhere"
b = dahlia.convert(a)

print(a)
print(clean(a))
print()
print(repr(b))
print(b)
print(clean_ansi(b))
print(escape(a))
print(dahlia.convert(escape(a)))

&aa &b&lbunch &c&nof &d&ostyles &e&mhere
a bunch of styles here

'\x1b[38;2;85;255;85ma \x1b[38;2;85;255;255m\x1b[1mbunch \x1b[38;2;255;85;85m\x1b[4mof \x1b[38;2;255;85;255m\x1b[3mstyles \x1b[38;2;255;255;85m\x1b[9mhere\x1b[0m'
a bunch of styles here
a bunch of styles here
&_aa &_b&_lbunch &_c&_nof &_d&_ostyles &_e&_mhere
&aa &b&lbunch &c&nof &d&ostyles &e&mhere

  1. See "transformation" in the specification's glossary. ↩↩

  2. See "color depth" in the specification's glossary. ↩↩