← Back to branch summary

~corey.bryant/ubuntu/wily/python-pyscss/thedac

« back to all changes in this revision

Viewing changes to README.rst

  • Committer: Package Import Robot
  • Author(s): Thomas Goirand
  • Date: 2014-06-26 12:10:36 UTC
  • mfrom: (1.1.1)
  • Revision ID: package-import@ubuntu.com-20140626121036-3dv13zn5zptk9fpx
Tags: 1.2.0.post3-1
http://bugs.debian.org/738776
* Team upload.
* New upstream release (Closes: #738776).
* Added a debian/gbp.conf.
* Added missing ${python:Depends}
* Added Python 3 support.
* Removed duplicate debhelper build-depends.
* Cannonical VCS URLs.
* Standards-Version: is now 3.9.5.
* Added a watch file.
* override dh helpers which the package doesn't use.

Show diffs side-by-side

added added

removed removed

Lines of Context:
README.rst
1
1
pyScss, a Scss compiler for Python
2
2
==================================
3
 
:Author:
4
 
        German M. Bravo (Kronuz) <german.mb@gmail.com>
5
 
 
6
 
About
7
 
=====
8
 
pyScss compiles Scss (Sass), a superset of CSS that is more powerful, elegant
9
 
and easier to maintain than plain-vanilla CSS. The library acts as a CSS source
10
 
code preprocesor which allows you to use variables, nested rules, mixins, and
11
 
have inheritance of rules, all with a CSS-compatible syntax which the
12
 
preprocessor then compiles to standard CSS.
13
 
 
14
 
Scss, as an extension of CSS, helps keep large stylesheets well-organized. It
15
 
borrows concepts and functionality from projects such as OOCSS and other similar
16
 
frameworks like as Sass. It's build on top of the original PHP xCSS codebase
17
 
structure but it's been completely rewritten, many bugs have been fixed and it
18
 
has been extensively extended to support almost the full range of Sass' Scss
19
 
syntax and functionality.
20
 
 
21
 
.. image:: http://pledgie.com/campaigns/16513.png?skin_name=chrome
22
 
   :alt: Click here to lend your support to pyScss and make a donation at pledgie.com!
23
 
   :target: http://pledgie.com/campaigns/16513
24
 
 
25
 
Support
26
 
========
27
 
pyScss is fully compatible with SCSS (Sass) 3.2 ...it has:
28
 
 
29
 
        * **Compass**: Compass 0.11 Support
30
 
        * **Nested rules**
31
 
        * **Keyword arguments**
32
 
        * **Mixins**: `@mixin`, `@include`
33
 
        * **Functions**: `@function`, `@return`
34
 
        * **Inheritance**: `@extend`
35
 
        * **Conditions**: `@if`, `@else if`, `@else`
36
 
        * **Loops**: `@for`, `@each`
37
 
        * **Variables**: `$`, `@variables`, `@vars`
38
 
        * **Sprites**: `sprite-map()`, `sprite()`, `sprite-position()`, `sprite-url()`, ...
39
 
        * **Images**: `image-url()`, `image-width()`, `image-height()`, ...
40
 
        * **Embedded (inline) images**: `inline-image()`
41
 
        * **Colors handling**: `adjust-color()`, `scale-color()`, `opacify()`/`transparentize()`, `lighten()`/`darken()`, `mix()`, ...
42
 
        * **Math functions**: `sin()`, `cos()`, `tan()`, `round()`, `ceil()`, `floor()`, `pi()`, ...
43
 
        * **CSS Compression**: `@option compress:yes;`
44
 
 
45
 
Requirements
46
 
============
47
 
        * python >= 2.5
48
 
 
49
 
Installation
50
 
============
51
 
pyScss should be installed using pip or setuptools::
52
 
 
53
 
        pip install pyScss
54
 
 
55
 
        easy_install pyScss
56
 
 
57
 
Usage
58
 
=====
59
 
Usage example::
60
 
 
61
 
        from scss import Scss
62
 
        css = Scss()
63
 
        css.compile("a { color: red + green; }")
64
 
 
65
 
Or compile from the command line::
66
 
 
67
 
        python -mscss < file.scss
68
 
 
69
 
Interactive mode::
70
 
 
71
 
        python -mscss --interactive
72
 
 
73
 
.. note::
74
 
 
75
 
    ``-mscss`` will only work in Python 2.7 and above, for Python 2.5
76
 
    and 2.6 you need to invoke::
77
 
 
78
 
        python -mscss.tool
79
 
 
80
 
Examples
81
 
========
82
 
#. **Nested Rules**
83
 
        Example::
84
 
 
85
 
                @option compress: no;
86
 
                .selector {
87
 
                    a {
88
 
                        display: block;
89
 
                    }
90
 
                        strong {
91
 
                        color: blue;
92
 
                    }
93
 
                }
94
 
 
95
 
        ...produces::
96
 
 
97
 
                .selector a {
98
 
                    display: block;
99
 
                }
100
 
                .selector strong {
101
 
                    color: #00f;
102
 
                }
103
 
 
104
 
#. **Variables**
105
 
        Example::
106
 
 
107
 
                @option compress: no;
108
 
                $main-color: #ce4dd6;
109
 
                $style: solid;
110
 
                $side: bottom;
111
 
                #navbar {
112
 
                    border-#{$side}: {
113
 
                        color: $main-color;
114
 
                        style: $style;
115
 
                    }
