django-libsass
==============
A django-compressor filter to compile Sass files using libsass.
Installation
~~~~~~~~~~~~
Starting from a Django project with `django-compressor <https://github.com/django-compressor/django-compressor/>`_ set up::
pip install django-libsass
and add django_libsass.SassCompiler to your COMPRESS_PRECOMPILERS setting::
COMPRESS_PRECOMPILERS = (
('text/x-scss', 'django_libsass.SassCompiler'),
)
You can now use the content type text/x-scss on your stylesheets, and have them
compiled seamlessly into CSS::
{% load compress %}
{% compress css %}
<link rel="stylesheet" type="text/x-scss" href="{% static "myapp/css/main.scss" %}" />
{% endcompress %}
Imports
~~~~~~~
Relative paths in @import lines are followed as you would expect::
@import "../variables.scss";
Additionally, Django's STATICFILES_FINDERS setting is consulted, and all possible locations
for static files *on the local filesystem* are included on the search path. This makes it
possible to import files across different apps::
@import "myotherapp/css/widget.scss"
Settings
~~~~~~~~
The following settings can be used to control django-libsass's behaviour:
* ``LIBSASS_SOURCE_COMMENTS`` - whether to enable SASS source comments (adds comments about source lines). Defaults to ``True`` when Django's ``DEBUG`` is ``True``, ``False`` otherwise.
* ``LIBSASS_OUTPUT_STYLE`` - SASS output style. Options are ``'nested'``, ``'expanded'``, ``'compact'`` and ``'compressed'``, although as of libsass 3.0.2 only ``'nested'`` and ``'compressed'`` are implemented. Default is 'nested'. See `SASS documentation for output styles <http://sass-lang.com/documentation/file.SASS_REFERENCE.html#output_style>`_. Note that `django-compressor's settings <http://django-compressor.readthedocs.org/en/latest/settings/>`_ may also affect the formatting of the resulting CSS.
* ``LIBSASS_CUSTOM_FUNCTIONS`` - A mapping of custom functions to be made available within the SASS compiler. By default, a ``static`` function is provided, analogous to Django's ``static`` template tag.
* ``LIBSASS_SOURCEMAPS`` - Enable embedding sourcemaps into file output (default: False)
* ``LIBSASS_PRECISION`` - Number of digits of numerical precision (default: 5)
* ``LIBSASS_ADDITIONAL_INCLUDE_PATHS`` - a list of base paths to be recognised in @import lines, in addition to Django's recognised static file locations
Custom functions
~~~~~~~~~~~~~~~~
The SASS compiler can be extended with custom Python functions defined in the ``LIBSASS_CUSTOM_FUNCTIONS`` setting. By default, a ``static`` function is provided, for generating static paths to resources such as images and fonts::
.foo {
background: url(static("myapp/image/bar.png"));
}
If your ``STATIC_URL`` is '/static/', this will be rendered as::
.foo {
background: url("/static/myapp/image/bar.png"));
}
Why django-libsass?
~~~~~~~~~~~~~~~~~~~
We wanted to use Sass in a Django project without introducing any external (non pip-installable)
dependencies. (Actually, we wanted to use Less, but the same arguments apply...) There are a few
pure Python implementations of Sass and Less, but we found that they invariably didn't match the
behaviour of the reference compilers, either in their handling of @imports or lesser-used CSS
features such as media queries.
`libsass <http://libsass.org/>`_ is a mature C/C++ port of the Sass engine, co-developed by the
original creator of Sass, and we can reasonably rely on it to stay in sync with the reference
Sass compiler - and, being C/C++, it's fast. Thanks to Hong Minhee's
`libsass-python <https://github.com/dahlia/libsass-python>`_ project, it has Python bindings and
installs straight from pip.
django-libsass builds on libsass-python to make @import paths aware of Django's staticfiles
mechanism, and provides a filter module for django-compressor which uses the libsass-python API
directly, avoiding the overheads of calling an external executable to do the compilation.
Reporting bugs
~~~~~~~~~~~~~~
Please see the `troubleshooting <https://github.com/torchbox/django-libsass/wiki/Troubleshooting>`_ page for help with some common setup issues.
I do not provide support for getting django-libsass working with your CSS framework of choice. If you believe you've found a bug, please try to isolate it as a minimal reproducible test case before reporting it - ideally this will consist of a few edits / additions to the `hello-django-libsass <https://github.com/gasman/hello-django-libsass>`_ example project. If you cannot demonstrate the problem in a few standalone SCSS files, it is almost certainly not a django-libsass bug - any bug reports that relate to a third-party CSS framework are likely to be closed without further investigation.
Author
~~~~~~
Matt Westcott matthew.westcott@torchbox.com
Raw data
{
"_id": null,
"home_page": "https://github.com/torchbox/django-libsass",
"name": "django-libsass",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Matt Westcott",
"author_email": "matthew.westcott@torchbox.com",
"download_url": "https://files.pythonhosted.org/packages/d2/6c/fe7c95536eed569960daf139726c8f83eaf8c4ae01d908c22d94d60f31c2/django-libsass-0.9.tar.gz",
"platform": "",
"description": "django-libsass\n==============\n\nA django-compressor filter to compile Sass files using libsass.\n\nInstallation\n~~~~~~~~~~~~\n\nStarting from a Django project with `django-compressor <https://github.com/django-compressor/django-compressor/>`_ set up::\n\n pip install django-libsass\n\nand add django_libsass.SassCompiler to your COMPRESS_PRECOMPILERS setting::\n\n COMPRESS_PRECOMPILERS = (\n ('text/x-scss', 'django_libsass.SassCompiler'),\n )\n\nYou can now use the content type text/x-scss on your stylesheets, and have them\ncompiled seamlessly into CSS::\n\n {% load compress %}\n\n {% compress css %}\n <link rel=\"stylesheet\" type=\"text/x-scss\" href=\"{% static \"myapp/css/main.scss\" %}\" />\n {% endcompress %}\n\n\nImports\n~~~~~~~\n\nRelative paths in @import lines are followed as you would expect::\n\n @import \"../variables.scss\";\n\nAdditionally, Django's STATICFILES_FINDERS setting is consulted, and all possible locations\nfor static files *on the local filesystem* are included on the search path. This makes it\npossible to import files across different apps::\n\n @import \"myotherapp/css/widget.scss\"\n\n\nSettings\n~~~~~~~~\n\nThe following settings can be used to control django-libsass's behaviour:\n\n* ``LIBSASS_SOURCE_COMMENTS`` - whether to enable SASS source comments (adds comments about source lines). Defaults to ``True`` when Django's ``DEBUG`` is ``True``, ``False`` otherwise.\n* ``LIBSASS_OUTPUT_STYLE`` - SASS output style. Options are ``'nested'``, ``'expanded'``, ``'compact'`` and ``'compressed'``, although as of libsass 3.0.2 only ``'nested'`` and ``'compressed'`` are implemented. Default is 'nested'. See `SASS documentation for output styles <http://sass-lang.com/documentation/file.SASS_REFERENCE.html#output_style>`_. Note that `django-compressor's settings <http://django-compressor.readthedocs.org/en/latest/settings/>`_ may also affect the formatting of the resulting CSS.\n* ``LIBSASS_CUSTOM_FUNCTIONS`` - A mapping of custom functions to be made available within the SASS compiler. By default, a ``static`` function is provided, analogous to Django's ``static`` template tag.\n* ``LIBSASS_SOURCEMAPS`` - Enable embedding sourcemaps into file output (default: False)\n* ``LIBSASS_PRECISION`` - Number of digits of numerical precision (default: 5)\n* ``LIBSASS_ADDITIONAL_INCLUDE_PATHS`` - a list of base paths to be recognised in @import lines, in addition to Django's recognised static file locations\n\n\nCustom functions\n~~~~~~~~~~~~~~~~\n\nThe SASS compiler can be extended with custom Python functions defined in the ``LIBSASS_CUSTOM_FUNCTIONS`` setting. By default, a ``static`` function is provided, for generating static paths to resources such as images and fonts::\n\n .foo {\n background: url(static(\"myapp/image/bar.png\"));\n }\n\nIf your ``STATIC_URL`` is '/static/', this will be rendered as::\n\n .foo {\n background: url(\"/static/myapp/image/bar.png\"));\n }\n\nWhy django-libsass?\n~~~~~~~~~~~~~~~~~~~\n\nWe wanted to use Sass in a Django project without introducing any external (non pip-installable)\ndependencies. (Actually, we wanted to use Less, but the same arguments apply...) There are a few\npure Python implementations of Sass and Less, but we found that they invariably didn't match the\nbehaviour of the reference compilers, either in their handling of @imports or lesser-used CSS\nfeatures such as media queries.\n\n`libsass <http://libsass.org/>`_ is a mature C/C++ port of the Sass engine, co-developed by the\noriginal creator of Sass, and we can reasonably rely on it to stay in sync with the reference\nSass compiler - and, being C/C++, it's fast. Thanks to Hong Minhee's\n`libsass-python <https://github.com/dahlia/libsass-python>`_ project, it has Python bindings and\ninstalls straight from pip.\n\ndjango-libsass builds on libsass-python to make @import paths aware of Django's staticfiles\nmechanism, and provides a filter module for django-compressor which uses the libsass-python API\ndirectly, avoiding the overheads of calling an external executable to do the compilation.\n\n\nReporting bugs\n~~~~~~~~~~~~~~\n\nPlease see the `troubleshooting <https://github.com/torchbox/django-libsass/wiki/Troubleshooting>`_ page for help with some common setup issues.\n\nI do not provide support for getting django-libsass working with your CSS framework of choice. If you believe you've found a bug, please try to isolate it as a minimal reproducible test case before reporting it - ideally this will consist of a few edits / additions to the `hello-django-libsass <https://github.com/gasman/hello-django-libsass>`_ example project. If you cannot demonstrate the problem in a few standalone SCSS files, it is almost certainly not a django-libsass bug - any bug reports that relate to a third-party CSS framework are likely to be closed without further investigation.\n\n\nAuthor\n~~~~~~\n\nMatt Westcott matthew.westcott@torchbox.com\n\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "A django-compressor filter to compile SASS files using libsass",
"version": "0.9",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1bee65935acc5a36c418fa17d5190a4aeb339cfdf98b6a93ca1c59134cf1e6aa",
"md5": "532f8fc620dfe8005eaa19d887524cb7",
"sha256": "5234d29100889cac79e36a0f44207ec6d275adfd2da1acb6a94b55c89fe2bd97"
},
"downloads": -1,
"filename": "django_libsass-0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "532f8fc620dfe8005eaa19d887524cb7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 6572,
"upload_time": "2021-07-08T14:16:53",
"upload_time_iso_8601": "2021-07-08T14:16:53.501651Z",
"url": "https://files.pythonhosted.org/packages/1b/ee/65935acc5a36c418fa17d5190a4aeb339cfdf98b6a93ca1c59134cf1e6aa/django_libsass-0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d26cfe7c95536eed569960daf139726c8f83eaf8c4ae01d908c22d94d60f31c2",
"md5": "54ec0a413b6f817b5b5deff78c92ec66",
"sha256": "bfbbb55a8950bb40fa04dd416605f92da34ad1f303b10a41abc3232386ec27b5"
},
"downloads": -1,
"filename": "django-libsass-0.9.tar.gz",
"has_sig": false,
"md5_digest": "54ec0a413b6f817b5b5deff78c92ec66",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6754,
"upload_time": "2021-07-08T14:16:55",
"upload_time_iso_8601": "2021-07-08T14:16:55.346379Z",
"url": "https://files.pythonhosted.org/packages/d2/6c/fe7c95536eed569960daf139726c8f83eaf8c4ae01d908c22d94d60f31c2/django-libsass-0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-07-08 14:16:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "torchbox",
"github_project": "django-libsass",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "django-libsass"
}
JSON
