sass — Binding of libsass

This simple C extension module provides a very simple binding of libsass, which is written in C/C++. It contains only one function and one exception type.

>>> import sass
>>> sass.compile(string='a { b { color: blue; } }')
'a b {
  color: blue; }
'
sass.MODES = {'filename', 'string', 'dirname'}

(collections.Set) The set of keywords compile() can take.

sass.OUTPUT_STYLES = {'nested': 0, 'expanded': 1, 'compact': 2, 'compressed': 3}

(collections.Mapping) The dictionary of output styles. Keys are output name strings, and values are flag integers.

sass.SOURCE_COMMENTS = {'none': 0, 'line_numbers': 1, 'default': 1, 'map': 2}

(collections.Mapping) The dictionary of source comments styles. Keys are mode names, and values are corresponding flag integers.

New in version 0.4.0.

Deprecated since version 0.6.0.

exception sass.CompileError(msg)

The exception type that is raised by compile(). It is a subtype of exceptions.ValueError.

class sass.SassFunction(name, arguments, callable_)

Custom function for Sass. It can be instantiated using from_lambda() and from_named_function() as well.

Parameters:

New in version 0.7.0.

classmethod from_lambda(name, lambda_)

Make a SassFunction object from the given lambda_ function. Since lambda functions don’t have their name, it need its name as well. Arguments are automatically inspected.

Parameters:
  • name (str) – the function name
  • lambda (types.LambdaType) – the actual lambda function to be called
Returns:

a custom function wrapper of the lambda_ function

Return type:

SassFunction

classmethod from_named_function(function)

Make a SassFunction object from the named function. Function name and arguments are automatically inspected.

Parameters:function (types.FunctionType) – the named function to be called
Returns:a custom function wrapper of the function
Return type:SassFunction
signature

Signature string of the function.

class sass.SassMap(*args, **kwargs)

Because sass maps can have mapping types as keys, we need an immutable hashable mapping type.

New in version 0.7.0.

sass.and_join(strings)

Join the given strings by commas with last ‘ and ‘ conjuction.

>>> and_join(['Korea', 'Japan', 'China', 'Taiwan'])
'Korea, Japan, China, and Taiwan'
Parameters:strings – a list of words to join
Returns:a joined string
Return type:str, basestring
sass.compile(**kwargs)

There are three modes of parameters compile() can take: string, filename, and dirname.

The string parameter is the most basic way to compile SASS. It simply takes a string of SASS code, and then returns a compiled CSS string.

Parameters:
  • string (str) – SASS source code to compile. it’s exclusive to filename and dirname parameters
  • output_style (str) – an optional coding style of the compiled result. choose one of: 'nested' (default), 'expanded', 'compact', 'compressed'
  • source_comments (bool) – whether to add comments about source lines. False by default
  • include_paths (collections.Sequence) – an optional list of paths to find @imported SASS/CSS source files
  • precision (int) – optional precision for numbers. 5 by default.
  • custom_functions (collections.Set, collections.Sequence, collections.Mapping) – optional mapping of custom functions. see also below custom functions description
  • indented (bool) – optional declaration that the string is SASS, not SCSS formatted. False by default
  • importers (collections.Callable) – optional callback functions. see also below importer callbacks description
Returns:

the compiled CSS string

Return type:

str

Raises:

sass.CompileError – when it fails for any reason (for example the given SASS has broken syntax)

The filename is the most commonly used way. It takes a string of SASS filename, and then returns a compiled CSS string.

Parameters:
  • filename (str) – the filename of SASS source code to compile. it’s exclusive to string and dirname parameters
  • output_style (str) – an optional coding style of the compiled result. choose one of: 'nested' (default), 'expanded', 'compact', 'compressed'
  • source_comments (bool) – whether to add comments about source lines. False by default
  • source_map_filename (str) – use source maps and indicate the source map output filename. None means not using source maps. None by default.
  • include_paths (collections.Sequence) – an optional list of paths to find @imported SASS/CSS source files
  • precision (int) – optional precision for numbers. 5 by default.
  • custom_functions (collections.Set, collections.Sequence, collections.Mapping) –

    optional mapping of custom functions. see also below custom functions description

  • importers (collections.Callable) –

    optional callback functions. see also below importer callbacks description