116
 
                }
117
 
 
118
 
        ...produces::
119
 
 
120
 
                #navbar {
121
 
                    border-bottom-color: #ce4dd6;
122
 
                    border-bottom-style: solid;
123
 
                }
124
 
 
125
 
#. **Mixins**
126
 
        Example::
127
 
 
128
 
                @option compress: no;
129
 
                @mixin rounded($side, $radius: 10px) {
130
 
                    border-#{$side}-radius: $radius;
131
 
                    -moz-border-radius-#{$side}: $radius;
132
 
                    -webkit-border-#{$side}-radius: $radius;
133
 
                }
134
 
                #navbar li { @include rounded(top); }
135
 
                #footer { @include rounded(top, 5px); }
136
 
                #sidebar { @include rounded(left, 8px); }
137
 
 
138
 
        ...produces::
139
 
 
140
 
                #navbar li {
141
 
                    border-top-radius: 10px;
142
 
                    -moz-border-radius-top: 10px;
143
 
                    -webkit-border-top-radius: 10px;
144
 
                }
145
 
                #footer {
146
 
                    border-top-radius: 5px;
147
 
                    -moz-border-radius-top: 5px;
148
 
                    -webkit-border-top-radius: 5px;
149
 
                }
150
 
                #sidebar {
151
 
                    border-left-radius: 8px;
152
 
                    -moz-border-radius-left: 8px;
153
 
                    -webkit-border-left-radius: 8px;
154
 
                }
155
 
 
156
 
#. **Extend** (using `@extend`)
157
 
        Example::
158
 
 
159
 
                @option compress: no;
160
 
                .error {
161
 
                    border: 1px #f00;
162
 
                    background-color: #fdd;
163
 
                }
164
 
                .error.intrusion {
165
 
                    background-image: url("/image/hacked.png");
166
 
                }
167
 
                .seriousError {
168
 
                    @extend .error;
169
 
                    border-width: 3px;
170
 
                }
171
 
 
172
 
        ...produces::
173
 
 
174
 
                .error,
175
 
                .seriousError {
176
 
                    border: 1px red;
177
 
                    background-color: #fdd;
178
 
                }
179
 
                .error.intrusion,
180
 
                .seriousError.intrusion {
181
 
                    background-image: url("/image/hacked.png");
182
 
                }
183
 
                .seriousError {
184
 
                    border-width: 3px;
185
 
                }
186
 
 
187
 
#. **Sprites** (using `sprite-map()`)
188
 
        Example::
189
 
 
190
 
                @option compress: no;
191
 
                $icons: sprite-map("sociable/*.png"); // contains sociable/facebook.png among others.
192
 
                div {
193
 
                    background: $icons;
194
 
                }
