| LIBSASS(3) | libsass | LIBSASS(3) |
libsass - libsass Documentation
This package provides a simple Python extension module sass which is binding LibSass (written in C/C++ by Hampton Catlin and Aaron Leung). It's very straightforward and there isn't any headache related Python distribution/deployment. That means you can add just libsass into your setup.py's install_requires list or requirements.txt file.
It currently supports CPython 3.6+ and PyPy 3!
It's available on PyPI, so you can install it using pip:
$ pip install libsass
NOTE:
>>> import sass
>>> sass.compile(string='a { b { color: blue; } }')
'a b {\n color: blue; }\n'
>>> import sass
>>> import os
>>> os.mkdir('css')
>>> os.mkdir('sass')
>>> scss = """\
... $theme_color: #cc0000;
... body {
... background-color: $theme_color;
... }
... """
>>> with open('sass/example.scss', 'w') as example_scss:
... example_scss.write(scss)
...
>>> sass.compile(dirname=('sass', 'css'), output_style='compressed')
>>> with open('css/example.css') as example_css:
... print(example_css.read())
...
body{background-color:#c00}
This guide explains how to use libsass with the Flask web framework. sassutils package provides several tools that can be integrated into web applications written in Flask.
Imagine the project contained in such directory layout:
Sass/SCSS files will go inside myapp/static/sass/ directory. Compiled CSS files will go inside myapp/static/css/ directory. CSS files can be regenerated, so add myapp/static/css/ into your ignore list like .gitignore or .hgignore.
The sassutils defines a concept named manifest. Manifest is the build settings of Sass/SCSS. It specifies some paths related to building Sass/SCSS:
Every package may have its own manifest. Paths have to be relative to the path of the package.
For example, in the above project, the package name is myapp. The path of the package is myapp/. The path of the Sass/SCSS directory is static/sass/ (relative to the package directory). The path of the CSS directory is static/css/. The exposed path is /static/css.
These settings can be represented as the following manifests:
{
'myapp': ('static/sass', 'static/css', '/static/css')
}
As you can see the above, the set of manifests are represented in dictionary, in which the keys are packages names and the values are tuples of paths.
SEE ALSO:
In development, manually building Sass/SCSS files for each change is a tedious task. SassMiddleware makes the web application build Sass/SCSS files for each request automatically. It's a WSGI middleware, so it can be plugged into the web app written in Flask.
SassMiddleware takes two required parameters:
So:
from flask import Flask
from sassutils.wsgi import SassMiddleware
app = Flask(__name__)
app.wsgi_app = SassMiddleware(app.wsgi_app, {
'myapp': ('static/sass', 'static/css', '/static/css')
})
And then, if you want to link a compiled CSS file, use the url_for() function:
<link href="{{ url_for('static', filename='css/style.scss.css') }}"
rel="stylesheet" type="text/css">
NOTE:
NOTE:
SEE ALSO:
If libsass is installed in the site-packages (for example, your virtualenv), the setup.py script also gets a new command provided by libsass: build_sass. The command is aware of the sass_manifests option of setup.py and builds all Sass/SCSS sources according to the manifests.
Add these arguments to setup.py script:
setup(
# ...,
setup_requires=['libsass >= 0.6.0'],
sass_manifests={
'myapp': ('static/sass', 'static/css', '/static/css')
} )
The setup_requires option makes sure that libsass is installed in site-packages (for example, your virtualenv) before the setup.py script. That means if you run the setup.py script and libsass isn't installed in advance, it will automatically install libsass first.
The sass_manifests specifies the manifests for libsass.
Now setup.py build_sass will compile all Sass/SCSS files in the specified path and generates compiled CSS files inside the specified path (according to the manifests).
If you use it with sdist or bdist commands, the packed archive will also contain the compiled CSS files!
$ python setup.py build_sass sdist
You can add aliases to make these commands always run the build_sass command first. Make setup.cfg config:
[aliases] sdist = build_sass sdist bdist = build_sass bdist
Now it automatically builds Sass/SCSS sources and include the compiled CSS files to the package archive when you run setup.py sdist.
Released on November 12, 2022.
Released on May 20, 2021.
Released on August 27, 2020.
Released on May 1, 2020.
Released on November 3, 2019.
Released on October 5, 2019.
Released on June 16, 2019.
Released on May 18, 2019.
Released on May 18, 2019.
Release on March 13, 2019
Release on January 03, 2019
Released on November 25, 2018.
Released on November 13, 2018.
Released on September 24, 2018.
Released on September 16, 2018.
Released on April 25, 2018.
Released on April 24, 2018.
Released on April 23, 2018.
Released on March 16, 2018.
Released on March 12, 2018.
Released on March 6, 2018.
Released on February 5, 2018.
Released on January 19, 2018.
Released on January 11, 2018.
Released on November 14, 2017.
Released on October 11, 2017.
Released on June 14, 2017.
Released on June 8, 2017.
Released on June 7, 2017.
Released on January 7, 2017.
Released on January 5, 2017.
Released on December 20, 2016.
Released on December 10, 2016.
Released on October 24, 2016.
Released on April 22, 2016.
Released on March 23, 2016.
Released on January 29, 2016.
Released on December 15, 2015.
Released on December 03, 2015.
Released on November 12, 2015.
Released on October 29, 2015.
Released on October 28, 2015.
Released on August 2, 2015.
Released on May 19, 2015.
Released on May 14, 2015.
Released on May 3, 2015.
Released on March 6, 2015.
Anthony Sottile contributed to the most of this release. Huge thanks to him!
Released on November 25, 2014.
Although 0.6.0--0.6.1 have needed GCC (G++) 4.8+, LLVM Clang 3.3+, now it became back to only need GCC (G++) 4.6+, LLVM Clang 2.9+, or Visual Studio 2013 Update 4+.
Released on November 6, 2014.
Released on October 27, 2014.
Note that since libsass-python 0.6.0 (and libsass 3.0) it requires C++11 to compile. Although 0.6.2 became back to only need GCC (G++) 4.6+, LLVM Clang 2.9+, from 0.6.0 to 0.6.1 you need GCC (G++) 4.8+, LLVM Clang 3.3+, or Visual Studio 2013 Update 4+.
Released on September 23, 2014.
Released on June 6, 2014.
Released on May 29, 2014.
Released on May 28, 2014.
Released on May 22, 2014.
Released on May 20, 2014.
Released on May 6, 2014.
Released on February 21, 2014.
Released on December 4, 2012.
Released on October 24, 2012.
Released on September 28, 2012.
Released on September 12, 2012.
Released on August 24, 2012.
Released on August 18, 2012.
Released on August 17, 2012. Initial version.
This provides SassC compliant CLI executable named pysassc:
$ pysassc Usage: pysassc [options] SCSS_FILE [CSS_FILE]
There are options as well:
Deprecated since version 0.11.0.
New in version 0.4.0.
New in version 0.7.0.
New in version 0.11.0.
New in version 0.17.0.
New in version 0.17.0.
New in version 0.17.0.
New in version 0.17.0.
New in version 0.17.0.
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; }
'
New in version 0.4.0.
Deprecated since version 0.6.0.
New in version 0.7.0.
New in version 0.7.0.
>>> and_join(['Korea', 'Japan', 'China', 'Taiwan'])
'Korea, Japan, China, and Taiwan'
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.
The filename is the most commonly used way. It takes a string of Sass filename, and then returns a compiled CSS string.
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.
The custom_functions parameter can take three types of forms:
set/Sequence of SassFunctions
sass.compile(
...,
custom_functions={
sass.SassFunction('func-name', ('$a', '$b'), some_callable),
...
} )
sass.compile(
...,
custom_functions={
'func-name': lambda a, b: ...,
...
} )
set/Sequence of named functions
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:
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.
This package provides several additional utilities related to Sass which depends on libsass core (sass module).
New in version 0.6.0: The output_style parameter.
New in version 0.4.0: Added optional source_map parameter.
New in version 0.6.0: The output_style parameter.
This module provides extensions (and some magical monkey-patches, sorry) of the standard distutils and setuptools (now it's named Distribute) for libsass.
To use this, add libsass into setup_requires (not install_requires) option of the setup.py script:
from setuptools import setup setup(
# ...,
setup_requires=['libsass >= 0.6.0'] )
It will adds build_sass command to the setup.py script:
$ python setup.py build_sass
This commands builds Sass/SCSS files to compiled CSS files of the project and makes the package archive (made by sdist, bdist, and so on) to include these compiled CSS files.
To set the directory of Sass/SCSS source files and the directory to store compiled CSS files, specify sass_manifests option:
from setuptools import find_packages, setup setup(
name='YourPackage',
packages=find_packages(),
sass_manifests={
'your.webapp': ('static/sass', 'static/css')
},
setup_requires=['libsass >= 0.6.0'] )
The option should be a mapping of package names to pairs of paths, e.g.:
{
'package': ('static/sass', 'static/css'),
'package.name': ('static/scss', 'static')
}
The option can also be a mapping of package names to manifest dictionaries:
{
'package': {
'sass_path': 'static/sass',
'css_path': 'static/css',
'strip_extension': True,
},
}
New in version 0.15.0: Added strip_extension so a.scss is compiled to a.css instead of a.scss.css. This option will default to True in the future.
New in version 0.6.0: Added --output-style/-s option to build_sass command.
This method must be implemented by all command classes.
Copied from distutils.command.build_py.get_package_dir() method.
This method must be implemented by all command classes.
This method must be implemented by all command classes.
It shows syntax errors in three ways:
/* Error: invalid property name */
body:before {
content: 'Error: invalid property name';
color: maroon;
background-color: white;
}
In most cases you could be aware of syntax error by refreshing your working document because it will removes all other styles and leaves only a red text.
To enable this:
from logging import Formatter, StreamHandler, getLogger
logger = getLogger('sassutils.wsgi.SassMiddleware')
handler = StreamHandler(level=logging.ERROR)
formatter = Formatter(fmt='*' * 80 + '\n%(message)s\n' + '*' * 80)
handler.setFormatter(formatter)
logger.addHandler(handler)
Or simply:
import logging logging.basicConfig()
Changed in version 0.4.0: It creates also source map files with filenames followed by .map suffix.
New in version 0.8.0: It logs syntax errors if exist during compilation to sassutils.wsgi.SassMiddleware logger with level ERROR.
Hong Minhee wrote this Python binding of LibSass.
Hampton Catlin and Aaron Leung wrote LibSass, which is portable C/C++ implementation of Sass.
Hampton Catlin originally designed Sass language and wrote the first reference implementation of it in Ruby.
The above three are all distributed under MIT license.
Hong Minhee
2023, Hong Minhee
| January 4, 2023 | 0.22.0 |