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.5--3.7, 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.18.0
241 Release on March 13, 2019
242 · Add support for previous import path to importer callbacks [#287 #291
244 by Frankie Dintino]
245 Version 0.17.0
247 Release on January 03, 2019
248 ·
250 Add several new cli options [#279 #268 by Frankie Dintino]
252 · --sourcemap-file: output file for source map
254 · --sourcemap-contents: embed sourcesContent in source map
256 · --sourcemap-embed: embed sourceMappingURL as data uri
258 · --omit-sourcemap-url: omit source map url comment from out‐
260 put
261 · --sourcemap-root: base path, emitted as sourceRoot in source
263 map
264 · Fix .sass in WsgiMiddleware (again) [#280 by Anthony Sottile]
266 Version 0.16.1
268 Released on November 25, 2018.
269 · Fix compilation on macos mojave [#276 #277 by Anthony Sottile]
271 · Fix .sass in WsgiMiddleware for strip_extension=True [#278 by Anthony
273 Sottile]
274 Version 0.16.0
276 Released on November 13, 2018.
277 · Use -lc++ link flag when compiling with clang [#270 by Christian
279 Thieme #271 by Anthony Sottile]
280 · Honor strip_extension in SassMiddleware [#274 by Anthony Sottile]
282 · Follow up the libsass upstream: 3.5.5 --- See the release notes of
284 LibSass 3.5.5. [#275 by Anthony Sottile]
285 Version 0.15.1
287 Released on September 24, 2018.
288 · Fix setup.py sdist (regressed in 0.15.0) [#267 by Anthony Sottile]
290 Version 0.15.0
292 Released on September 16, 2018.
293 · Fix invalid escape sequences [#249 by Anthony Sottile]
295 · Add code of conduct [#251 by Nick Schonning]
297 · Add support for python3.7 and remove testing for python3.4 [#254 by
299 Anthony Sottile]
300 · Add strip_extension option for wsgi / distutils builder [#55 #258 by
302 Anthony Sottile #260 by Morten Brekkevold]
303 · Deprecate sassc (replaced by pysassc). [#262 by Anthony Sottile]
305 · Import abc classes from collections.abc to remove DeprecationWarning
307 [#264 by Gary van der Merwe #265 by Anthony Sottile]
308 Version 0.14.5
310 Released on April 25, 2018.
311 · Follow up the libsass upstream: 3.5.4 --- See the release notes of
313 LibSass 3.5.4. [#247 by Anthony Sottile]
314 Version 0.14.4
316 Released on April 24, 2018.
317 · Add ability to specify imports for custom extensions. This provides
319 a way to enable imports of .css files (which was removed in 3.5.3).
320 Specify --import-extensions .css to restore the previous behavior.
321 [#246 by Samuel Colvin]
322 Version 0.14.3
324 Released on April 23, 2018.
325 · Follow up the libsass upstream: 3.5.3 --- See the release notes of
327 LibSass 3.5.3. [#244 by Anthony Sottile]
328 Version 0.14.2
330 Released on March 16, 2018.
331 · Follow up the libsass upstream: 3.5.2 --- See the release notes of
333 LibSass 3.5.2. [#243 by Anthony Sottile]
334 Version 0.14.1
336 Released on March 12, 2018.
337 · Follow up the libsass upstream: 3.5.1 --- See the release notes of
339 LibSass 3.5.1. [#242 by Anthony Sottile]
340 Version 0.14.0
342 Released on March 6, 2018.
343 · Follow up the libsass upstream: 3.5.0 --- See the release notes of
345 LibSass 3.5.0. [#241 by Anthony Sottile]
346 · SassList type gained an additional option bracketed=False to match
348 the upstream changes to the sass_list type. [#184 by Anthony Sottile]
349 Version 0.13.7
351 Released on February 5, 2018.
352 · Follow up the libsass upstream: 3.4.9 --- See the release notes of
354 LibSass 3.4.9. [#232 by Anthony Sottile]
355 Version 0.13.6
357 Released on January 19, 2018.
358 · libsass-python has moved to the sass organization!
360 Version 0.13.5
362 Released on January 11, 2018.
363 · Follow up the libsass upstream: 3.4.8 --- See the release notes of
365 LibSass 3.4.8. [#228 by Anthony Sottile]
366 Version 0.13.4
368 Released on November 14, 2017.
369 · Follow up the libsass upstream: 3.4.7 --- See the release notes of
371 LibSass 3.4.7. [#226 by Anthony Sottile]
372 Version 0.13.3
374 Released on October 11, 2017.
375 · Sort input files for determinism [#212 by Bernhard M. Wiedemann]
377 · Include LICENSE file in distributions [#216 by Dougal J. Sutherland]
379 · Add a pysassc entry to replace sassc [#218 by Anthony Sottile]
381 · Enable building with dynamic linking [#219 by Marcel Plch]
383 · Follow up the libsass upstream: 3.4.6 --- See the release notes of
385 LibSass 3.4.6. [#221 by Anthony Sottile]
386 Version 0.13.2
388 Released on June 14, 2017.
389 · Always add cwd to import paths [#208 by Anthony Sottile]
391 Version 0.13.1
393 Released on June 8, 2017.
394 · Follow up the libsass upstream: 3.4.5 --- See the release notes of
396 LibSass 3.4.5. [#207 by Anthony Sottile]
397 Version 0.13.0
399 Released on June 7, 2017.
400 · Use getfullargspec when available in python 3. [#188 by Thom Wiggers]
402 · Use sass_copy_c_string instead of strdup for portability [#196 by
404 Anthony Sottile]
405 · Use -std=gnu++0x to fix installation under cygwin [#195 #197 by
407 Anthony Sottile]
408 · Correct source map url [#201 #202 by Anthony Sottile]
410 · Remove --watch [#203 by Anthony Sottile]
412 · Follow up the libsass upstream: 3.4.4 --- See the release notes of
414 LibSass 3.4.4. [#205 by Anthony Sottile]
415 Version 0.12.3
417 Released on January 7, 2017.
418 · Follow up the libsass upstream: 3.4.3 --- See the release notes of
420 LibSass 3.4.3. [#178 by Anthony Sottile]
421 Version 0.12.2
423 Released on January 5, 2017.
424 · Follow up the libsass upstream: 3.4.2 --- See the release notes of
426 LibSass 3.4.2. [#176 by Anthony Sottile]
427 Version 0.12.1
429 Released on December 20, 2016.
430 · Follow up the libsass upstream: 3.4.1 --- See the release notes of
432 LibSass 3.4.1. [#175 by Anthony Sottile]
433 Version 0.12.0
435 Released on December 10, 2016.
436 · Follow up the libsass upstream: 3.4.0 --- See the release notes of
438 LibSass 3.4.0. [#173 by Anthony Sottile]
439 Version 0.11.2
441 Released on October 24, 2016.
442 · Drop support for python2.6 [#158 by Anthony Sottile]
444 · Deprecate --watch [#156 by Anthony Sottile]
446 · Preserve line endings [#160 by Anthony Sottile]
448 · Follow up the libsass upstream: 3.3.6 --- See the release notes of
450 LibSass 3.3.6. [#167 by Anthony Sottile]
451 Version 0.11.1
453 Released on April 22, 2016.
454 · Follow up the libsass upstream: 3.3.5 --- See the release notes of
456 LibSass 3.3.5. [#148 by Anthony Sottile]
457 Version 0.11.0
459 Released on March 23, 2016.
460 · Follow up the libsass upstream: 3.3.4 --- See the release notes of
462 LibSass 3.3.4. [#144 by Anthony Sottile]
463 · Expose libsass version in sassc --version and sass.libsass_version [‐
465 #142 #141 #140 by Anthony Sottile]
466 · Fix warning about unused enum on switch [#127 #131 by Anthony Sot‐
468 tile]
469 · Sourcemaps no longer imply source comments [#124 #130 by Tim Tisdall]
471 · Add --source-comments option to sassc [#124 #130 by Anthony Sottile]
473 · Improve formatting of CompileError under python3 [#123 by Anthony
475 Sottile]
476 · Raise when compiling a directory which does not exist [#116 #119 by
478 Anthony Sottile]
479 Version 0.10.1
481 Released on January 29, 2016.
482 · Follow up the libsass upstream: 3.3.3 --- See the release notes of
484 LibSass 3.3.3. [by Anthony Sottile]
485 · Allow -t for style like sassc [#98 by Anthony Sottile]
487 Version 0.10.0
489 Released on December 15, 2015.
490 · Support custom import callbacks [#81 by Alice Zoë Bevan–McGregor,
492 Anthony Sottile]
493 · Disallow arbitrary kwargs in compile() [#109 by Anthony Sottile]
495 Version 0.9.3
497 Released on December 03, 2015.
498 · Support "indented" Sass compilation [#41 by Alice Zoë Bevan–McGregor]
500 · Fix wheels on windows [#28 #49 by Anthony Sottile]
502 Version 0.9.2
504 Released on November 12, 2015.
505 · Follow up the libsass upstream: 3.3.2 --- See the release notes of
507 LibSass 3.3.2. [by Anthony Sottile]
508 · Require VS 2015 to build on windows [#99 by Anthony Sottile]
510 Version 0.9.1
512 Released on October 29, 2015.
513 · Follow up the libsass upstream: 3.3.1 --- See the release notes of
515 LibSass 3.3.1. [by Anthony Sottile]
516 Version 0.9.0
518 Released on October 28, 2015.
519 · Fix a bug with writing UTF-8 to a file [#72 by Caleb Ely]
521 · Fix a segmentation fault on ^C [#87 by Anthony Sottile]
523 · Follow up the libsass upstream: 3.3.0 --- See the release notes of
525 LibSass 3.3.0. [#96 by Anthony Sottile]
526 Version 0.8.3
528 Released on August 2, 2015.
529 · Follow up the libsass upstream: 3.2.5 --- See the release notes of
531 LibSass 3.2.5. [#79, #80 by Anthony Sottile]
532 · Fixed a bug that *.sass files were ignored. [#78 by Guilhem
534 MAS-PAITRAULT]
535 Version 0.8.2
537 Released on May 19, 2015.
538 · Follow up the libsass upstream: 3.2.4 --- See the release notes of
540 LibSass 3.2.3, and 3.2.4. [#69 by Anthony Sottile]
541 · The default value of SassMiddleware's error_status parameter was
543 changed from '500 Internal Server Error' to '200 OK' so that Mozilla
544 Firefox can render the error message well. [#67, #68, #70 by zxv]
545 Version 0.8.1
547 Released on May 14, 2015.
548 · Fixed a bug that there was no 'expanded' in sass.OUTPUT_STYLES but
550 'expected' instead which is a typo. [#66 by Triangle717]
551 · Fixed broken FreeBSD build. [#65 by Toshiharu Moriyama]
553 Version 0.8.0
555 Released on May 3, 2015.
556 · Follow up the libsass upstream: 3.2.2 --- See the release notes of
558 LibSass 3.2.0, 3.2.1, and 3.2.2. [#61, #52, #56, #58, #62, #64 by
559 Anthony Sottile]
560 · Compact and expanded output styles [#37]
562 · Strings and interpolation closer to Ruby Sass
564 · The correctness of the generated sourcemap files
566 · Directive buddling
568 · Full support for the @at-root directive
570 · Full support for !global variable scoping
572 · Now underscored files are ignored when compiling a directory. [#57
574 by Anthony Sottile]
575 · Fixed broken FreeBSD build. [#34, #60 by Ilya Baryshev]
577 · SassMiddleware became to log syntax errors if exist during compila‐
579 tion to sassutils.wsgi.SassMiddleware logger with level ERROR. [#42]
580 Version 0.7.0
582 Released on March 6, 2015.
583 Anthony Sottile contributed to the most of this release. Huge thanks
585 to him!
586 · Follow up the libsass upstream: 3.1.0 --- See the release note of
588 LibSass. [#38, #43 by Anthony Sottile]
589 · Custom functions and imports
591 · Decrementing in @for loops
593 · @debug and @error
595 · not operator
597 · nth() for maps
599 · inspect()
601 · feature-exists()
603 · unique-id()
605 · random()
607 · Added custom functions support. [#13, #44 by Anthony Sottile]
609 · Added sass.SassFunction class.
611 · Added custom_functions parameter to sass.compile() function.
613 · Added data types for custom functions:
615 · sass.SassNumber
617 · sass.SassColor
619 · sass.SassList
621 · sass.SassMap
623 · sass.SassError
625 · sass.SassWarning
627 · Added precision parameter to sass.compile() function. [#39 by Andrea
629 Stagi]
630 · sassc has a new -p/--precision option. [#39 by Andrea Stagi]
632 Version 0.6.2
634 Released on November 25, 2014.
635 Although 0.6.0--0.6.1 have needed GCC (G++) 4.8+, LLVM Clang 3.3+, now
637 it became back to only need GCC (G++) 4.6+, LLVM Clang 2.9+, or Visual
638 Studio 2013 Update 4+.
639 · Follow up the libsass upstream: 3.0.2 --- See the release note of
641 libsass. [#33 by Rodolphe Pelloux-Prayer]
642 · Fixed a bug that sassc --watch crashed when a file is not compilable
644 on the first try. [#32 by Alan Justino da Silva]
645 · Fixed broken build on Windows.
647 Version 0.6.1
649 Released on November 6, 2014.
650 · Follow up the libsass upstream: 3.0.1 --- See the release note of
652 LibSass.
653 · Fixed a bug that SassMiddleware never closes the socket on some WSGI
655 servers e.g. eventlet.wsgi.
656 Version 0.6.0
658 Released on October 27, 2014.
659 Note that since libsass-python 0.6.0 (and libsass 3.0) it requires
661 C++11 to compile. Although 0.6.2 became back to only need GCC (G++)
662 4.6+, LLVM Clang 2.9+, from 0.6.0 to 0.6.1 you need GCC (G++) 4.8+,
663 LLVM Clang 3.3+, or Visual Studio 2013 Update 4+.
664 · Follow up the libsass upstream: 3.0 --- See the release note of Lib‐
666 Sass.
667 · Decent extends support
669 · Basic Sass Maps Support
671 · Better UTF-8 Support
673 · call() function
675 · Better Windows Support
677 · Spec Enhancements
679 · Added missing partial import support. [#27 by item4]
681 · SOURCE_COMMENTS became deprecated.
683 · sass.compile()'s parameter source_comments now can take only bool
685 instead of str. String values like 'none', 'line_numbers', and 'map'
686 become deprecated, and will be obsolete soon.
687 · build_directory() function has a new optional parameter output_style.
689 · build() method has a new optional parameter output_style.
691 · Added --output-style/-s option to build_sass command. [#25]
693 Version 0.5.1
695 Released on September 23, 2014.
696 · Fixed a bug that SassMiddleware yielded str instead of bytes on
698 Python 3.
699 · Fixed several Unicode-related bugs on Windows.
701 · Fixed a bug that build_directory(), SassMiddleware, and build_sass
703 don't recursively build subdirectories.
704 Version 0.5.0
706 Released on June 6, 2014.
707 · Follow up the libsass upstream: 2.0 --- See the release note of Lib‐
709 Sass.
710 · Added indented syntax support (*.sass files).
712 · Added expanded selector support (BEM).
714 · Added string functions.
716 · Fixed UTF-8 support.
718 · Backward incompatibility: broken extends.
720 Unstable version 0.4.2.20140529.cd3ee1cbe3
722 Released on May 29, 2014.
723 · Version scheme changed to use periods (.) instead of hyphens (-) due
725 to setuptools seems to treat hyphens special.
726 · Fixed malformed packaging that doesn't correctly preserve the package
728 name and version.
729 Unstable Version 0.4.2-20140528-cd3ee1cbe3
731 Released on May 28, 2014.
732 · Follow up the libsass upstream:
734 cd3ee1cbe34d5316eb762a43127a3de9575454ee.
735 Version 0.4.2
737 Released on May 22, 2014.
738 · Fixed build failing on Mac OS X 10.8 or earlier. [#19]
740 · Fixed UnicodeEncodeError that Manifest.build_one() method rises when
742 the input source contains any non-ASCII Unicode characters.
743 Version 0.4.1
745 Released on May 20, 2014.
746 · Fixed UnicodeEncodeError that rise when the input source contains any
748 non-ASCII Unicode characters.
749 Version 0.4.0
751 Released on May 6, 2014.
752 · sassc has a new -w/--watch option.
754 · Expose source maps support:
756 · sassc has a new -m/-g/--sourcemap option.
758 · SassMiddleware now also creates source map files with filenames
760 followed by .map suffix.
761 · Manifest.build_one() method has a new source_map option. This
763 option builds also a source map file with the filename followed by
764 .map suffix.
765 · sass.compile() has a new optional parameter source_comments. It
767 can be one of sass.SOURCE_COMMENTS keys. It also has a new parame‐
768 ter source_map_filename which is required only when source_com‐
769 ments='map'.
770 · Fixed Python 3 incompatibility of sassc program.
772 · Fixed a bug that multiple include_paths doesn't work on Windows.
774 Version 0.3.0
776 Released on February 21, 2014.
777 · Added support for Python 3.3. [#7]
779 · Dropped support for Python 2.5.
781 · Fixed build failing on Mac OS X. [#4, #5, #6 by Hyungoo Kang]
783 · Now builder creates target recursive subdirectories even if it
785 doesn't exist yet, rather than siliently fails. [#8, #9 by Philipp
786 Volguine]
787 · Merged recent changes from libsass 1.0.1: 57a2f62--v1.0.1.
789 · Supports variable arguments.
791 · Supports sourcemaps.
793 Version 0.2.4
795 Released on December 4, 2012.
796 · Added sassc CLI executable script.
798 · Added sass.OUTPUT_STYLES constant map.
800 · Merged recent changes from libsass upstream: e997102--a84b181.
802 Version 0.2.3
804 Released on October 24, 2012.
805 · sassutils.distutils: Prevent double monkey patch of sdist.
807 · Merged upstream changes of libsass.
809 Version 0.2.2
811 Released on September 28, 2012.
812 · Fixed a link error on PyPy and Linux.
814 · Fixed build errors on Windows.
816 Version 0.2.1
818 Released on September 12, 2012.
819 · Support Windows.
821 Version 0.2.0
823 Released on August 24, 2012.
824 · Added new sassutils package.
826 · Added sassutils.builder module to build the whole directory at a
828 time.
829 · Added sassutils.distutils module for distutils and setuptools inte‐
831 gration.
832 · Added sassutils.wsgi module which provides a development-purpose
834 WSGI middleware.
835 · Added build_sass command for distutils/setuptools.
837 Version 0.1.1
839 Released on August 18, 2012.
840 · Fixed segmentation fault for reading filename which does not exist.
842 Now it raises a proper exceptions.IOError exception.
843 Version 0.1.0
845 Released on August 17, 2012. Initial version.
846
848 pysassc --- SassC compliant command line interface
849 This provides SassC compliant CLI executable named pysassc:
850 $ pysassc
852 Usage: pysassc [options] SCSS_FILE [CSS_FILE]
853 There are options as well:
855 -t <style>, --style <style>
857 Coding style of the compiled result. The same as sass.compile()
858 function's output_style keyword argument. Default is nested.
859 -s <style>, --output-style <style>
861 Alias for -t / --style.
862 Deprecated since version 0.11.0.
864 -I <dir>, --include-path <dir>
867 Optional directory path to find @imported (S)CSS files. Can be
868 multiply used.
869 -m, -g, --sourcemap
871 Emit source map. Requires the second argument (output CSS file‐
872 name). The filename of source map will be the output CSS file‐
873 name followed by .map.
874 New in version 0.4.0.
876 -p, --precision
879 Set the precision for numbers. Default is 5.
880 New in version 0.7.0.
882 --source-comments
885 Include debug info in output.
886 New in version 0.11.0.
888 --sourcemap-file
891 Output file for source map
892 New in version 0.17.0.
894 --sourcemap-contents
897 Embed sourcesContent in source map.
898 New in version 0.17.0.
900 --sourcemap-embed
903 Embed sourceMappingUrl as data URI
904 New in version 0.17.0.
906 --omit-sourcemap-url
909 Omit source map URL comment from output
910 New in version 0.17.0.
912 --sourcemap-root
915 Base path, will be emitted to sourceRoot in source-map as is
916 New in version 0.17.0.
918 -v, --version
921 Prints the program version.
922 -h, --help
924 Prints the help message.
925 sass --- Binding of libsass
927 This simple C extension module provides a very simple binding of lib‐
928 sass, which is written in C/C++. It contains only one function and one
929 exception type.
930 >>> import sass
932 >>> sass.compile(string='a { b { color: blue; } }')
933 'a b {
934 color: blue; }
935 '
936 sass.MODES = frozenset({'dirname', 'filename', 'string'})
938 (frozenset) The set of keywords compile() can take.
939 sass.OUTPUT_STYLES = {'compact': 2, 'compressed': 3, 'expanded': 1,
941 'nested': 0}
942 (collections.abc.Mapping) The dictionary of output styles. Keys
943 are output name strings, and values are flag integers.
944 sass.SOURCE_COMMENTS = {'default': 1, 'line_numbers': 1, 'map': 2,
946 'none': 0}
947 (collections.abc.Mapping) The dictionary of source comments
948 styles. Keys are mode names, and values are corresponding flag
949 integers.
950 New in version 0.4.0.
952 Deprecated since version 0.6.0.
955 exception sass.CompileError(msg)
958 The exception type that is raised by compile(). It is a subtype
959 of exceptions.ValueError.
960 class sass.SassColor
962 class sass.SassError
964 class sass.SassFunction(name, arguments, callable_)
966 Custom function for Sass. It can be instantiated using
967 from_lambda() and from_named_function() as well.
968 Parameters
970 · name (str) -- the function name
972 · arguments (collections.abc.Sequence) -- the argument
974 names
975 · callable (collections.abc.Callable) -- the actual func‐
977 tion to be called
978 New in version 0.7.0.
980 classmethod from_lambda(name, lambda_)
983 Make a SassFunction object from the given lambda_ func‐
984 tion. Since lambda functions don't have their name, it
985 need its name as well. Arguments are automatically
986 inspected.
987 Parameters
989 · name (str) -- the function name
991 · lambda (types.LambdaType) -- the actual lambda
993 function to be called
994 Returns
996 a custom function wrapper of the lambda_ function
997 Return type
999 SassFunction
1000 classmethod from_named_function(function)
1002 Make a SassFunction object from the named function.
1003 Function name and arguments are automatically inspected.
1004 Parameters
1006 function (types.FunctionType) -- the named func‐
1007 tion to be called
1008 Returns
1010 a custom function wrapper of the function
1011 Return type
1013 SassFunction
1014 property signature
1016 Signature string of the function.
1017 class sass.SassList
1019 class sass.SassMap(*args, **kwargs)
1021 Because sass maps can have mapping types as keys, we need an
1022 immutable hashable mapping type.
1023 New in version 0.7.0.
1025 class sass.SassNumber
1028 class sass.SassWarning
1030 sass.and_join(strings)
1032 Join the given strings by commas with last ' and ' conjuction.
1033 >>> and_join(['Korea', 'Japan', 'China', 'Taiwan'])
1035 'Korea, Japan, China, and Taiwan'
1036 Parameters
1038 strings -- a list of words to join
1039 Returns
1041 a joined string
1042 Return type
1044 str, basestring
1045 sass.compile(**kwargs)
1047 There are three modes of parameters compile() can take: string,
1048 filename, and dirname.
1049 The string parameter is the most basic way to compile Sass. It
1051 simply takes a string of Sass code, and then returns a compiled
1052 CSS string.
1053 Parameters
1055 · string (str) -- Sass source code to compile. it's
1057 exclusive to filename and dirname parameters
1058 · output_style (str) -- an optional coding style of the
1060 compiled result. choose one of: 'nested' (default),
1061 'expanded', 'compact', 'compressed'
1062 · source_comments (bool) -- whether to add comments about
1064 source lines. False by default
1065 · source_map_contents (bool) -- embed include contents in
1067 map
1068 · source_map_embed (bool) -- embed sourceMappingUrl as
1070 data URI
1071 · omit_source_map_url (bool) -- omit source map URL com‐
1073 ment from output
1074 · source_map_root (str) -- base path, will be emitted in
1076 source map as is
1077 · include_paths (collections.abc.Sequence) -- an optional
1079 list of paths to find @imported Sass/CSS source files
1080 · precision (int) -- optional precision for numbers. 5 by
1082 default.
1083 · custom_functions (set, collections.abc.Sequence, col‐
1085 lections.abc.Mapping) -- optional mapping of custom
1086 functions. see also below custom functions description
1087 · custom_import_extensions -- (ignored, for backward com‐
1089 patibility)
1090 · indented (bool) -- optional declaration that the string
1092 is Sass, not SCSS formatted. False by default
1093 · importers (collections.abc.Callable) -- optional call‐
1095 back functions. see also below importer callbacks
1096 description
1097 Returns
1099 the compiled CSS string
1100 Return type
1102 str
1103 Raises sass.CompileError -- when it fails for any reason (for
1105 example the given Sass has broken syntax)
1106 The filename is the most commonly used way. It takes a string
1108 of Sass filename, and then returns a compiled CSS string.
1109 Parameters
1111 · filename (str) -- the filename of Sass source code to
1113 compile. it's exclusive to string and dirname parame‐
1114 ters
1115 · output_style (str) -- an optional coding style of the
1117 compiled result. choose one of: 'nested' (default),
1118 'expanded', 'compact', 'compressed'
1119 · source_comments (bool) -- whether to add comments about
1121 source lines. False by default
1122 · source_map_filename (str) -- use source maps and indi‐
1124 cate the source map output filename. None means not
1125 using source maps. None by default.
1126 · source_map_contents (bool) -- embed include contents in
1128 map
1129 · source_map_embed (bool) -- embed sourceMappingUrl as
1131 data URI
1132 · omit_source_map_url (bool) -- omit source map URL com‐
1134 ment from output
1135 · source_map_root (str) -- base path, will be emitted in
1137 source map as is
1138 · include_paths (collections.abc.Sequence) -- an optional
1140 list of paths to find @imported Sass/CSS source files
1141 · precision (int) -- optional precision for numbers. 5 by
1143 default.
1144 · custom_functions (set, collections.abc.Sequence, col‐
1146 lections.abc.Mapping) -- optional mapping of custom
1147 functions. see also below custom functions description
1148 · custom_import_extensions -- (ignored, for backward com‐
1150 patibility)
1151 · importers (collections.abc.Callable) -- optional call‐
1153 back functions. see also below importer callbacks
1154 description
1155 Returns
1157 the compiled CSS string, or a pair of the compiled CSS
1158 string and the source map string if source_map_filename
1159 is set
1160 Return type
1162 str, tuple
1163 Raises
1165 · sass.CompileError -- when it fails for any reason (for
1167 example the given Sass has broken syntax)
1168 · exceptions.IOError -- when the filename doesn't exist
1170 or cannot be read
1171 The dirname is useful for automation. It takes a pair of paths.
1173 The first of the dirname pair refers the source directory, con‐
1174 tains several Sass source files to compiled. Sass source files
1175 can be nested in directories. The second of the pair refers the
1176 output directory that compiled CSS files would be saved. Direc‐
1177 tory tree structure of the source directory will be maintained
1178 in the output directory as well. If dirname parameter is used
1179 the function returns None.
1180 Parameters
1182 · dirname (tuple) -- a pair of (source_dir, output_dir).
1184 it's exclusive to string and filename parameters
1185 · output_style (str) -- an optional coding style of the
1187 compiled result. choose one of: 'nested' (default),
1188 'expanded', 'compact', 'compressed'
1189 · source_comments (bool) -- whether to add comments about
1191 source lines. False by default
1192 · source_map_contents (bool) -- embed include contents in
1194 map
1195 · source_map_embed (bool) -- embed sourceMappingUrl as
1197 data URI
1198 · omit_source_map_url (bool) -- omit source map URL com‐
1200 ment from output
1201 · source_map_root (str) -- base path, will be emitted in
1203 source map as is
1204 · include_paths (collections.abc.Sequence) -- an optional
1206 list of paths to find @imported Sass/CSS source files
1207 · precision (int) -- optional precision for numbers. 5 by
1209 default.
1210 · custom_functions (set, collections.abc.Sequence, col‐
1212 lections.abc.Mapping) -- optional mapping of custom
1213 functions. see also below custom functions description
1214 · custom_import_extensions -- (ignored, for backward com‐
1216 patibility)
1217 Raises sass.CompileError -- when it fails for any reason (for
1219 example the given Sass has broken syntax)
1220 The custom_functions parameter can take three types of forms:
1222 set/Sequence of SassFunctions
1224 It is the most general form. Although pretty verbose, it can
1225 take any kind of callables like type objects, unnamed func‐
1226 tions, and user-defined callables.
1227 sass.compile(
1229 ...,
1230 custom_functions={
1231 sass.SassFunction('func-name', ('$a', '$b'), some_callable),
1232 ...
1233 }
1234 )
1235 Mapping of names to functions
1237 Less general, but easier-to-use form. Although it's not
1238 it can take any kind of callables, it can take any kind
1239 of functions defined using def/lambda syntax. It cannot
1240 take callables other than them since inspecting arguments
1241 is not always available for every kind of callables.
1242 sass.compile(
1244 ...,
1245 custom_functions={
1246 'func-name': lambda a, b: ...,
1247 ...
1248 }
1249 )
1250 set/Sequence of named functions
1252 Not general, but the easiest-to-use form for named functions.
1253 It can take only named functions, defined using def. It can‐
1254 not take lambdas sinc names are unavailable for them.
1255 def func_name(a, b):
1257 return ...
1258 sass.compile(
1260 ...,
1261 custom_functions={func_name}
1262 )
1263 Newer versions of libsass allow developers to define callbacks
1265 to be called and given a chance to process @import directives.
1266 You can define yours by passing in a list of callables via the
1267 importers parameter. The callables must be passed as 2-tuples in
1268 the form:
1269 (priority_int, callback_fn)
1271 A priority of zero is acceptable; priority determines the order
1273 callbacks are attempted.
1274 These callbacks can accept one or two string arguments. The
1276 first argument is the path that was passed to the @import direc‐
1277 tive; the second (optional) argument is the previous resolved
1278 path, where the @import directive was found. The callbacks must
1279 either return None to indicate the path wasn't handled by that
1280 callback (to continue with others or fall back on internal lib‐
1281 sass filesystem behaviour) or a list of one or more tuples, each
1282 in one of three forms:
1283 · A 1-tuple representing an alternate path to handle internally;
1285 or,
1286 · A 2-tuple representing an alternate path and the content that
1288 path represents; or,
1289 · A 3-tuple representing the same as the 2-tuple with the addi‐
1291 tion of a "sourcemap".
1292 All tuple return values must be strings. As a not overly realis‐
1294 tic example:
1295 def my_importer(path, prev):
1297 return [(path, '#' + path + ' { color: red; }')]
1298 sass.compile(
1300 ...,
1301 importers=[(0, my_importer)]
1302 )
1303 Now, within the style source, attempting to @import 'button';
1305 will instead attach color: red as a property of an element with
1306 the imported name.
1307 New in version 0.4.0: Added source_comments and source_map_file‐
1309 name parameters.
1310 Changed in version 0.6.0: The source_comments parameter becomes
1313 to take only bool instead of str.
1314 Deprecated since version 0.6.0: Values like 'none', 'line_num‐
1317 bers', and 'map' for the source_comments parameter are depre‐
1318 cated.
1319 New in version 0.7.0: Added precision parameter.
1322 New in version 0.7.0: Added custom_functions parameter.
1325 New in version 0.11.0: source_map_filename no longer implies
1328 source_comments.
1329 New in version 0.17.0: Added source_map_contents,
1332 source_map_embed, omit_source_map_url, and source_map_root
1333 parameters.
1334 New in version 0.18.0: The importer callbacks can now take a
1337 second argument, the previously- resolved path, so that
1338 importers can do relative path resolution.
1339 sassutils --- Additional utilities related to Sass
1342 This package provides several additional utilities related to Sass
1343 which depends on libsass core (sass module).
1344 sassutils.builder --- Build the whole directory
1346 sassutils.builder.SUFFIXES = frozenset({'sass', 'scss'})
1347 (frozenset) The set of supported filename suffixes.
1348 sassutils.builder.SUFFIX_PATTERN = re.compile('[.](sass|scss)$')
1350 (re.RegexObject) The regular expression pattern which matches to
1351 filenames of supported SUFFIXES.
1352 class sassutils.builder.Manifest(sass_path, css_path=None,
1354 wsgi_path=None, strip_extension=None)
1355 Building manifest of Sass/SCSS.
1356 Parameters
1358 · sass_path (str, basestring) -- the path of the direc‐
1360 tory that contains Sass/SCSS source files
1361 · css_path (str, basestring) -- the path of the directory
1363 to store compiled CSS files
1364 · strip_extension (bool) -- whether to remove the origi‐
1366 nal file extension
1367 build(package_dir, output_style='nested')
1369 Builds the Sass/SCSS files in the specified sass_path.
1370 It finds sass_path and locates css_path as relative to
1371 the given package_dir.
1372 Parameters
1374 · package_dir (str, basestring) -- the path of
1376 package directory
1377 · output_style (str) -- an optional coding style
1379 of the compiled result. choose one of: 'nested'
1380 (default), 'expanded', 'compact', 'compressed'
1381 Returns
1383 the set of compiled CSS filenames
1384 Return type
1386 frozenset
1387 New in version 0.6.0: The output_style parameter.
1389 build_one(package_dir, filename, source_map=False)
1392 Builds one Sass/SCSS file.
1393 Parameters
1395 · package_dir (str, basestring) -- the path of
1397 package directory
1398 · filename (str, basestring) -- the filename of
1400 Sass/SCSS source to compile
1401 · source_map (bool) -- whether to use source maps.
1403 if True it also write a source map to a filename
1404 followed by .map suffix. default is False
1405 Returns
1407 the filename of compiled CSS
1408 Return type
1410 str, basestring
1411 New in version 0.4.0: Added optional source_map parame‐
1413 ter.
1414 resolve_filename(package_dir, filename)
1417 Gets a proper full relative path of Sass source and CSS
1418 source that will be generated, according to package_dir
1419 and filename.
1420 Parameters
1422 · package_dir (str, basestring) -- the path of
1424 package directory
1425 · filename (str, basestring) -- the filename of
1427 Sass/SCSS source to compile
1428 Returns
1430 a pair of (sass, css) path
1431 Return type
1433 tuple
1434 unresolve_filename(package_dir, filename)
1436 Retrieves the probable source path from the output file‐
1437 name. Pass in a .css path to get out a .scss path.
1438 Parameters
1440 · package_dir (str) -- the path of the package
1442 directory
1443 · filename (str) -- the css filename
1445 Returns
1447 the scss filename
1448 Return type
1450 str
1451 sassutils.builder.build_directory(sass_path, css_path, out‐
1453 put_style='nested', _root_sass=None, _root_css=None, strip_exten‐
1454 sion=False)
1455 Compiles all Sass/SCSS files in path to CSS.
1456 Parameters
1458 · sass_path (str, basestring) -- the path of the direc‐
1460 tory which contains source files to compile
1461 · css_path (str, basestring) -- the path of the directory
1463 compiled CSS files will go
1464 · output_style (str) -- an optional coding style of the
1466 compiled result. choose one of: 'nested' (default),
1467 'expanded', 'compact', 'compressed'
1468 Returns
1470 a dictionary of source filenames to compiled CSS file‐
1471 names
1472 Return type
1474 collections.abc.Mapping
1475 New in version 0.6.0: The output_style parameter.
1477 sassutils.distutils --- setuptools/distutils integration
1480 This module provides extensions (and some magical monkey-patches,
1481 sorry) of the standard distutils and setuptools (now it's named Dis‐
1482 tribute) for libsass.
1483 To use this, add libsass into setup_requires (not install_requires)
1485 option of the setup.py script:
1486 from setuptools import setup
1488 setup(
1490 # ...,
1491 setup_requires=['libsass >= 0.6.0']
1492 )
1493 It will adds build_sass command to the setup.py script:
1495 $ python setup.py build_sass
1497 This commands builds Sass/SCSS files to compiled CSS files of the
1499 project and makes the package archive (made by sdist, bdist, and so on)
1500 to include these compiled CSS files.
1501 To set the directory of Sass/SCSS source files and the directory to
1503 store compiled CSS files, specify sass_manifests option:
1504 from setuptools import find_packages, setup
1506 setup(
1508 name='YourPackage',
1509 packages=find_packages(),
1510 sass_manifests={
1511 'your.webapp': ('static/sass', 'static/css')
1512 },
1513 setup_requires=['libsass >= 0.6.0']
1514 )
1515 The option should be a mapping of package names to pairs of paths,
1517 e.g.:
1518 {
1520 'package': ('static/sass', 'static/css'),
1521 'package.name': ('static/scss', 'static')
1522 }
1523 The option can also be a mapping of package names to manifest dictio‐
1525 naries:
1526 {
1528 'package': {
1529 'sass_path': 'static/sass',
1530 'css_path': 'static/css',
1531 'strip_extension': True,
1532 },
1533 }
1534 New in version 0.15.0: Added strip_extension so a.scss is compiled to
1536 a.css instead of a.scss.css. This option will default to True in the
1537 future.
1538 New in version 0.6.0: Added --output-style/-s option to build_sass com‐
1541 mand.
1542 class sassutils.distutils.build_sass(dist, **kw)
1545 Builds Sass/SCSS files to CSS files.
1546 finalize_options()
1548 Set final values for all the options that this command
1549 supports. This is always called as late as possible, ie.
1550 after any option assignments from the command-line or
1551 from other commands have been done. Thus, this is the
1552 place to code option dependencies: if 'foo' depends on
1553 'bar', then it is safe to set 'foo' from 'bar' as long as
1554 'foo' still has the same value it was assigned in 'ini‐
1555 tialize_options()'.
1556 This method must be implemented by all command classes.
1558 get_package_dir(package)
1560 Returns the directory, relative to the top of the source
1561 distribution, where package package should be found (at
1562 least according to the package_dir option, if any).
1563 Copied from distutils.command.build_py.get_package_dir()
1565 method.
1566 initialize_options()
1568 Set default values for all the options that this command
1569 supports. Note that these defaults may be overridden by
1570 other commands, by the setup script, by config files, or
1571 by the command-line. Thus, this is not the place to code
1572 dependencies between options; generally, 'initial‐
1573 ize_options()' implementations are just a bunch of
1574 "self.foo = None" assignments.
1575 This method must be implemented by all command classes.
1577 run() A command's raison d'etre: carry out the action it exists
1579 to perform, controlled by the options initialized in
1580 'initialize_options()', customized by other commands, the
1581 setup script, the command-line, and config files, and
1582 finalized in 'finalize_options()'. All terminal output
1583 and filesystem interaction should be done by 'run()'.
1584 This method must be implemented by all command classes.
1586 sassutils.distutils.validate_manifests(dist, attr, value)
1588 Verifies that value is an expected mapping of package to sassu‐
1589 tils.builder.Manifest.
1590 sassutils.wsgi --- WSGI middleware for development purpose
1592 class sassutils.wsgi.SassMiddleware(app, manifests, package_dir={},
1593 error_status='200 OK')
1594 WSGI middleware for development purpose. Everytime a CSS file
1595 has requested it finds a matched Sass/SCSS source file and then
1596 compiled it into CSS.
1597 It shows syntax errors in three ways:
1599 Heading comment
1601 The result CSS includes detailed error message in the
1602 heading CSS comment e.g.:
1603 /*
1605 Error: invalid property name
1606 */
1607 Red text in body:before
1609 The result CSS draws detailed error message in :before
1610 pseudo-class of body element e.g.:
1611 body:before {
1613 content: 'Error: invalid property name';
1614 color: maroon;
1615 background-color: white;
1616 }
1617 In most cases you could be aware of syntax error by
1619 refreshing your working document because it will removes
1620 all other styles and leaves only a red text.
1621 logging
1623 It logs syntax errors if exist during compilation to sas‐
1624 sutils.wsgi.SassMiddleware logger with level ERROR.
1625 To enable this:
1627 from logging import Formatter, StreamHandler, getLogger
1629 logger = getLogger('sassutils.wsgi.SassMiddleware')
1630 handler = StreamHandler(level=logging.ERROR)
1631 formatter = Formatter(fmt='*' * 80 + '\n%(message)s\n' + '*' * 80)
1632 handler.setFormatter(formatter)
1633 logger.addHandler(handler)
1634 Or simply:
1636 import logging
1638 logging.basicConfig()
1639 Parameters
1641 · app (collections.abc.Callable) -- the WSGI application
1643 to wrap
1644 · manifests (collections.abc.Mapping) -- build settings.
1646 the same format to setup.py script's sass_manifests
1647 option
1648 · package_dir (collections.abc.Mapping) -- optional map‐
1650 ping of package names to directories. the same format
1651 to setup.py script's package_dir option
1652 Changed in version 0.4.0: It creates also source map files with
1654 filenames followed by .map suffix.
1655 New in version 0.8.0: It logs syntax errors if exist during com‐
1658 pilation to sassutils.wsgi.SassMiddleware logger with level
1659 ERROR.
1660 static quote_css_string(s)
1663 Quotes a string as CSS string literal.
1664
1666 Hong Minhee wrote this Python binding of LibSass.
1667 Hampton Catlin and Aaron Leung wrote LibSass, which is portable C/C++
1669 implementation of Sass.
1670 Hampton Catlin originally designed Sass language and wrote the first
1672 reference implementation of it in Ruby.
1673 The above three softwares are all distributed under MIT license.
1675
1677 GitHub (Git repository + issues)
1678 https://github.com/sass/libsass-python
1679 Travis CI
1681 https://travis-ci.org/sass/libsass-python Build Status.TP
1682 AppVeyor (CI for Windows)
1683 https://ci.appveyor.com/project/asottile/libsass-python Build
1684 Status (Windows).TP Coveralls (Test coverage)
1685 https://coveralls.io/r/sass/libsass-python Coverage Status.TP
1686 PyPI https://pypi.org/pypi/libsass/ PyPI.TP Changelog changes
1687
1689 · genindex
1690 · modindex
1692 · search
1694
1696 Hong Minhee
1697
1699 2019, Hong Minhee
17000.18.0 Jul 26, 2019 PYSASSC(1)