195
 
                @each $icon in sprites($icons) {
196
 
                    div .#{$icon} {
197
 
                        width: image-width(sprite-file($icons, $icon));
198
 
                        height: image-height(sprite-file($icons, $icon));
199
 
                        background-position: sprite-position($icons, $icon);
200
 
                    }
201
 
                }
202
 
 
203
 
        ...generates a new sprite file and produces something like::
204
 
 
205
 
                div {
206
 
                    background: url("/static/assets/u8Y7yEQL0UffAVw5rX7yhw.png?_=1298240989") 0px 0px no-repeat;
207
 
                }
208
 
                div .facebook {
209
 
                    width: 32px;
210
 
                    height: 32px;
211
 
                    background-position: 0px 0px;
212
 
                }
213
 
                div .twitter {
214
 
                    width: 32px;
215
 
                    height: 32px;
216
 
                    background-position: 0px -32px;
217
 
                }
218
 
                ...
219
 
 
220
 
#. **Interactive mode**
221
 
        Example::
222
 
 
223
 
                $ python scss.py --interactive
224
 
                >>> @import "compass/css3"
225
 
                >>> show()
226
 
                ['functions', 'mixins', 'options', 'vars']
227
 
                >>> show(mixins)
228
 
                ['apply-origin',
229
 
                 'apply-transform',
230
 
                 ...
231
 
                 'transparent']
232
 
                >>> show(mixins, transparent)
233
 
                @mixin transparent() {
234
 
                    @include opacity(0);
235
 
                }
236
 
                >>> 1px + 5px
237
 
                6px
238
 
                >>> _
239
 
 
240
 
Sass Sassy CSS
241
 
==============
242
 
pyScss is a Scss (Sass) implementation for Python.
243
 
Currently it implements @mixin, @include, @if, @else, @for, and @import... it
244
 
also implements many of the Sass functions including color functions like
245
 
hsla(), hsl(), darken(), lighten(), mix(), opacify(), transparentize(),
246
 
saturate(), desaturate(), etc.) as well as sprite-map(), sprite-file(),
247
 
image-width(), image-height() and the others.
248
 
 
249
 
In the file `scss.py`, by the top, you can configure the LOAD_PATHS to point to
250
 
your Sass frameworks path (I have `sass/frameworks/compass/*.scss` and
251
 
`sass/framework/blueprint/*.scss` files in my project directory:
252
 
`/usr/local/www/project/`, where `scss.py` lives, so it defaults to use the
253
 
`sass/framework/` path, relative to the `scss.py` file) or configure using the
254
 
command line `--load-path` option, see `python scss.py --help`.
255
 
 
256
 
I have succesfully compiled some Compass using `python scss.py < myfile.css` the
257
 
following `myfile.css`::
258
 
 
259
 
        @option compress: no;
260
 
 
261
 
        $blueprint-grid-columns : 24;
262
 
        $blueprint-grid-width   : 30px;
263
 
        $blueprint-grid-margin  : 10px;
264
 
        $font-color             : #333;
265
 
 
266
 
        @import "compass/reset";
267
 
        @import "compass/utilities";
268
 
        @import "blueprint";
269
 
 
270
 
        // Stuff goes here...
271
 
 
272
 
Django Example
273
 
==============
274
 
The following shows some code that can be used with django::
275
 
 
276
 
        import os
277
 
        import fnmatch
278
 
        
279
 
        import scss
280
 
        
281
 
        from django.conf import settings
282
 
        from django.utils.datastructures import SortedDict
283
 
        from django.contrib.staticfiles import finders
284
 
        
285
 
        
286
 
        def finder(glob):
287
 
            """
288
 
            Finds all files in the django finders for a given glob,
289
 
            returns the file path, if available, and the django storage object.
290
 
            storage objects must implement the File storage API:
291
 
            https://docs.djangoproject.com/en/dev/ref/files/storage/
292
 
            """
293
 
            for finder in finders.get_finders():
294
 
                for path, storage in finder.list([]):
295
 
                    if fnmatch.fnmatchcase(path, glob):
296
 
                        yield path, storage