Returns:

the compiled CSS string, or a pair of the compiled CSS string and the source map string if source_map_filename is set

Return type:

str, tuple

Raises:

The dirname is useful for automation. It takes a pair of paths. The first of the dirname pair refers the source directory, contains several SASS source files to compiled. SASS source files can be nested in directories. The second of the pair refers the output directory that compiled CSS files would be saved. Directory tree structure of the source directory will be maintained in the output directory as well. If dirname parameter is used the function returns None.

Parameters:
  • dirname (tuple) – a pair of (source_dir, output_dir). it’s exclusive to string and filename parameters
  • output_style (str) – an optional coding style of the compiled result. choose one of: 'nested' (default), 'expanded', 'compact', 'compressed'
  • source_comments (bool) – whether to add comments about source lines. False by default
  • include_paths (collections.Sequence) – an optional list of paths to find @imported SASS/CSS source files
  • precision (int) – optional precision for numbers. 5 by default.
  • custom_functions (collections.Set, collections.Sequence, collections.Mapping) –

    optional mapping of custom functions. see also below custom functions description

Raises:

sass.CompileError – when it fails for any reason (for example the given SASS has broken syntax)

The custom_functions parameter can take three types of forms:

Set/Sequence of SassFunctions

It is the most general form. Although pretty verbose, it can take any kind of callables like type objects, unnamed functions, and user-defined callables.

sass.compile(
    ...,
    custom_functions={
        sass.SassFunction('func-name', ('$a', '$b'), some_callable),
        ...
    }
)
Mapping of names to functions

Less general, but easier-to-use form. Although it’s not it can take any kind of callables, it can take any kind of functions defined using def/lambda syntax. It cannot take callables other than them since inspecting arguments is not always available for every kind of callables.

sass.compile(
    ...,
    custom_functions={
        'func-name': lambda a, b: ...,
        ...
    }
)
Set/Sequence of named functions

Not general, but the easiest-to-use form for named functions. It can take only named functions, defined using def. It cannot take lambdas sinc names are unavailable for them.

def func_name(a, b):
    return ...

sass.compile(
    ...,
    custom_functions={func_name}
)

Newer versions of libsass allow developers to define callbacks to be called and given a chance to process @import directives. You can define yours by passing in a list of callables via the importers parameter. The callables must be passed as 2-tuples in the form:

(priority_int, callback_fn)

A priority of zero is acceptable; priority determines the order callbacks are attempted.

These callbacks must accept a single string argument representing the path passed to the @import directive, and either return None to indicate the path wasn’t handled by that callback (to continue with others or fall back on internal libsass filesystem behaviour) or a list of one or more tuples, each in one of three forms:

  • A 1-tuple representing an alternate path to handle internally; or,
  • A 2-tuple representing an alternate path and the content that path represents; or,
  • A 3-tuple representing the same as the 2-tuple with the addition of a “sourcemap”.

All tuple return values must be strings. As a not overly realistic example:

def my_importer(path):
    return [(path, '#' + path + ' { color: red; }')]

sass.compile(
        ...,
        importers=[(0, my_importer)]
    )

Now, within the style source, attempting to @import 'button'; will instead attach color: red as a property of an element with the imported name.

New in version 0.4.0: Added source_comments and source_map_filename parameters.

Changed in version 0.6.0: The source_comments parameter becomes to take only bool instead of str.

Deprecated since version 0.6.0: Values like 'none', 'line_numbers', and 'map' for the source_comments parameter are deprecated.

New in version 0.7.0: Added precision parameter.

New in version 0.7.0: Added custom_functions parameter.

New in version 0.11.0: source_map_filename no longer implies source_comments.