1PYSASSC(1) libsass PYSASSC(1)
2
6 pysassc - libsass Documentation
7 This package provides a simple Python extension module sass which is
9 binding LibSass (written in C/C++ by Hampton Catlin and Aaron Leung).
10 It's very straightforward and there isn't any headache related Python
11 distribution/deployment. That means you can add just libsass into your
12 setup.py's install_requires list or requirements.txt file.
13 It currently supports CPython 2.6, 2.7, 3.4--3.6, and PyPy 2.3+!
15
17 · You don't need any Ruby/Node.js stack at all, for development or
18 deployment either.
19 · Fast. (LibSass is written in C++.)
21 · Simple API. See example code for details.
23 · Custom functions.
25 · @import callbacks.
27 · Support both tabbed (Sass) and braces (SCSS) syntax.
29 · WSGI middleware for ease of development. It automatically compiles
31 Sass/SCSS files for each request. See also sassutils.wsgi for
32 details.
33 · setuptools/distutils integration. You can build all Sass/SCSS files
35 using setup.py build_sass command. See also sassutils.distutils for
36 details.
37 · Works also on PyPy.
39 · Provides prebuilt wheel (PEP 427) binaries for Windows and Mac.
41
43 It's available on PyPI, so you can install it using pip:
44 $ pip install libsass
46 NOTE:
48 libsass requires some features introduced by the recent C++ stan‐
49 dard. You need a C++ compiler that support those features. See
50 also libsass project's README file.
51
53 Compile a String of Sass to CSS
54 >>> import sass
55 >>> sass.compile(string='a { b { color: blue; } }')
56 'a b {\n color: blue; }\n'
57 Compile a Directory of Sass Files to CSS
59 >>> import sass
60 >>> import os
61 >>> os.mkdir('css')
62 >>> os.mkdir('sass')
63 >>> scss = """\
64 ... $theme_color: #cc0000;
65 ... body {
66 ... background-color: $theme_color;
67 ... }
68 ... """
69 >>> with open('sass/example.scss', 'w') as example_scss:
70 ... example_scss.write(scss)
71 ...
72 >>> sass.compile(dirname=('sass', 'css'), output_style='compressed')
73 >>> with open('css/example.css') as example_css:
74 ... print(example_css.read())
75 ...
76 body{background-color:#c00}
77
79 Using with Flask
80 This guide explains how to use libsass with Flask web framework. sas‐
81 sutils package provides several tools that can be integrated to web
82 applications written in Flask.
83 Contents
85 · Using with Flask
86 · Directory layout
88 · Defining manifest
90 · Building Sass/SCSS for each request
92 · Building Sass/SCSS for each deployment
94 Directory layout
96 Imagine the project contained in such directory layout:
97 · setup.py
99 · myapp/
101 · __init__.py
103 · static/
105 · sass/
107 · css/
109 · templates/
111 Sass/SCSS files will go inside myapp/static/sass/ directory. Compiled
113 CSS files will go inside myapp/static/css/ directory. CSS files can be
114 regenerated, so add myapp/static/css/ into your ignore list like .git‐
115 ignore or .hgignore.
116 Defining manifest
118 The sassutils defines a concept named manifest. Manifest is building
119 settings of Sass/SCSS. It specifies some paths related to building
120 Sass/SCSS:
121 · The path of the directory which contains Sass/SCSS source files.
123 · The path of the directory compiled CSS files will go.
125 · The path, is exposed to HTTP (through WSGI), of the directory that
127 will contain compiled CSS files.
128 Every package may have their own manifest. Paths have to be relative
130 to the path of the package.
131 For example, in the project the package name is myapp. The path of the
133 package is myapp/. The path of Sass/SCSS directory is static/sass/
134 (relative to the package directory). The path of CSS directory is
135 static/css/. The exposed path is /static/css.
136 This settings can be represented as the following manifests:
138 {
140 'myapp': ('static/sass', 'static/css', '/static/css')
141 }
142 As you can see the above, the set of manifests are represented in dic‐
144 tionary. Keys are packages names. Values are tuples of paths.
145 Building Sass/SCSS for each request
147 SEE ALSO:
148 Flask --- Hooking in WSGI Middlewares
150 The section which explains how to integrate WSGI middlewares
151 to Flask.
152 Flask --- flask:app-dispatch
154 The documentation which explains how Flask dispatch each
155 request internally.
156 In development, to manually build Sass/SCSS files for each change is so
158 tiring. SassMiddleware makes the web application to automatically
159 build Sass/SCSS files for each request. It's a WSGI middleware, so it
160 can be plugged into the web app written in Flask.
161 SassMiddleware takes two required parameters:
163 · The WSGI-compliant callable object.
165 · The set of manifests represented as dictionary.
167 So:
169 from flask import Flask
171 from sassutils.wsgi import SassMiddleware
172 app = Flask(__name__)
174 app.wsgi_app = SassMiddleware(app.wsgi_app, {
176 'myapp': ('static/sass', 'static/css', '/static/css')
177 })
178 And then, if you want to link a compiled CSS file, use url_for() func‐
180 tion:
181 <link href="{{ url_for('static', filename='css/style.scss.css') }}"
183 rel="stylesheet" type="text/css">
184 NOTE:
186 The linked filename is style.scss.css, not just style.scss. All
187 compiled filenames have trailing .css suffix.
188 Building Sass/SCSS for each deployment
190 NOTE:
191 This section assumes that you use setuptools for deployment.
192 SEE ALSO:
194 Flask --- flask:distribute-deployment
196 How to deploy Flask application using setuptools.
197 If libsass has been installed in the site-packages (for example, your
199 virtualenv), setup.py script also gets had new command provided by lib‐
200 sass: build_sass. The command is aware of sass_manifests option of
201 setup.py and builds all Sass/SCSS sources according to the manifests.
202 Add these arguments to setup.py script:
204 setup(
206 # ...,
207 setup_requires=['libsass >= 0.6.0'],
208 sass_manifests={
209 'myapp': ('static/sass', 'static/css', '/static/css')
210 }
211 )
212 The setup_requires option makes sure that the libsass is installed in
214 site-packages (for example, your virtualenv) before setup.py script.
215 That means: if you run setup.py script and libsass isn't installed yet
216 at the moment, it will automatically install libsass first.
217 The sass_manifests specifies the manifests for libsass.
219 Now setup.py build_sass will compile all Sass/SCSS files in the speci‐
221 fied path and generates compiled CSS files into the specified path
222 (according to the manifests).
223 If you use it with sdist or bdist command, a packed archive also will
225 contain compiled CSS files!
226 $ python setup.py build_sass sdist
228 You can add aliases to make these commands to always run build_sass
230 command before. Make setup.cfg config:
231 [aliases]
233 sdist = build_sass sdist
234 bdist = build_sass bdist
235 Now it automatically builds Sass/SCSS sources and include compiled CSS
237 files to the package archive when you run setup.py sdist.
238 Changelog
240 Version 0.14.5
241 Released on April 25, 2018.
242 · Follow up the libsass upstream: 3.5.4 --- See the release notes of
244 LibSass 3.5.4. [#247 by Anthony Sottile]
245 Version 0.14.4
247 Released on April 24, 2018.
248 · Add ability to specify imports for custom extensions. This provides
250 a way to enable imports of .css files (which was removed in 3.5.3).
251 Specify --import-extensions .css to restore the previous behavior.
252 [#246 by Samuel Colvin]
253 Version 0.14.3
255 Released on April 23, 2018.
256 · Follow up the libsass upstream: 3.5.3 --- See the release notes of
258 LibSass 3.5.3. [#244 by Anthony Sottile]
259 Version 0.14.2
261 Released on March 16, 2018.
262 · Follow up the libsass upstream: 3.5.2 --- See the release notes of
264 LibSass 3.5.2. [#243 by Anthony Sottile]
265 Version 0.14.1
267 Released on March 12, 2018.
268 · Follow up the libsass upstream: 3.5.1 --- See the release notes of
270 LibSass 3.5.1. [#242 by Anthony Sottile]
271 Version 0.14.0
273 Released on March 6, 2018.
274 · Follow up the libsass upstream: 3.5.0 --- See the release notes of
276 LibSass 3.5.0. [#241 by Anthony Sottile]
277 · SassList type gained an additional option bracketed=False to match
279 the upstream changes to the sass_list type. [#184 by Anthony Sottile]
280 Version 0.13.7
282 Released on February 5, 2018.
283 · Follow up the libsass upstream: 3.4.9 --- See the release notes of
285 LibSass 3.4.9. [#232 by Anthony Sottile]
286 Version 0.13.6
288 Released on January 19, 2018.
289 · libsass-python has moved to the sass organization!
291 Version 0.13.5
293 Released on January 11, 2018.
294 · Follow up the libsass upstream: 3.4.8 --- See the release notes of
296 LibSass 3.4.8. [#228 by Anthony Sottile]
297 Version 0.13.4
299 Released on November 14, 2017.
300 · Follow up the libsass upstream: 3.4.7 --- See the release notes of
302 LibSass 3.4.7. [#226 by Anthony Sottile]
303 Version 0.13.3
305 Released on October 11, 2017.
306 · Sort input files for determinism [#212 by Bernhard M. Wiedemann]
308 · Include LICENSE file in distributions [#216 by Dougal J. Sutherland]
310 · Add a pysassc entry to replace sassc [#218 by Anthony Sottile]
312 · Enable building with dynamic linking [#219 by Marcel Plch]
314 · Follow up the libsass upstream: 3.4.6 --- See the release notes of
316 LibSass 3.4.6. [#221 by Anthony Sottile]
317 Version 0.13.2
319 Released on June 14, 2017.
320 · Always add cwd to import paths [#208 by Anthony Sottile]
322 Version 0.13.1
324 Released on June 8, 2017.
325 · Follow up the libsass upstream: 3.4.5 --- See the release notes of
327 LibSass 3.4.5. [#207 by Anthony Sottile]
328 Version 0.13.0
330 Released on June 7, 2017.
331 · Use getfullargspec when available in python 3. [#188 by Thom Wiggers]
333 · Use sass_copy_c_string instead of strdup for portability [#196 by
335 Anthony Sottile]
336 · Use -std=gnu++0x to fix installation under cygwin [#195 #197 by
338 Anthony Sottile]
339 · Correct source map url [#201 #202 by Anthony Sottile]
341 · Remove --watch [#203 by Anthony Sottile]
343 · Follow up the libsass upstream: 3.4.4 --- See the release notes of
345 LibSass 3.4.4. [#205 by Anthony Sottile]
346 Version 0.12.3
348 Released on January 7, 2017.
349 · Follow up the libsass upstream: 3.4.3 --- See the release notes of
351 LibSass 3.4.3. [#178 by Anthony Sottile]
352 Version 0.12.2
354 Released on January 5, 2017.
355 · Follow up the libsass upstream: 3.4.2 --- See the release notes of
357 LibSass 3.4.2. [#176 by Anthony Sottile]
358 Version 0.12.1
360 Released on December 20, 2016.
361 · Follow up the libsass upstream: 3.4.1 --- See the release notes of
363 LibSass 3.4.1. [#175 by Anthony Sottile]
364 Version 0.12.0
366 Released on December 10, 2016.
367 · Follow up the libsass upstream: 3.4.0 --- See the release notes of
369 LibSass 3.4.0. [#173 by Anthony Sottile]
370 Version 0.11.2
372 Released on October 24, 2016.
373 · Drop support for python2.6 [#158 by Anthony Sottile]
375 · Deprecate --watch [#156 by Anthony Sottile]
377 · Preserve line endings [#160 by Anthony Sottile]
379 · Follow up the libsass upstream: 3.3.6 --- See the release notes of
381 LibSass 3.3.6. [#167 by Anthony Sottile]
382 Version 0.11.1
384 Released on April 22, 2016.
385 · Follow up the libsass upstream: 3.3.5 --- See the release notes of
387 LibSass 3.3.5. [#148 by Anthony Sottile]
388 Version 0.11.0
390 Released on March 23, 2016.
391 · Follow up the libsass upstream: 3.3.4 --- See the release notes of
393 LibSass 3.3.4. [#144 by Anthony Sottile]
394 · Expose libsass version in sassc --version and sass.libsass_version [‐
396 #142 #141 #140 by Anthony Sottile]
397 · Fix warning about unused enum on switch [#127 #131 by Anthony Sot‐
399 tile]
400 · Sourcemaps no longer imply source comments [#124 #130 by Tim Tisdall]
402 · Add --source-comments option to sassc [#124 #130 by Anthony Sottile]
404 · Improve formatting of CompileError under python3 [#123 by Anthony
406 Sottile]
407 · Raise when compiling a directory which does not exist [#116 #119 by
409 Anthony Sottile]
410 Version 0.10.1
412 Released on January 29, 2016.
413 · Follow up the libsass upstream: 3.3.3 --- See the release notes of
415 LibSass 3.3.3. [by Anthony Sottile]
416 · Allow -t for style like sassc [#98 by Anthony Sottile]
418 Version 0.10.0
420 Released on December 15, 2015.
421 · Support custom import callbacks [#81 by Alice Zoë Bevan–McGregor,
423 Anthony Sottile]
424 · Disallow arbitrary kwargs in compile() [#109 by Anthony Sottile]
426 Version 0.9.3
428 Released on December 03, 2015.
429 · Support "indented" Sass compilation [#41 by Alice Zoë Bevan–McGregor]
431 · Fix wheels on windows [#28 #49 by Anthony Sottile]
433 Version 0.9.2
435 Released on November 12, 2015.
436 · Follow up the libsass upstream: 3.3.2 --- See the release notes of
438 LibSass 3.3.2. [by Anthony Sottile]
439 · Require VS 2015 to build on windows [#99 by Anthony Sottile]
441 Version 0.9.1
443 Released on October 29, 2015.
444 · Follow up the libsass upstream: 3.3.1 --- See the release notes of
446 LibSass 3.3.1. [by Anthony Sottile]
447 Version 0.9.0
449 Released on October 28, 2015.
450 · Fix a bug with writing UTF-8 to a file [#72 by Caleb Ely]
452 · Fix a segmentation fault on ^C [#87 by Anthony Sottile]
454 · Follow up the libsass upstream: 3.3.0 --- See the release notes of
456 LibSass 3.3.0. [#96 by Anthony Sottile]
457 Version 0.8.3
459 Released on August 2, 2015.
460 · Follow up the libsass upstream: 3.2.5 --- See the release notes of
462 LibSass 3.2.5. [#79, #80 by Anthony Sottile]
463 · Fixed a bug that *.sass files were ignored. [#78 by Guilhem
465 MAS-PAITRAULT]
466 Version 0.8.2
468 Released on May 19, 2015.
469 · Follow up the libsass upstream: 3.2.4 --- See the release notes of
471 LibSass 3.2.3, and 3.2.4. [#69 by Anthony Sottile]
472 · The default value of SassMiddleware's error_status parameter was
474 changed from '500 Internal Server Error' to '200 OK' so that Mozilla
475 Firefox can render the error message well. [#67, #68, #70 by zxv]
476 Version 0.8.1
478 Released on May 14, 2015.
479 · Fixed a bug that there was no 'expanded' in sass.OUTPUT_STYLES but
481 'expected' instead which is a typo. [#66 by Triangle717]
482 · Fixed broken FreeBSD build. [#65 by Toshiharu Moriyama]
484 Version 0.8.0
486 Released on May 3, 2015.
487 · Follow up the libsass upstream: 3.2.2 --- See the release notes of
489 LibSass 3.2.0, 3.2.1, and 3.2.2. [#61, #52, #56, #58, #62, #64 by
490 Anthony Sottile]
491 · Compact and expanded output styles [#37]
493 · Strings and interpolation closer to Ruby Sass
495 · The correctness of the generated sourcemap files
497 · Directive buddling
499 · Full support for the @at-root directive
501 · Full support for !global variable scoping
503 · Now underscored files are ignored when compiling a directory. [#57
505 by Anthony Sottile]
506 · Fixed broken FreeBSD build. [#34, #60 by Ilya Baryshev]
508 · SassMiddleware became to log syntax errors if exist during compila‐
510 tion to sassutils.wsgi.SassMiddleware logger with level ERROR. [#42]
511 Version 0.7.0
513 Released on March 6, 2015.
514 Anthony Sottile contributed to the most of this release. Huge thanks
516 to him!
517 · Follow up the libsass upstream: 3.1.0 --- See the release note of
519 LibSass. [#38, #43 by Anthony Sottile]
520 · Custom functions and imports
522 · Decrementing in @for loops
524 · @debug and @error
526 · not operator
528 · nth() for maps
530 · inspect()
532 · feature-exists()
534 · unique-id()
536 · random()
538 · Added custom functions support. [#13, #44 by Anthony Sottile]
540 · Added sass.SassFunction class.
542 · Added custom_functions parameter to sass.compile() function.
544 · Added data types for custom functions:
546 · sass.SassNumber
548 · sass.SassColor
550 · sass.SassList
552 · sass.SassMap
554 · sass.SassError
556 · sass.SassWarning
558 · Added precision parameter to sass.compile() function. [#39 by Andrea
560 Stagi]
561 · sassc has a new -p/--precision option. [#39 by Andrea Stagi]
563 Version 0.6.2
565 Released on November 25, 2014.
566 Although 0.6.0--0.6.1 have needed GCC (G++) 4.8+, LLVM Clang 3.3+, now
568 it became back to only need GCC (G++) 4.6+, LLVM Clang 2.9+, or Visual
569 Studio 2013 Update 4+.
570 · Follow up the libsass upstream: 3.0.2 --- See the release note of
572 libsass. [#33 by Rodolphe Pelloux-Prayer]
573 · Fixed a bug that sassc --watch crashed when a file is not compilable
575 on the first try. [#32 by Alan Justino da Silva]
576 · Fixed broken build on Windows.
578 Version 0.6.1
580 Released on November 6, 2014.
581 · Follow up the libsass upstream: 3.0.1 --- See the release note of
583 LibSass.
584 · Fixed a bug that SassMiddleware never closes the socket on some WSGI
586 servers e.g. eventlet.wsgi.
587 Version 0.6.0
589 Released on October 27, 2014.
590 Note that since libsass-python 0.6.0 (and libsass 3.0) it requires
592 C++11 to compile. Although 0.6.2 became back to only need GCC (G++)
593 4.6+, LLVM Clang 2.9+, from 0.6.0 to 0.6.1 you need GCC (G++) 4.8+,
594 LLVM Clang 3.3+, or Visual Studio 2013 Update 4+.
595 · Follow up the libsass upstream: 3.0 --- See the release note of Lib‐
597 Sass.
598 · Decent extends support
600 · Basic Sass Maps Support
602 · Better UTF-8 Support
604 · call() function
606 · Better Windows Support
608 · Spec Enhancements
610 · Added missing partial import support. [#27 by item4]
612 · SOURCE_COMMENTS became deprecated.
614 · sass.compile()'s parameter source_comments now can take only bool
616 instead of str. String values like 'none', 'line_numbers', and 'map'
617 become deprecated, and will be obsolete soon.
618 · build_directory() function has a new optional parameter output_style.
620 · build() method has a new optional parameter output_style.
622 · Added --output-style/-s option to build_sass command. [#25]
624 Version 0.5.1
626 Released on September 23, 2014.
627 · Fixed a bug that SassMiddleware yielded str instead of bytes on
629 Python 3.
630 · Fixed several Unicode-related bugs on Windows.
632 · Fixed a bug that build_directory(), SassMiddleware, and build_sass
634 don't recursively build subdirectories.
635 Version 0.5.0
637 Released on June 6, 2014.
638 · Follow up the libsass upstream: 2.0 --- See the release note of Lib‐
640 Sass.
641 · Added indented syntax support (*.sass files).
643 · Added expanded selector support (BEM).
645 · Added string functions.
647 · Fixed UTF-8 support.
649 · Backward incompatibility: broken extends.
651 Unstable version 0.4.2.20140529.cd3ee1cbe3
653 Released on May 29, 2014.
654 · Version scheme changed to use periods (.) instead of hyphens (-) due
656 to setuptools seems to treat hyphens special.
657 · Fixed malformed packaging that doesn't correctly preserve the package
659 name and version.
660 Unstable Version 0.4.2-20140528-cd3ee1cbe3
662 Released on May 28, 2014.
663 · Follow up the libsass upstream:
665 cd3ee1cbe34d5316eb762a43127a3de9575454ee.
666 Version 0.4.2
668 Released on May 22, 2014.
669 · Fixed build failing on Mac OS X 10.8 or earlier. [#19]
671 · Fixed UnicodeEncodeError that Manifest.build_one() method rises when
673 the input source contains any non-ASCII Unicode characters.
674 Version 0.4.1
676 Released on May 20, 2014.
677 · Fixed UnicodeEncodeError that rise when the input source contains any
679 non-ASCII Unicode characters.
680 Version 0.4.0
682 Released on May 6, 2014.
683 · sassc has a new -w/--watch option.
685 · Expose source maps support:
687 · sassc has a new -m/-g/--sourcemap option.
689 · SassMiddleware now also creates source map files with filenames
691 followed by .map suffix.
692 · Manifest.build_one() method has a new source_map option. This
694 option builds also a source map file with the filename followed by
695 .map suffix.
696 · sass.compile() has a new optional parameter source_comments. It
698 can be one of sass.SOURCE_COMMENTS keys. It also has a new parame‐
699 ter source_map_filename which is required only when source_com‐
700 ments='map'.
701 · Fixed Python 3 incompatibility of sassc program.
703 · Fixed a bug that multiple include_paths doesn't work on Windows.
705 Version 0.3.0
707 Released on February 21, 2014.
708 · Added support for Python 3.3. [#7]
710 · Dropped support for Python 2.5.
712 · Fixed build failing on Mac OS X. [#4, #5, #6 by Hyungoo Kang]
714 · Now builder creates target recursive subdirectories even if it
716 doesn't exist yet, rather than siliently fails. [#8, #9 by Philipp
717 Volguine]
718 · Merged recent changes from libsass 1.0.1: 57a2f62--v1.0.1.
720 · Supports variable arguments.
722 · Supports sourcemaps.
724 Version 0.2.4
726 Released on December 4, 2012.
727 · Added sassc CLI executable script.
729 · Added sass.OUTPUT_STYLES constant map.
731 · Merged recent changes from libsass upstream: e997102--a84b181.
733 Version 0.2.3
735 Released on October 24, 2012.
736 · sassutils.distutils: Prevent double monkey patch of sdist.
738 · Merged upstream changes of libsass.
740 Version 0.2.2
742 Released on September 28, 2012.
743 · Fixed a link error on PyPy and Linux.
745 · Fixed build errors on Windows.
747 Version 0.2.1
749 Released on September 12, 2012.
750 · Support Windows.
752 Version 0.2.0
754 Released on August 24, 2012.
755 · Added new sassutils package.
757 · Added sassutils.builder module to build the whole directory at a
759 time.
760 · Added sassutils.distutils module for distutils and setuptools inte‐
762 gration.
763 · Added sassutils.wsgi module which provides a development-purpose
765 WSGI middleware.
766 · Added build_sass command for distutils/setuptools.
768 Version 0.1.1
770 Released on August 18, 2012.
771 · Fixed segmentation fault for reading filename which does not exist.
773 Now it raises a proper exceptions.IOError exception.
774 Version 0.1.0
776 Released on August 17, 2012. Initial version.
777
779 sassc --- SassC compliant command line interface
780 This provides SassC compliant CLI executable named sassc:
781 $ sassc
783 Usage: sassc [options] SCSS_FILE [CSS_FILE]
784 There are options as well:
786 -t <style>, --style <style>
788 Coding style of the compiled result. The same as sass.compile()
789 function's output_style keyword argument. Default is nested.
790 -s <style>, --output-style <style>
792 Alias for -t / --style.
793 Deprecated since version 0.11.0.
795 -I <dir>, --include-path <dir>
798 Optional directory path to find @imported (S)CSS files. Can be
799 multiply used.
800 -m, -g, --sourcemap
802 Emit source map. Requires the second argument (output CSS file‐
803 name). The filename of source map will be the output CSS file‐
804 name followed by .map.
805 New in version 0.4.0.
807 -p, --precision
810 Set the precision for numbers. Default is 5.
811 New in version 0.7.0.
813 --source-comments
816 Include debug info in output.
817 New in version 0.11.0.
819 -v, --version
822 Prints the program version.
823 -h, --help
825 Prints the help message.
826 sass --- Binding of libsass
828 This simple C extension module provides a very simple binding of lib‐
829 sass, which is written in C/C++. It contains only one function and one
830 exception type.
831 >>> import sass
833 >>> sass.compile(string='a { b { color: blue; } }')
834 'a b {
835 color: blue; }
836 '
837 sass.MODES = frozenset({'string', 'filename', 'dirname'})
839 (frozenset) The set of keywords compile() can take.
840 sass.OUTPUT_STYLES = {'compact': 2, 'compressed': 3, 'expanded': 1,
842 'nested': 0}
843 (collections.abc.Mapping) The dictionary of output styles. Keys
844 are output name strings, and values are flag integers.
845 sass.SOURCE_COMMENTS = {'default': 1, 'line_numbers': 1, 'map': 2,
847 'none': 0}
848 (collections.abc.Mapping) The dictionary of source comments
849 styles. Keys are mode names, and values are corresponding flag
850 integers.
851 New in version 0.4.0.
853 Deprecated since version 0.6.0.
856 exception sass.CompileError(msg)
859 The exception type that is raised by compile(). It is a subtype
860 of exceptions.ValueError.
861 class sass.SassColor
863 class sass.SassError
865 class sass.SassFunction(name, arguments, callable_)
867 Custom function for Sass. It can be instantiated using
868 from_lambda() and from_named_function() as well.
869 Parameters
871 · name (str) -- the function name
873 · arguments (collections.abc.Sequence) -- the argument
875 names
876 · callable (collections.abc.Callable) -- the actual func‐
878 tion to be called
879 New in version 0.7.0.
881 classmethod from_lambda(name, lambda_)
884 Make a SassFunction object from the given lambda_ func‐
885 tion. Since lambda functions don't have their name, it
886 need its name as well. Arguments are automatically
887 inspected.
888 Parameters
890 · name (str) -- the function name
892 · lambda (types.LambdaType) -- the actual lambda
894 function to be called
895 Returns
897 a custom function wrapper of the lambda_ function
898 Return type
900 SassFunction
901 classmethod from_named_function(function)
903 Make a SassFunction object from the named function.
904 Function name and arguments are automatically inspected.
905 Parameters
907 function (types.FunctionType) -- the named func‐
908 tion to be called
909 Returns
911 a custom function wrapper of the function
912 Return type
914 SassFunction
915 signature
917 Signature string of the function.
918 class sass.SassList
920 class sass.SassMap(*args, **kwargs)
922 Because sass maps can have mapping types as keys, we need an
923 immutable hashable mapping type.
924 New in version 0.7.0.
926 class sass.SassNumber
929 class sass.SassWarning
931 sass.and_join(strings)
933 Join the given strings by commas with last ' and ' conjuction.
934 >>> and_join(['Korea', 'Japan', 'China', 'Taiwan'])
936 'Korea, Japan, China, and Taiwan'
937 Parameters
939 strings -- a list of words to join
940 Returns
942 a joined string
943 Return type
945 str, basestring
946 sass.compile(**kwargs)
948 There are three modes of parameters compile() can take: string,
949 filename, and dirname.
950 The string parameter is the most basic way to compile Sass. It
952 simply takes a string of Sass code, and then returns a compiled
953 CSS string.
954 Parameters
956 · string (str) -- Sass source code to compile. it's
958 exclusive to filename and dirname parameters
959 · output_style (str) -- an optional coding style of the
961 compiled result. choose one of: 'nested' (default),
962 'expanded', 'compact', 'compressed'
963 · source_comments (bool) -- whether to add comments about
965 source lines. False by default
966 · include_paths (collections.abc.Sequence) -- an optional
968 list of paths to find @imported Sass/CSS source files
969 · precision (int) -- optional precision for numbers. 5 by
971 default.
972 · custom_functions (set, collections.abc.Sequence, col‐
974 lections.abc.Mapping) -- optional mapping of custom
975 functions. see also below custom functions description
976 · custom_import_extensions (list, tuple) -- optional
978 extra file extensions which allow can be imported, eg.
979 ['.css']
980 · indented (bool) -- optional declaration that the string
982 is Sass, not SCSS formatted. False by default
983 · importers (collections.abc.Callable) -- optional call‐
985 back functions. see also below importer callbacks
986 description
987 Returns
989 the compiled CSS string
990 Return type
992 str
993 Raises sass.CompileError -- when it fails for any reason (for
995 example the given Sass has broken syntax)
996 The filename is the most commonly used way. It takes a string
998 of Sass filename, and then returns a compiled CSS string.
999 Parameters
1001 · filename (str) -- the filename of Sass source code to
1003 compile. it's exclusive to string and dirname parame‐
1004 ters
1005 · output_style (str) -- an optional coding style of the
1007 compiled result. choose one of: 'nested' (default),
1008 'expanded', 'compact', 'compressed'
1009 · source_comments (bool) -- whether to add comments about
1011 source lines. False by default
1012 · source_map_filename (str) -- use source maps and indi‐
1014 cate the source map output filename. None means not
1015 using source maps. None by default.
1016 · include_paths (collections.abc.Sequence) -- an optional
1018 list of paths to find @imported Sass/CSS source files
1019 · precision (int) -- optional precision for numbers. 5 by
1021 default.
1022 · custom_functions (set, collections.abc.Sequence, col‐
1024 lections.abc.Mapping) -- optional mapping of custom
1025 functions. see also below custom functions description
1026 · custom_import_extensions (list, tuple) -- optional
1028 extra file extensions which allow can be imported, eg.
1029 ['.css']
1030 · importers (collections.abc.Callable) -- optional call‐
1032 back functions. see also below importer callbacks
1033 description
1034 Returns
1036 the compiled CSS string, or a pair of the compiled CSS
1037 string and the source map string if source_map_filename
1038 is set
1039 Return type
1041 str, tuple
1042 Raises
1044 · sass.CompileError -- when it fails for any reason (for
1046 example the given Sass has broken syntax)
1047 · exceptions.IOError -- when the filename doesn't exist
1049 or cannot be read
1050 The dirname is useful for automation. It takes a pair of paths.
1052 The first of the dirname pair refers the source directory, con‐
1053 tains several Sass source files to compiled. Sass source files
1054 can be nested in directories. The second of the pair refers the
1055 output directory that compiled CSS files would be saved. Direc‐
1056 tory tree structure of the source directory will be maintained
1057 in the output directory as well. If dirname parameter is used
1058 the function returns None.
1059 Parameters
1061 · dirname (tuple) -- a pair of (source_dir, output_dir).
1063 it's exclusive to string and filename parameters
1064 · output_style (str) -- an optional coding style of the
1066 compiled result. choose one of: 'nested' (default),
1067 'expanded', 'compact', 'compressed'
1068 · source_comments (bool) -- whether to add comments about
1070 source lines. False by default
1071 · include_paths (collections.abc.Sequence) -- an optional
1073 list of paths to find @imported Sass/CSS source files
1074 · precision (int) -- optional precision for numbers. 5 by
1076 default.
1077 · custom_functions (set, collections.abc.Sequence, col‐
1079 lections.abc.Mapping) -- optional mapping of custom
1080 functions. see also below custom functions description
1081 · custom_import_extensions (list, tuple) -- optional
1083 extra file extensions which allow can be imported, eg.
1084 ['.css']
1085 Raises sass.CompileError -- when it fails for any reason (for
1087 example the given Sass has broken syntax)
1088 The custom_functions parameter can take three types of forms:
1090 set/Sequence of SassFunctions
1092 It is the most general form. Although pretty verbose, it
1093 can take any kind of callables like type objects, unnamed
1094 functions, and user-defined callables.
1095 sass.compile(
1097 ...,
1098 custom_functions={
1099 sass.SassFunction('func-name', ('$a', '$b'), some_callable),
1100 ...
1101 }
1102 )
1103 Mapping of names to functions
1105 Less general, but easier-to-use form. Although it's not
1106 it can take any kind of callables, it can take any kind
1107 of functions defined using def/lambda syntax. It cannot
1108 take callables other than them since inspecting arguments
1109 is not always available for every kind of callables.
1110 sass.compile(
1112 ...,
1113 custom_functions={
1114 'func-name': lambda a, b: ...,
1115 ...
1116 }
1117 )
1118 set/Sequence of named functions
1120 Not general, but the easiest-to-use form for named func‐
1121 tions. It can take only named functions, defined using
1122 def. It cannot take lambdas sinc names are unavailable
1123 for them.
1124 def func_name(a, b):
1126 return ...
1127 sass.compile(
1129 ...,
1130 custom_functions={func_name}
1131 )
1132 Newer versions of libsass allow developers to define callbacks
1134 to be called and given a chance to process @import directives.
1135 You can define yours by passing in a list of callables via the
1136 importers parameter. The callables must be passed as 2-tuples in
1137 the form:
1138 (priority_int, callback_fn)
1140 A priority of zero is acceptable; priority determines the order
1142 callbacks are attempted.
1143 These callbacks must accept a single string argument represent‐
1145 ing the path passed to the @import directive, and either return
1146 None to indicate the path wasn't handled by that callback (to
1147 continue with others or fall back on internal libsass filesystem
1148 behaviour) or a list of one or more tuples, each in one of three
1149 forms:
1150 · A 1-tuple representing an alternate path to handle internally;
1152 or,
1153 · A 2-tuple representing an alternate path and the content that
1155 path represents; or,
1156 · A 3-tuple representing the same as the 2-tuple with the addi‐
1158 tion of a "sourcemap".
1159 All tuple return values must be strings. As a not overly realis‐
1161 tic example:
1162 def my_importer(path):
1164 return [(path, '#' + path + ' { color: red; }')]
1165 sass.compile(
1167 ...,
1168 importers=[(0, my_importer)]
1169 )
1170 Now, within the style source, attempting to @import 'button';
1172 will instead attach color: red as a property of an element with
1173 the imported name.
1174 New in version 0.4.0: Added source_comments and source_map_file‐
1176 name parameters.
1177 Changed in version 0.6.0: The source_comments parameter becomes
1180 to take only bool instead of str.
1181 Deprecated since version 0.6.0: Values like 'none', 'line_num‐
1184 bers', and 'map' for the source_comments parameter are depre‐
1185 cated.
1186 New in version 0.7.0: Added precision parameter.
1189 New in version 0.7.0: Added custom_functions parameter.
1192 New in version 0.11.0: source_map_filename no longer implies
1195 source_comments.
1196 sassutils --- Additional utilities related to Sass
1199 This package provides several additional utilities related to Sass
1200 which depends on libsass core (sass module).
1201 sassutils.builder --- Build the whole directory
1203 sassutils.builder.SUFFIXES = frozenset({'scss', 'sass'})
1204 (frozenset) The set of supported filename suffixes.
1205 sassutils.builder.SUFFIX_PATTERN = re.compile('[.](scss|sass)$')
1207 (re.RegexObject) The regular expression pattern which matches to
1208 filenames of supported SUFFIXES.
1209 class sassutils.builder.Manifest(sass_path, css_path=None,
1211 wsgi_path=None)
1212 Building manifest of Sass/SCSS.
1213 Parameters
1215 · sass_path (str, basestring) -- the path of the direc‐
1217 tory that contains Sass/SCSS source files
1218 · css_path (str, basestring) -- the path of the directory
1220 to store compiled CSS files
1221 build(package_dir, output_style='nested')
1223 Builds the Sass/SCSS files in the specified sass_path.
1224 It finds sass_path and locates css_path as relative to
1225 the given package_dir.
1226 Parameters
1228 · package_dir (str, basestring) -- the path of
1230 package directory
1231 · output_style (str) -- an optional coding style
1233 of the compiled result. choose one of: 'nested'
1234 (default), 'expanded', 'compact', 'compressed'
1235 Returns
1237 the set of compiled CSS filenames
1238 Return type
1240 frozenset
1241 New in version 0.6.0: The output_style parameter.
1243 build_one(package_dir, filename, source_map=False)
1246 Builds one Sass/SCSS file.
1247 Parameters
1249 · package_dir (str, basestring) -- the path of
1251 package directory
1252 · filename (str, basestring) -- the filename of
1254 Sass/SCSS source to compile
1255 · source_map (bool) -- whether to use source maps.
1257 if True it also write a source map to a filename
1258 followed by .map suffix. default is False
1259 Returns
1261 the filename of compiled CSS
1262 Return type
1264 str, basestring
1265 New in version 0.4.0: Added optional source_map parame‐
1267 ter.
1268 resolve_filename(package_dir, filename)
1271 Gets a proper full relative path of Sass source and CSS
1272 source that will be generated, according to package_dir
1273 and filename.
1274 Parameters
1276 · package_dir (str, basestring) -- the path of
1278 package directory
1279 · filename (str, basestring) -- the filename of
1281 Sass/SCSS source to compile
1282 Returns
1284 a pair of (sass, css) path
1285 Return type
1287 tuple
1288 sassutils.builder.build_directory(sass_path, css_path, out‐
1290 put_style='nested', _root_sass=None, _root_css=None)
1291 Compiles all Sass/SCSS files in path to CSS.
1292 Parameters
1294 · sass_path (str, basestring) -- the path of the direc‐
1296 tory which contains source files to compile
1297 · css_path (str, basestring) -- the path of the directory
1299 compiled CSS files will go
1300 · output_style (str) -- an optional coding style of the
1302 compiled result. choose one of: 'nested' (default),
1303 'expanded', 'compact', 'compressed'
1304 Returns
1306 a dictionary of source filenames to compiled CSS file‐
1307 names
1308 Return type
1310 collections.abc.Mapping
1311 New in version 0.6.0: The output_style parameter.
1313 sassutils.distutils --- setuptools/distutils integration
1316 This module provides extensions (and some magical monkey-patches,
1317 sorry) of the standard distutils and setuptools (now it's named Dis‐
1318 tribute) for libsass.
1319 To use this, add libsass into setup_requires (not install_requires)
1321 option of the setup.py script:
1322 from setuptools import setup
1324 setup(
1326 # ...,
1327 setup_requires=['libsass >= 0.6.0']
1328 )
1329 It will adds build_sass command to the setup.py script:
1331 $ python setup.py build_sass
1333 This commands builds Sass/SCSS files to compiled CSS files of the
1335 project and makes the package archive (made by sdist, bdist, and so on)
1336 to include these compiled CSS files.
1337 To set the directory of Sass/SCSS source files and the directory to
1339 store compiled CSS files, specify sass_manifests option:
1340 from setuptools import find_packages, setup
1342 setup(
1344 name='YourPackage',
1345 packages=find_packages(),
1346 sass_manifests={
1347 'your.webapp': ('static/sass', 'static/css')
1348 },
1349 setup_requires=['libsass >= 0.6.0']
1350 )
1351 The option should be a mapping of package names to pairs of paths,
1353 e.g.:
1354 {
1356 'package': ('static/sass', 'static/css'),
1357 'package.name': ('static/scss', 'static')
1358 }
1359 New in version 0.6.0: Added --output-style/-s option to build_sass com‐
1361 mand.
1362 class sassutils.distutils.build_sass(dist, **kw)
1365 Builds Sass/SCSS files to CSS files.
1366 finalize_options()
1368 Set final values for all the options that this command
1369 supports. This is always called as late as possible, ie.
1370 after any option assignments from the command-line or
1371 from other commands have been done. Thus, this is the
1372 place to code option dependencies: if 'foo' depends on
1373 'bar', then it is safe to set 'foo' from 'bar' as long as
1374 'foo' still has the same value it was assigned in 'ini‐
1375 tialize_options()'.
1376 This method must be implemented by all command classes.
1378 get_package_dir(package)
1380 Returns the directory, relative to the top of the source
1381 distribution, where package package should be found (at
1382 least according to the package_dir option, if any).
1383 Copied from distutils.command.build_py.get_package_dir()
1385 method.
1386 initialize_options()
1388 Set default values for all the options that this command
1389 supports. Note that these defaults may be overridden by
1390 other commands, by the setup script, by config files, or
1391 by the command-line. Thus, this is not the place to code
1392 dependencies between options; generally, 'initial‐
1393 ize_options()' implementations are just a bunch of
1394 "self.foo = None" assignments.
1395 This method must be implemented by all command classes.
1397 run() A command's raison d'etre: carry out the action it exists
1399 to perform, controlled by the options initialized in
1400 'initialize_options()', customized by other commands, the
1401 setup script, the command-line, and config files, and
1402 finalized in 'finalize_options()'. All terminal output
1403 and filesystem interaction should be done by 'run()'.
1404 This method must be implemented by all command classes.
1406 sassutils.distutils.validate_manifests(dist, attr, value)
1408 Verifies that value is an expected mapping of package to sassu‐
1409 tils.builder.Manifest.
1410 sassutils.wsgi --- WSGI middleware for development purpose
1412 class sassutils.wsgi.SassMiddleware(app, manifests, package_dir={},
1413 error_status='200 OK')
1414 WSGI middleware for development purpose. Everytime a CSS file
1415 has requested it finds a matched Sass/SCSS source file and then
1416 compiled it into CSS.
1417 It shows syntax errors in three ways:
1419 Heading comment
1421 The result CSS includes detailed error message in the
1422 heading CSS comment e.g.:
1423 /*
1425 Error: invalid property name
1426 */
1427 Red text in body:before
1429 The result CSS draws detailed error message in :before
1430 pseudo-class of body element e.g.:
1431 body:before {
1433 content: 'Error: invalid property name';
1434 color: maroon;
1435 background-color: white;
1436 }
1437 In most cases you could be aware of syntax error by
1439 refreshing your working document because it will removes
1440 all other styles and leaves only a red text.
1441 logging
1443 It logs syntax errors if exist during compilation to sas‐
1444 sutils.wsgi.SassMiddleware logger with level ERROR.
1445 To enable this:
1447 from logging import Formatter, StreamHandler, getLogger
1449 logger = getLogger('sassutils.wsgi.SassMiddleware')
1450 handler = StreamHandler(level=logging.ERROR)
1451 formatter = Formatter(fmt='*' * 80 + '\n%(message)s\n' + '*' * 80)
1452 handler.setFormatter(formatter)
1453 logger.addHandler(handler)
1454 Or simply:
1456 import logging
1458 logging.basicConfig()
1459 Parameters
1461 · app (collections.abc.Callable) -- the WSGI application
1463 to wrap
1464 · manifests (collections.abc.Mapping) -- build settings.
1466 the same format to setup.py script's sass_manifests
1467 option
1468 · package_dir (collections.abc.Mapping) -- optional map‐
1470 ping of package names to directories. the same format
1471 to setup.py script's package_dir option
1472 Changed in version 0.4.0: It creates also source map files with
1474 filenames followed by .map suffix.
1475 New in version 0.8.0: It logs syntax errors if exist during com‐
1478 pilation to sassutils.wsgi.SassMiddleware logger with level
1479 ERROR.
1480 static quote_css_string(s)
1483 Quotes a string as CSS string literal.
1484
1486 Hong Minhee wrote this Python binding of LibSass.
1487 Hampton Catlin and Aaron Leung wrote LibSass, which is portable C/C++
1489 implementation of Sass.
1490 Hampton Catlin originally designed Sass language and wrote the first
1492 reference implementation of it in Ruby.
1493 The above three softwares are all distributed under MIT license.
1495
1497 GitHub (Git repository + issues)
1498 https://github.com/sass/libsass-python
1499 Travis CI
1501 https://travis-ci.org/sass/libsass-python Build Status.TP
1502 AppVeyor (CI for Windows)
1503 https://ci.appveyor.com/project/asottile/libsass-python Build
1504 Status (Windows).TP Coveralls (Test coverage)
1505 https://coveralls.io/r/sass/libsass-python Coverage Status.TP
1506 PyPI https://pypi.python.org/pypi/libsass PyPI.TP Changelog
1507 changes
1508
1510 · genindex
1511 · modindex
1513 · search
1515
1517 Hong Minhee
1518
1520 2012, Hong Minhee
15210.14.5 Feb 02, 2019 PYSASSC(1)