297
 
        
298
 
        
299
 
        # STATIC_ROOT is where pyScss looks for images and static data.
300
 
        # STATIC_ROOT can be either a fully qualified path name or a "finder"
301
 
        # iterable function that receives a filename or glob and returns a tuple
302
 
        # of the file found and its file storage object for each matching file.
303
 
        # (https://docs.djangoproject.com/en/dev/ref/files/storage/)
304
 
        scss.STATIC_ROOT = finder
305
 
        scss.STATIC_URL = settings.STATIC_URL
306
 
        
307
 
        # ASSETS_ROOT is where the pyScss outputs the generated files such as spritemaps
308
 
        # and compile cache:
309
 
        scss.ASSETS_ROOT = os.path.join(settings.MEDIA_ROOT, 'assets/')
310
 
        scss.ASSETS_URL = settings.MEDIA_URL + 'assets/'
311
 
        
312
 
        # These are the paths pyScss will look ".scss" files on. This can be the path to
313
 
        # the compass framework or blueprint or compass-recepies, etc.
314
 
        scss.LOAD_PATHS = [
315
 
            '/usr/local/www/sass/frameworks/',
316
 
            '/Library/Ruby/Gems/1.8/gems/compass-0.11.5/frameworks/compass/stylesheets/',
317
 
            '/Library/Ruby/Gems/1.8/gems/compass-0.11.5/frameworks/blueprint/stylesheets/',
318
 
        ]
319
 
        
320
 
        # This creates the Scss object used to compile SCSS code. In this example,
321
 
        # _scss_vars will hold the context variables:
322
 
        _scss_vars = {}
323
 
        _scss = scss.Scss(
324
 
            scss_vars=_scss_vars,
325
 
            scss_opts={
326
 
                'compress': True,
327
 
                'debug_info': True,
328
 
            }
329
 
        )
330
 
        
331
 
        # 1. Compile from a string:
332
 
        compiled_css_from_string = _scss.compile('@import "file2"; a {color: red + green; }')
333
 
        
334
 
        # 2. Compile from a file:
335
 
        compiled_css_from_file = _scss.compile(scss_file='file1.scss')
336
 
        
337
 
        # 3. Compile from a set of files (use SortedDict or collections.OrderedDict to
338
 
        # maintain the compile order):
339
 
        _scss._scss_files = SortedDict((
340
 
            ('file2.scss', open('file2.scss').read()),
341
 
            ('file3.scss', open('file3.scss').read()),
342
 
            ('file4.scss', open('file4.scss').read()),
343
 
        ))
344
 
        compiled_css_from_files = _scss.compile()
345
 
 
346
 
 
347
 
Bug tracker
348
 
===========
349
 
If you have any suggestions, bug reports or annoyances please report them to the
350
 
issue tracker at http://github.com/Kronuz/pyScss/issues
351
 
 
352
 
 
353
 
Changelog
354
 
=========
355
 
 
356
 
1.1.5 Feb 15, 2013
357
 
        + ``debug_info`` now properly produces rules that can be used by FireSass and Google Chrome SASS Source Maps.
358
 
        + Improved memory usage for large sets of files to be used as sprites.
359
 
        + Warns about IE 4095 maximum number of selectors.
360
 
        + ``debug_info`` prints info as comments if specified as ``comments``.
361
 
        + Better handling of undefined variables.
362
 
        + Added CSS filter functions and ``skewX`` ``skewY``.
363
 
        + Command line tool and entry point fixed.
364
 
        + Fix cache buster URLs when paths already include queries or fragments.
365
 
        + Hashable Values.
366
 
 
367
 
1.1.4 Aug 8, 2012
368
 
        + Added ``--debug-info`` command line option (for *FireSass* output).
369
 
        + Added compass helper function ``reject()``.
370
 
        + Added ``undefined`` keyword for undefined variables.
371
 
 
372
 
1.1.3 Jan 9, 2012
373
 
        + Support for the new Sass 3.2.0 features (``@content`` and placeholder selectors)
374
 
        + Fixed bug with line numbers throwing an exception.
375
 
 
376
 
