compile() has new params: source_comments, source_map_filename

Author: dahlia

docs/changes.rst

@@ -6,6 +6,13 @@ Version 0.4.0
 
 To be released.
 
+- Expose source maps support:
+
+  - :func:`sass.compile()` has a new optional parameter ``source_comments``.
+    It can be one of :const:`sass.SOURCE_COMMENTS` keys.  It also has
+    a new parameter ``source_map_filename`` which is required only when
+    ``source_comments='map'``.
+
 - Fixed Python 3 incompatibility of :program:`sassc` program.
 
 

pysass.c

@@ -1,43 +1,62 @@
 #include <unistd.h>
+#include <stdlib.h>
+#include <string.h>
 #include <Python.h>
 #include "sass_interface.h"
 
 #if PY_MAJOR_VERSION >= 3
 #define PySass_IF_PY3(three, two) (three)
 #define PySass_Int_FromLong(v) PyLong_FromLong(v)
+#define PySass_Bytes_Check(o) PyBytes_Check(o)
+#define PySass_Bytes_GET_SIZE(o) PyBytes_GET_SIZE(o)
+#define PySass_Bytes_AS_STRING(o) PyBytes_AS_STRING(o)
 #else
 #define PySass_IF_PY3(three, two) (two)
 #define PySass_Int_FromLong(v) PyInt_FromLong(v)
+#define PySass_Bytes_Check(o) PyString_Check(o)
+#define PySass_Bytes_GET_SIZE(o) PyString_GET_SIZE(o)
+#define PySass_Bytes_AS_STRING(o) PyString_AS_STRING(o)
 #endif
 
