`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; }
'

exception sass.CompileError(msg)¶: The exception type that is raised by compile(). It is a subtype of exceptions.ValueError.

sass.MODES = frozenset({'dirname', 'filename', 'string'})¶: (frozenset) The set of keywords compile() can take.

sass.OUTPUT_STYLES = {'compact': 2, 'compressed': 3, 'expanded': 1, 'nested': 0}¶: (collections.abc.Mapping) The dictionary of output styles. Keys are output name strings, and values are flag integers.

sass.SOURCE_COMMENTS = {'default': 1, 'line_numbers': 1, 'map': 2, 'none': 0}¶: (collections.abc.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.

class sass.SassColor(r, g, b, a)¶

class sass.SassError(msg)¶

class sass.SassFunction(name, arguments, callable_)¶

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

Parameters:

name (str) – the function name
arguments (collections.abc.Sequence) – the argument names
callable (collections.abc.Callable) – the actual function to be called

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

property signature¶: Signature string of the function.

class sass.SassList(items, separator, bracketed=False)¶

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.

class sass.SassNumber(value, unit)¶

class sass.SassWarning(msg)¶

sass.and_join(strings)¶

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

>>> 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
source_map_contents (bool) – embed include contents in map
source_map_embed (bool) – embed sourceMappingUrl as data URI
omit_source_map_url (bool) – omit source map URL comment from output
source_map_root (str) – base path, will be emitted in source map as is
include_paths (collections.abc.Sequence) – an optional list of paths to find @imported Sass/CSS source files
precision (int) – optional precision for numbers. 5 by default.
custom_functions (set, collections.abc.Sequence, collections.abc.Mapping) – optional mapping of custom functions. see also below custom functions description
custom_import_extensions – (ignored, for backward compatibility)
indented (bool) – optional declaration that the string is Sass, not SCSS formatted. False by default
importers (collections.abc.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.
source_map_contents (bool) – embed include contents in map
source_map_embed (bool) – embed sourceMappingUrl as data URI
omit_source_map_url (bool) – omit source map URL comment from output
source_map_root (str) – base path, will be emitted in source map as is
include_paths (collections.abc.Sequence) – an optional list of paths to find @imported Sass/CSS source files
precision (int) – optional precision for numbers. 5 by default.
custom_functions (set, collections.abc.Sequence, collections.abc.Mapping) – optional mapping of custom functions. see also below custom functions description
custom_import_extensions – (ignored, for backward compatibility)
importers (collections.abc.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:

sass.CompileError – when it fails for any reason (for example the given Sass has broken syntax)
exceptions.IOError – when the filename doesn’t exist or cannot be read

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
source_map_contents (bool) – embed include contents in map
source_map_embed (bool) – embed sourceMappingUrl as data URI
omit_source_map_url (bool) – omit source map URL comment from output
source_map_root (str) – base path, will be emitted in source map as is
include_paths (collections.abc.Sequence) – an optional list of paths to find @imported Sass/CSS source files
precision (int) – optional precision for numbers. 5 by default.
custom_functions (set, collections.abc.Sequence, collections.abc.Mapping) – optional mapping of custom functions. see also below custom functions description
custom_import_extensions – (ignored, for backward compatibility)

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 can accept one or two string arguments. The first argument is the path that was passed to the @import directive; the second (optional) argument is the previous resolved path, where the @import directive was found. The callbacks must 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, prev):
    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.

New in version 0.17.0: Added source_map_contents, source_map_embed, omit_source_map_url, and source_map_root parameters.

New in version 0.18.0: The importer callbacks can now take a second argument, the previously- resolved path, so that importers can do relative path resolution.

`sass` — Binding of `libsass`¶

libsass

Navigation

Related Topics

sass — Binding of libsass¶

`sass` — Binding of `libsass`¶