1.1.2 Jan 3, 2012
377
 
        + Regression bug fixed from 1.1.1
378
 
 
379
 
1.1.1 Jan 2, 2012
380
 
        + Added optional C speedup module for an amazing boost in scanning speed!
381
 
        + Added ``headings``, ``stylesheet-url``, ``font-url``, ``font-files``, ``inline-font-files`` and ``sprite-names``.
382
 
 
383
 
1.1.0 - Dec 22, 2011
384
 
        + Added ``min()`` and ``max()`` for lists.
385
 
        + Removed exception raise.
386
 
 
387
 
1.0.9 - Dec 22, 2011
388
 
        + Optimizations in the scanner.
389
 
        + Added ``background-noise()`` for compass-recipes support.
390
 
        + ``enumerate()`` and ``range()`` can go backwards. Ex.: ``range(3, 0)`` goes from 3 to 0.
391
 
        + Added line numbers and files for errors.
392
 
        + Added support for *Firebug* with *FireSass*.
393
 
        + ``nth(n)`` is round (returns the ``nth mod len`` item of the list).
394
 
        + ``--watch`` added to the command line.
395
 
        + Several bugs fixed.
396
 
 
397
 
1.0.8 - May 13, 2011
398
 
    + Changed source color (``$src-color``) default to black.
399
 
    + Moved the module filename to ``__init__.py`` and module renamed back to scss.
400
 
 
401
 
 
402
 
Contributing
403
 
============
404
 
Development of pyScss happens at github: https://github.com/Kronuz/pyScss
405
 
 
406
 
 
407
 
License
408
 
=======
409
 
MIT License. See *LICENSE* for details.
410
 
http://www.opensource.org/licenses/mit-license.php
411
 
 
412
 
 
413
 
Copyright
414
 
=========
415
 
Copyright (c) 2012 German M. Bravo (Kronuz)
416
 
*Bits of code in pyScss come from various projects:*
417
 
 
418
 
Compass:
419
 
        (c) 2009 Christopher M. Eppstein
420
 
        http://compass-style.org/
421
 
Sass:
422
 
        (c) 2006-2009 Hampton Catlin and Nathan Weizenbaum
423
 
        http://sass-lang.com/
424
 
xCSS:
425
 
        (c) 2010 Anton Pawlik
426
 
        http://xcss.antpaw.org/docs/
 
3
 
 
4
pyScss is a compiler for SCSS flavor of the Sass language, a superset of CSS3
 
5
that adds programming capabilities and some other syntactic sugar.
 
6
 
 
7
Quickstart
 
8
----------
 
9
 
 
10
You need Python 2.6 or later.  Python 3 is also supported.
 
11
 
 
12
Installation::
 
13
 
 
14
    pip install pyScss
 
15
 
 
16
Usage::
 
17
 
 
18
    python -mscss < style.scss
 
19
 
 
20
Python API::
 
21
 
 
22
    from scss import Scss
 
23
    compiler = Scss()
 
24
    compiler.compile("a { color: red + green; }")
 
25
 
 
26
 
 
27
Features
 
28
--------
 
29
 
 
30
95% of Sass 3.2 is supported.  If it's not supported, it's a bug!  Please file
 
31
a ticket.
 
32
 
 
33
Most of Compass 0.11 is also built in.
 
34
 
 
35
 
 
36
Further reading
 
37
---------------
 
38
 
 
39
Documentation is in Sphinx.  You can build it yourself by running ``make html``
 
40
from within the ``docs`` directory, or read it on RTD:
 
41
http://pyscss.readthedocs.org/en/latest/
 
42
 
 
43
The canonical syntax reference is part of the Ruby Sass documentation:
 
44
http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html
 
45
 
 
46
 
 
47
Obligatory
 
48
----------
 
49
 
 
50
Copyright © 2012 German M. Bravo (Kronuz).  Additional credits in the
 
51
documentation.
 
52
 
 
53
Licensed under the `MIT license`_, reproduced in ``LICENSE``.
 
54
 
 
55
.. _MIT license: http://www.opensource.org/licenses/mit-license.php