The pyScss box from The Boy Who Opened Boxes. It is also the grown-up, legal version of The Forbidden Layer: take a tool someone built in another language, open it up, understand exactly how it works, and rebuild it in yours.
Sass was a Ruby tool. I wanted it in Python, so I wrote one, pyScss, which implements about 95% of Sass 3.2. You install it from GitHub with pip install git+https://github.com/Kronuz/pyScss (the last PyPI release, 1.4.0, fails on Python 3.11 and newer, see issue #431) and use it like this:
from scss import CompilerCompiler().compile_string("a { color: red + green; }")Look closely at that input. color: red + green. You are adding two colors. That line is the whole reason this is interesting, and the reason building it was a real compiler problem and not a glorified find-and-replace.
Sass is not a template language. It is a typed language.
Section titled “Sass is not a template language. It is a typed language.”The mistake is to think Sass is CSS with variables pasted in. It is not. Sass is a small, typed expression language that happens to emit CSS. red + green is not string concatenation; it is an operation on two values of type Color, and it produces a third Color. 10px * 2 is arithmetic on a value of type Number that carries a unit. To compile Sass you have to actually evaluate these expressions, which means you need real value types, with real arithmetic, and a real evaluator.
pyScss has exactly that. The value types live in types.py: Number, Color, String, Boolean, List, Map, Null, and a few more, each a subclass of a common Value. Two of them are worth opening up.
Numbers that know their units
Section titled “Numbers that know their units”In Sass, 10px, 2em, and 50% are not strings with a suffix. They are numbers with dimensions, and they obey dimensional analysis. Multiply 10px by a unitless 2 and you get 20px. Divide 10px by 2px and the units cancel to a plain 5. pyScss’s Number implements this literally, in its constructor: it stores units as separate numerator and denominator tuples and cancels the ones that appear on both sides, exactly like reducing a fraction.
# from scss/types.py: a Number carries its units as numer/denom tuplesdef __init__(self, amount, unit=None, unit_numer=(), unit_denom=()): ... # Cancel out any convertable units on the top and bottom numerator_base_units = count_base_units(unit_numer) denominator_base_units = count_base_units(unit_denom) ... self.unit_numer = tuple(unit_numer) self.unit_denom = tuple(unit_denom) self.value = amount * (numer_factor / denom_factor)There is a precision subtlety hiding in there, and it is not mine: Eevee (Lexy Munroe), who rewrote much of pyScss’s type system from 2013 on, added it in 2016. Unit conversions are ratios (96 pixels to an inch, and so on), and doing them in floating point accumulates error. So the amount is stored as a Python Fraction, not a float, to keep conversions exact. The source keeps the honest note that came with it: “this slowed the test suite down by about 10%, ha.” Correctness cost ten percent, and Eevee paid it.
Colors that do math
Section titled “Colors that do math”Color (also in types.py) stores an RGBA tuple and knows how to be built from every form Sass accepts: from_rgb, from_hsl (which leans on Python’s own colorsys), and from_hex. Once a literal like red is a Color, red + green is channel-wise addition on the underlying values. The arithmetic operators on the value types are what make CSS, suddenly, able to compute.
The pipeline: scan, parse, evaluate, flatten
Section titled “The pipeline: scan, parse, evaluate, flatten”Putting it together, compiling a stylesheet runs through a real compiler pipeline.
The grammar for the expression language is a real grammar, written for the yapps2 parser generator in expression.g and compiled to a scanner and parser. The Calculator, whose docstring is simply “Expression evaluator,” walks the resulting AST and evaluates it against a Namespace that holds the variables, mixins, and functions in scope, caching parsed ASTs along the way. Selectors get parsed and the nesting flattened. Out the other end comes plain CSS.
Why there is C in a Python project
Section titled “Why there is C in a Python project”If you look in the repository you will find scanner.c, along with _speedups.c, block_locator.c, and a small hashtable.c. A Sass compiler written in pure Python spends an enormous fraction of its time in the scanner, character by character, and that is exactly the kind of tight loop CPython is slowest at. So the hot path got a hand-written C scanner, with a pure-Python scanner kept as a fallback so the library still installs and runs anywhere, PyPy included.
That instinct is the same one from every other box in this series: when a thing is slow, open it, find the loop that actually costs, and rewrite just that. In DOSBox it was the scaler. Here it was the tokenizer. The shape of the fix never changes.
What it was
Section titled “What it was”pyScss was, for a while, a widely used way to compile Sass without a Ruby dependency in the build, pip install pyScss and go. Implementing 95% of someone else’s language teaches you that language more thoroughly than any amount of using it, because every corner you skipped as a user is a corner you now have to make behave. I came out the other side understanding Sass better than I understood most things I had merely used, which is the whole argument for opening the box instead of admiring it from outside.
I did not get to 95% alone. Eevee (Lexy Munroe) made about five hundred commits to pyScss between 2012 and 2016, and most of the value types, the grammar, the Calculator and the compiler as they stand today are that work; the scanner and the C speedups are the parts that are still mostly mine.
Code references: scss/types.py (Number, Color and the other Sass value types), scss/calculator.py (the expression evaluator), the yapps grammar, and the C scanner. The full source is at github.com/Kronuz/pyScss.