1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
Python API
==========
Compiling files
---------------
Very basic usage is simple enough::
from scss import Scss
css = Scss()
css.compile("a { color: red + green; }")
Configuration
-------------
There are several configuration variables in the ``scss.config`` module that
you may wish to change.
``PROJECT_ROOT``: Root of your entire project. Used only to construct defaults
for other variables. Defaults to the root of the pyScss installation, which is
probably not what you want.
``LOAD_PATHS``: An iterable of paths to search when using``@import``.
``STATIC_ROOT``: Used for finding sprite files. Defaults to
``$PROJECT_ROOT/static``.
``ASSETS_ROOT``: Generated sprites are saved here. Defaults to
``$STATIC_ROOT/assets``.
``CACHE_ROOT``: Used for storing cached sprite information. Defaults to
``ASSETS_ROOT``.
``STATIC_URL``: URL equivalent to ``STATIC_ROOT``. Defaults to ``static/``.
``ASSETS_URL``: URL equivalent to ``ASSETS_ROOT``. Defaults to ``static/assets/``.
``SPRTE_MAP_DIRECTION``: Direction in which to arrange sprites in a
spritesheet. Defaults to ``vertical``; may be changed to ``horizontal``,
``diagonal``, or ``smart``.
``VERBOSITY``: Increase spew from the compiler. Defaults to ``1``.
``DEBUG``: Set to true to make parse errors fatal. Defaults to false.
.. warning::
Configuration via monkeypatching is fraught with issues. If you don't need
the Compass sprite functionality, stick with passing ``search_paths`` to
the ``Scss`` constructor, and don't touch these variables at all.
The current plan is to introduce a new mechanism for Compass configuration
in 1.3 with deprecation warnings, and remove ``scss.config`` entirely in
2.0.
Django example
--------------
A rough example of using pyScss with Django::
import os
import fnmatch
import scss
from django.conf import settings
from django.utils.datastructures import SortedDict
from django.contrib.staticfiles import finders
def finder(glob):
"""
Finds all files in the django finders for a given glob,
returns the file path, if available, and the django storage object.
storage objects must implement the File storage API:
https://docs.djangoproject.com/en/dev/ref/files/storage/
"""
for finder in finders.get_finders():
for path, storage in finder.list([]):
if fnmatch.fnmatchcase(path, glob):
yield path, storage
# STATIC_ROOT is where pyScss looks for images and static data.
# STATIC_ROOT can be either a fully qualified path name or a "finder"
# iterable function that receives a filename or glob and returns a tuple
# of the file found and its file storage object for each matching file.
# (https://docs.djangoproject.com/en/dev/ref/files/storage/)
scss.config.STATIC_ROOT = finder
scss.config.STATIC_URL = settings.STATIC_URL
# ASSETS_ROOT is where the pyScss outputs the generated files such as spritemaps
# and compile cache:
scss.config.ASSETS_ROOT = os.path.join(settings.MEDIA_ROOT, 'assets/')
scss.config.ASSETS_URL = settings.MEDIA_URL + 'assets/'
# These are the paths pyScss will look ".scss" files on. This can be the path to
# the compass framework or blueprint or compass-recepies, etc.
scss.config.LOAD_PATHS = [
'/usr/local/www/sass/frameworks/',
'/Library/Ruby/Gems/1.8/gems/compass-0.11.5/frameworks/compass/stylesheets/',
'/Library/Ruby/Gems/1.8/gems/compass-0.11.5/frameworks/blueprint/stylesheets/',
]
# This creates the Scss object used to compile SCSS code. In this example,
# _scss_vars will hold the context variables:
_scss_vars = {}
_scss = scss.Scss(
scss_vars=_scss_vars,
scss_opts={
'compress': True,
'debug_info': True,
}
)
# 1. Compile from a string:
compiled_css_from_string = _scss.compile('@import "file2"; a {color: red + green; }')
# 2. Compile from a file:
compiled_css_from_file = _scss.compile(scss_file='file1.scss')
# 3. Compile from a set of files (use SortedDict or collections.OrderedDict to
# maintain the compile order):
_scss._scss_files = SortedDict((
('file2.scss', open('file2.scss').read()),
('file3.scss', open('file3.scss').read()),
('file4.scss', open('file4.scss').read()),
))
compiled_css_from_files = _scss.compile()
.. note::
The API here is likely to be improved in 1.3, to avoid the need for calling
underscored functions.
Extending pyScss
----------------
There is some support for adding custom functions from Python, but the API is
explicitly undocumented and subject to change. Watch this space.
.. todo::
Document the extension API once it's final.
|
