descr packageHello and welcome to this tutorial. First let's import the package and create a printer. There is no default printer yet.
The always_setup argument means that the style will be inserted every time
pr() is called. Otherwise, it is only printed when there are changes. Deleting
a cell deletes the style, so if always_setup = False, deleting whichever cell
contains the style will break display in the other cells. It's good to know.
from descr import boxy_notebook, descr, HTMLRuleBuilder as RB
pr = boxy_notebook(always_setup = True)
Let's try and see if it works:
pr("Hello :)")
Most basic datatypes should work, save for those I forgot about.
pr displays nested data structures in boxes. Various types get different colored borders when hovered.
Empty strings and sequences are displayed specially.
pr(("tuple", 1, 987.654, 2+2j, ["list", "hello", [11, 22, 33], "!"], {"key1": "value", "key2": {1: 2, 3: 4}}, {"set", "of", "unordered", "things"}))
pr("", '""', (), [], {}, set())
Tracebacks can be displayed prettily. In Python 3, all you need to do is pr(exception)
to print the exception, its traceback (contained in exception__traceback__), as
well as previous exceptions (exception.__context__ or exception.__cause__). In
Python 2, these fields do not seem to exist, but you can set them yourself:
import traceback, sys
try:
traceback.print_stack("But... I am not a stack!")
except:
etype, evalue, tb = sys.exc_info()
evalue.__traceback__ = tb
pr(evalue)
# The following prints with 3 lines of context, though it may seem a bit arcane:
#pr(evalue, rules = RB().pclasses(".location", "C#3"))
Custom objects must define the __descr__ method (and they must be new style classes).
The method takes one argument, recurse, which is a function to call on any field or children
to obtain their description. In order to facilitate the ordeal, a few pre-implemented classes can be used
as proxies (simply recurse on an object created using these factories).
See the inspect notebook for more information about the format of what __descr__ returns.
from descr.util import Group, Assoc, Object
class MyString(str):
def __descr__(self, recurse):
return ({"@str"}, "(((" + self + ")))")
class Person(object):
def __init__(self, name, age, occupation):
self.name, self.age, self.occupation = name, age, occupation
def __descr__(self, recurse):
return recurse(Object("Person", self.name, age = self.age, occupation = self.occupation))
peter = Person("Peter", 25, "baker")
pr(MyString("bananas"),
peter,
Assoc("key", "value"),
Group([1, 2, 3, 4], classes = {"@list", "sequence"}),
Object("A", "B", a = 1, b = 2, c = 3, field_ordering = ["c", "b", "a"]),
Object("A", None, [1, 2, 3], {'a': 4, 'b': 5}))
Tables can be created via descr.util.Table, which accepts lists of lists
or dictionaries. The borders will be a bit fuzzy if you have lists or
dictionaries inside them, but you can fix that with CSS.
from descr.util import Table, Group
from collections import OrderedDict
t = Table([("Name", "Age", "Occupation"),
("Peter", 25, "baker"),
("Marie-Anne", 27, "nurse"),
("Al", 75, "godfather")],
row_classes = [{"header"}, set()],
column_classes = [{"+name"}, {"+age"}, {"+occupation"}])
pr(t)
# You can also make it pretty (for some definition of pretty)!
t2 = Group([t], classes = {"pretty"})
# The class "pretty" is just to circumscribe the rules so that I can show t and t2 side to side
rules = RB().mclasses(".pretty .table > * > .scalar", {"scalar", "@str"})
rules.css_color(".pretty .header", "#fff")
rules.css_background_color(".pretty .header", "#000")
rules.css_background_color(".pretty .{+age}", "#ccf")
rules.css_background_color(".pretty .header > .{+age}", "#000")
rules.css_background_color(".pretty .{R#odd}", "#eee")
pr(OrderedDict(
[("standard", t),
("pretty", t2)]),
rules = rules)
# You can also make tables from dictionaries
t3 = Table(dict(Canada = ["Toronto", "Montreal"],
USA = ["New York", "Los Angeles"],
France = ["Paris", "Lyon"],
Germany = ["Berlin", "Hamburg"]))
# Rules to fix the borders
rules = RB().css_border(".table > * > .sequence", "0px")
pr(t3, rules = rules)
descr allows highlighting of certain parts, and modification of the descriptions of
objects that are parametrized using CSS selectors.
A selector is written as the CSS spec would indicate, but many class names contain
invalid CSS characters (for instance, strings have the class @str). You can however
enclose the name in {}s and it will be escaped automatically. Depending on the properties
you are adding, some selectors may be refused, because descr does not use a full CSS
implementation on the Python side (for the rest, though, it delegates to the browser).
In order to customize display, you need to create a ruleset using descr::HTMLRuleBuilder.
The builder provides many useful methods to construct rules, and then it can be given
as a keyword argument to pr.
Here is a simple example displaying the various ways to add rules:
from descr import HTMLRuleBuilder as RB, make_joiner
rules = RB()
rules.css_color(".{@str}", "blue")
rules.rule(".{@float}", {"color": "green", "border": "1px solid red"})
rules.join(".{@list}", make_joiner("<span class=bar>|</span>")) \
.css_color(".bar", "#888")
rules.rearrange(".{@tuple}", lambda classes, children: list(reversed(children)))
# Might need to execute twice to get it 100% correct but I am not sure why
pr(["hello!", 10, 9.87, (1, 2, 3)], rules = rules)
Now let's do something more interesting: highlight all error builtins!
There are methods called hl (bold), hl1, hl2, hl3 (colors) and hlE (errors)
that highlight the specified selector. They are actually implemented by giving the
target elements an extra class, which is styled separately.
rules = RB()
rules.hl1(".{@str}", lambda classes, children: children[0].endswith("Error"))
# alternatively:
# rules.pclasses(".{@str}", "hl1", lambda classes, children: children[0].endswith("Error"))
# or:
# rules.rule(".{@str}", {":+classes": lambda classes, children: {"hl1"} if children[0].endswith("Error") else {}})
# Want to hide anything that doesn't match? Add this:
# rules.hide(".{@str}", lambda classes, children: not children[0].endswith("Error"))
pr(dir(__builtins__), rules = rules)
There is a second way to do it, which is to monkey patch the descr method. This is easy
to do because descr takes an additional argument which is the method to call for the children.
For instance, if I want to track some particular object:
alist = ["hello", "world"]
def descr2(obj, recurse = None):
r = descr(obj, descr2)
if obj is alist:
return [{"hl1"}, r]
else:
return r
pr([1, 2, alist, [alist, ["hello", "world"]], [3, 4, 5]], descr = descr2)
You may use whichever method is easier. The former is a bit more composable and configurable thanks to selectors, but it can only access the object's description and not the object itself, unlike the latter. You can also use a combination of both: insert special classes around key elements, and then use selectors to highlight them depending on where they are.