-static struct {
+struct PySass_Pair {
     char *label;
     int value;
-} PySass_output_style_enum[] = {
+};
+
+static struct PySass_Pair PySass_output_style_enum[] = {
     {"nested", SASS_STYLE_NESTED},
     {"expanded", SASS_STYLE_EXPANDED},
     {"compact", SASS_STYLE_COMPACT},
     {"compressed", SASS_STYLE_COMPRESSED},
     {NULL}
 };
 
+static struct PySass_Pair PySass_source_comments_enum[] = {
+    {"none", SASS_SOURCE_COMMENTS_NONE},
+    {"line_numbers", SASS_SOURCE_COMMENTS_DEFAULT},  /* alias of "default" */
+    {"default", SASS_SOURCE_COMMENTS_DEFAULT},
+    {"map", SASS_SOURCE_COMMENTS_MAP},
+    {NULL}
+};
+
 static PyObject *
 PySass_compile_string(PyObject *self, PyObject *args) {
     struct sass_context *context;
     char *string, *include_paths, *image_path;
-    int output_style;
+    int output_style, source_comments;
     PyObject *result;
 
     if (!PyArg_ParseTuple(args,
-                          PySass_IF_PY3("yiyy", "siss"),
-                          &string, &output_style,
+                          PySass_IF_PY3("yiiyy", "siiss"),
+                          &string, &output_style, &source_comments,
                           &include_paths, &image_path)) {
         return NULL;
     }
 
     context = sass_new_context();
     context->source_string = string;
     context->options.output_style = output_style;
+    context->options.source_comments = source_comments;
     context->options.include_paths = include_paths;
     context->options.image_path = image_path;
 
@@ -56,28 +75,46 @@ static PyObject *
 PySass_compile_filename(PyObject *self, PyObject *args) {
     struct sass_file_context *context;
     char *filename, *include_paths, *image_path;
-    int output_style;
-    PyObject *result;
+    int output_style, source_comments, error_status;
+    PyObject *source_map_filename, *result;
 
     if (!PyArg_ParseTuple(args,
-                          PySass_IF_PY3("yiyy", "siss"),
-                          &filename, &output_style,
-                          &include_paths, &image_path)) {
+                          PySass_IF_PY3("yiiyyO", "siissO"),
+                          &filename, &output_style, &source_comments,
+                          &include_paths, &image_path, &source_map_filename)) {
         return NULL;
     }
 
     context = sass_new_file_context();
     context->input_path = filename;
+    if (source_comments == SASS_SOURCE_COMMENTS_MAP &&
+        PySass_Bytes_Check(source_map_filename)) {
+        size_t source_map_file_len = PySass_Bytes_GET_SIZE(source_map_filename);
+        if (source_map_file_len) {
+            char *source_map_file = malloc(source_map_file_len + 1);
+            strncpy(
+                source_map_file, 
+                PySass_Bytes_AS_STRING(source_map_filename),
+                source_map_file_len + 1
+            );
+            context->source_map_file = source_map_file;
+        }
+    }
     context->options.output_style = output_style;
+    context->options.source_comments = source_comments;
     context->options.include_paths = include_paths;
     context->options.image_path = image_path;
 
     sass_compile_file(context);
 
+    error_status = context->error_status;
     result = Py_BuildValue(
-        PySass_IF_PY3("hy", "hs"),
+        PySass_IF_PY3("hyy", "hss"),
         (short int) !context->error_status,
-        context->error_status ? context->error_message : context->output_string
+        error_status ? context->error_message : context->output_string,
+        error_status || context->source_map_string == NULL
+            ? ""
+            : context->source_map_string
     );
     sass_free_file_context(context);
     return result;
@@ -87,12 +124,13 @@ static PyObject *
 PySass_compile_dirname(PyObject *self, PyObject *args) {
     struct sass_folder_context *context;
     char *search_path, *output_path, *include_paths, *image_path;
-    int output_style;
+    int output_style, source_comments;
     PyObject *result;
 
     if (!PyArg_ParseTuple(args,
                           PySass_IF_PY3("yyiyy", "ssiss"),
-                          &search_path, &output_path, &output_style,
+                          &search_path, &output_path,
+                          &output_style, &source_comments,
                           &include_paths, &image_path)) {
         return NULL;
     }
@@ -101,6 +139,7 @@ PySass_compile_dirname(PyObject *self, PyObject *args) {
     context->search_path = search_path;
     context->output_path = output_path;
     context->options.output_style = output_style;
+    context->options.source_comments = source_comments;
     context->options.include_paths = include_paths;
     context->options.image_path = image_path;
 
@@ -127,18 +166,25 @@ static PyMethodDef PySass_methods[] = {
 
 static char PySass_doc[] = "The thin binding of libsass for Python.";
 
-void PySass_init_module(PyObject *module) {
-    PyObject *output_styles;
-    size_t i = 0;
-    output_styles = PyDict_New();
-    for (i = 0; PySass_output_style_enum[i].label; ++i) {
+void PySass_make_enum_dict(PyObject *enum_dict, struct PySass_Pair *pairs) {
+    size_t i;
+    for (i = 0; pairs[i].label; ++i) {
         PyDict_SetItemString(
-            output_styles,
-            PySass_output_style_enum[i].label,
-            PySass_Int_FromLong((long) PySass_output_style_enum[i].value)
+            enum_dict,
+            pairs[i].label,
+            PySass_Int_FromLong((long) pairs[i].value)
         );
     }
+}
+
+void PySass_init_module(PyObject *module) {
+    PyObject *output_styles, *source_comments;
+    output_styles = PyDict_New();
+    PySass_make_enum_dict(output_styles, PySass_output_style_enum);
     PyModule_AddObject(module, "OUTPUT_STYLES", output_styles);
+    source_comments = PyDict_New();
+    PySass_make_enum_dict(source_comments, PySass_source_comments_enum);
+    PyModule_AddObject(module, "SOURCE_COMMENTS", source_comments);
 }
 
 #if PY_MAJOR_VERSION >= 3

sass.py

@@ -16,17 +16,24 @@
 
 from six import string_types, text_type
 
-from _sass import (OUTPUT_STYLES, compile_dirname, compile_filename,
-                   compile_string)
+from _sass import (OUTPUT_STYLES, SOURCE_COMMENTS, compile_dirname,
+                   compile_filename, compile_string)
 
-__all__ = 'MODES', 'OUTPUT_STYLES', 'CompileError', 'and_join', 'compile'
+__all__ = ('MODES', 'OUTPUT_STYLES', 'SOURCE_COMMENTS', 'CompileError',
+           'and_join', 'compile')
 __version__ = '0.4.0'
 
 
 #: (:class:`collections.Mapping`) The dictionary of output styles.
 #: Keys are output name strings, and values are flag integers.
 OUTPUT_STYLES = OUTPUT_STYLES
 
+#: (:class:`collections.Mapping`) The dictionary of source comments styles.
+#: Keys are mode names, and values are corresponding flag integers.
+#:
+#: .. versionadded:: 0.4.0
+SOURCE_COMMENTS = SOURCE_COMMENTS
+
 #: (:class:`collections.Set`) The set of keywords :func:`compile()` can take.
 MODES = set(['string', 'filename', 'dirname'])
 
@@ -53,6 +60,11 @@ def compile(**kwargs):
                          choose one of: ``'nested'`` (default), ``'expanded'``,
                          ``'compact'``, ``'compressed'``
     :type output_style: :class:`str`
+    :param source_comments: an optional source comments mode of the compiled
+                            result.  choose one of ``'none'`` (default) or
+                            ``'line_numbers'``.  ``'map'`` is unavailable for
+                            ``string``
+    :type source_comments: :class:`str`
     :param include_paths: an optional list of paths to find ``@import``\ ed
                           SASS/CSS source files
     :type include_paths: :class:`collections.Sequence`, :class:`str`
@@ -73,13 +85,28 @@ def compile(**kwargs):
                          choose one of: ``'nested'`` (default), ``'expanded'``,
                          ``'compact'``, ``'compressed'``
     :type output_style: :class:`str`
+    :param source_comments: an optional source comments mode of the compiled
+                            result.  choose one of ``'none'`` (default),
+                            ``'line_numbers'``, ``'map'``.
+                            if ``'map'`` is used it requires
+                            ``source_map_filename`` argument as well and
+                            returns a (compiled CSS string,
+                            source map string) pair instead of a string
+    :type source_comments: :class:`str`
+    :param source_map_filename: indicate the source map output filename.
+                                it's only available and required
+                                when ``source_comments`` is ``'map'``.
+                                note that it will ignore all other parts of
+                                the path except for its basename
+    :type source_map_filename: :class:`str`
     :param include_paths: an optional list of paths to find ``@import``\ ed
                           SASS/CSS source files
     :type include_paths: :class:`collections.Sequence`, :class:`str`
     :param image_path: an optional path to find images
     :type image_path: :class:`str`
-    :returns: the compiled CSS string
-    :rtype: :class:`str`
+    :returns: the compiled CSS string, or a pair of the compiled CSS string
+              and the source map string if ``source_comments='map'``
+    :rtype: :class:`str`, :class:`tuple`
     :raises sass.CompileError: when it fails for any reason
                                (for example the given SASS has broken syntax)
     :raises exceptions.IOError: when the ``filename`` doesn't exist or
@@ -101,6 +128,11 @@ def compile(**kwargs):
                          choose one of: ``'nested'`` (default), ``'expanded'``,
                          ``'compact'``, ``'compressed'``
     :type output_style: :class:`str`
+    :param source_comments: an optional source comments mode of the compiled
+                            result.  choose one of ``'none'`` (default) or
+                            ``'line_numbers'``.  ``'map'`` is unavailable for
+                            ``dirname``
+    :type source_comments: :class:`str`
     :param include_paths: an optional list of paths to find ``@import``\ ed
                           SASS/CSS source files
     :type include_paths: :class:`collections.Sequence`, :class:`str`
@@ -109,6 +141,9 @@ def compile(**kwargs):
     :raises sass.CompileError: when it fails for any reason
                                (for example the given SASS has broken syntax)
 
+    .. versionadded:: 0.4.0
+       Added ``source_comments`` and ``source_map_filename`` parameters.
+
     """
     modes = set()
     for mode_name in MODES:
@@ -119,10 +154,7 @@ def compile(**kwargs):
     elif len(modes) > 1:
         raise TypeError(and_join(modes) + ' are exclusive each other; '
                         'cannot be used at a time')
-    try:
-        output_style = kwargs.pop('output_style')
-    except KeyError:
-        output_style = 'nested'
+    output_style = kwargs.pop('output_style', 'nested')
     if not isinstance(output_style, string_types):
         raise TypeError('output_style must be a string, not ' +
                         repr(output_style))
@@ -131,7 +163,38 @@ def compile(**kwargs):
     except KeyError:
         raise CompileError('{0} is unsupported output_style; choose one of {1}'
                            ''.format(output_style, and_join(OUTPUT_STYLES)))
+    source_comments = kwargs.pop('source_comments', 'none')
+    if not isinstance(source_comments, string_types):
+        raise TypeError('source_comments must be a string, not ' +
+                        repr(source_comments))
+    if 'filename' not in modes and source_comments == 'map':
+        raise CompileError('source_comments="map" is only available with '
+                           'filename= keyword argument since it has to be '
+                           'aware of it')
+    try:
+        source_comments = SOURCE_COMMENTS[source_comments]
+    except KeyError:
+        raise CompileError(
+            '{0} is unsupported source_comments; choose one of '
+            '{1}'.format(source_comments, and_join(SOURCE_COMMENTS))
+        )
     fs_encoding = sys.getfilesystemencoding() or sys.getdefaultencoding()
+    try:
+        source_map_filename = kwargs.pop('source_map_filename') or b''
+    except KeyError:
+        if source_comments == SOURCE_COMMENTS['map']:
+            raise TypeError('source_comments="map" requires '
+                            'source_map_filename argument')
+        source_map_filename = b''
+    else:
+        if source_comments != SOURCE_COMMENTS['map']:
+            raise TypeError('source_map_filename is available only with '
+                            'source_comments="map"')
+        elif not isinstance(source_map_filename, string_types):
+            raise TypeError('source_map_filename must be a string, not ' +
+                            repr(source_map_filename))
+        if isinstance(source_map_filename, text_type):
+            source_map_filename = source_map_filename.encode(fs_encoding)
     try:
         include_paths = kwargs.pop('include_paths') or b''
     except KeyError:
@@ -159,7 +222,11 @@ def compile(**kwargs):
         string = kwargs.pop('string')
         if isinstance(string, text_type):
             string = string.encode('utf-8')
-        s, v = compile_string(string, output_style, include_paths, image_path)
+        s, v = compile_string(string,
+                              output_style, source_comments,
+                              include_paths, image_path)
+        if s:
+            return v.decode('utf-8')
     elif 'filename' in modes:
         filename = kwargs.pop('filename')
         if not isinstance(filename, string_types):
@@ -168,8 +235,16 @@ def compile(**kwargs):
             raise IOError('{0!r} seems not a file'.format(filename))
         elif isinstance(filename, text_type):
             filename = filename.encode(fs_encoding)
-        s, v = compile_filename(filename,
-                                output_style, include_paths, image_path)
+        s, v, source_map = compile_filename(
+            filename,
+            output_style, source_comments,
+            include_paths, image_path, source_map_filename
+        )
+        if s:
+            v = v.decode('utf-8')
+            if source_map_filename:
+                v = v, source_map.decode('utf-8')
+            return v
     elif 'dirname' in modes:
         try:
             search_path, output_path = kwargs.pop('dirname')
@@ -182,11 +257,13 @@ def compile(**kwargs):
             if isinstance(output_path, text_type):
                 output_path = output_path.encode(fs_encoding)
         s, v = compile_dirname(search_path, output_path,
-                               output_style, include_paths, image_path)
+                               output_style, source_comments,
+                               include_paths, image_path)
+        if s:
+            return
     else:
         raise TypeError('something went wrong')
-    if s:
-        return None if v is None else v.decode('utf-8')
+    assert not s
     raise CompileError(v)