README

pyssed:
=======
A library for generating CSS via pure Python.

Author:
=======
Steve Lacy (github@slacy.com)

Description:
============
This is a simple library for expressing CSS selectors & style rules in
Python, then generating a syntactically correct CSS file as output.

It was written for easy inclusion and use from virtually any web framework:
Pylons, web2py, Django, etc.  It's just a Python library, and not tied to
any framework in particular.

Background & Motivation:
=======================
When doing web development, one must work in several languages and syntaxes
concurently.  Typically, you will have 4 or more languages to work with:

- Python (or whatever language you're using for your backend)
- HTML
- CSS
- JavaScript

Context switching between languages can lead to editing mistakes, like
missing (or adding) semicolons at the end of lines, etc.

In addition, CSS2 has a very lightweight syntax, missing many key features.
Because of this, several CSS helper libraries and alternate syntaxes have
arisen.  For example:

Less CSS: "Leaner CSS"
http://lesscss.org/

Sass: "Style with attitude"
http://sass-lang.com/

Clever CSS: "the pythonic way of webdesign"
http://sandbox.pocoo.org/clevercss/

But, none of these helper libraries actually use native Python for
generating the CSS itself, and all of them are "just another language" with
some CSS-isms and a few extensions to make the developer's life a bit
easier.  But, this just compounds the multi-language problem even more.

I want to write my stylesheets in Python.  I have a web framework that can
take Python and generate HTML, so why not have it generate syntactically
correct CSS as well?

That's exactly what pyssed is for.

What it does is best expressed in some examples.  Please browse the examples
directory for some more fun stuff.

Examples:
=========

# A trivial example of pyssed
# See actual source in pyssed/examples/simple.py

import pyssed

css = {
    'a:hover': {
        'font-weight': 'bold',
    }
}

print '\n'.join(pyssed.generate(css))

will generate the CSS:

"""
a:hover {
  font-weight: bold;
}
"""

In addition, because it's pure Python, pyssed's syntax is as flexible as the
language itself, and automatically supports all of the features of the
previously mentioned CSS helpers. Here's an example showing off lots of
pyssed's features, include variables, arithmetic, mixins, nested styles, and
style reuse.

# See source in pyssed/examples/everything.py
import pyssed

site_background = "#123450"
red = pyssed.style('color: red;')
blue = pyssed.style(color='blue')
green = {'color': 'green'}
bold = pyssed.style('font-weight: bold;')
red_bold = red + bold


def rounded(radius):
    return pyssed.style({
        'border-radius': radius,
        '-moz-border-radius': int(round(radius * 1.5)),
        '-webkit-border-radius': int(round(radius * 2.0)),
        })

css = {
    '.blue': blue,
    '.green': green,
    'ul li': rounded(3) + blue + {
        'font-style': 'italic',
        'background': site_background,
    },
    'div.ground': rounded(7) + red_bold + {
        'p': {
            'text-align': 'left',
            'em': {
                'font-size': '14pt',
                'background': site_background,
            }
        },
    }
}

print '\n'.join(pyssed.generate(css))

Which will generate the following CSS (item ordering may vary):

"""
.green {
    color: green;
}

div.ground {
    border-radius: 7px;
    color: red;
    font-weight: bold;
    -webkit-border-radius: 14px;
    -moz-border-radius: 11px;
}

div.ground p {
    text-align: left;
}

div.ground p em {
    font-size: 14pt;
    background: #123450;
}

.blue {
    color: blue;
}

ul li {
    border-radius: 3px;
    background: #123450;
    color: blue;
    -webkit-border-radius: 6px;
    -moz-border-radius: 5px;
    font-style: italic;
}
"""