diff --git a/.gitignore b/.gitignore index ea8a513670..f83bb8c9eb 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,12 @@ build/* a.out bin/* *.gem + +dist/ +docs/_build +.tox +.*.swp +*.egg +*.egg-info +*.so +*.pyc diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000000..55c1a22534 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,19 @@ +branches: + only: + - python +language: python +python: +- 2.5 +- 2.6 +- 2.7 +- pypy +install: +- pip install Attest +script: +- python setup.py test +notifications: + irc: + channels: + - "irc.ozinger.org:8080#hongminhee" + on_success: change + on_failure: always diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000000..8df76e815b --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1,5 @@ +include *.h +include *.hpp +include *.cpp +include test/*.sass +include README.rst diff --git a/README.rst b/README.rst new file mode 100644 index 0000000000..2e9f17b568 --- /dev/null +++ b/README.rst @@ -0,0 +1,71 @@ +libsass: SASS_ for Python +========================= + +This package provides a simple Python extension module ``sass`` which is +binding Libsass_ (written in C/C++ by Hampton Catlin and Aaron Leung). +It's very straightforward and there isn't any headache related Python +distribution/deployment. That means you can add just ``libsass`` into +your ``setup.py``'s ``install_requires`` list or ``requirements.txt`` file. +Need no Ruby nor Node.js. + +It currently supports CPython 2.5, 2.6, 2.7, and PyPy 1.9! + +.. _SASS: http://sass-lang.com/ +.. _Libsass: https://github.com/hcatlin/libsass + + +Install +------- + +It's available on PyPI_, so you can install it using ``easy_install`` +or ``pip``: + +.. code-block:: console + + $ easy_install libsass + +.. _PyPI: http://pypi.python.org/pypi/libsass + + +Example +------- + +.. code-block:: pycon + + >>> import sass + >>> print sass.compile(string='a { b { color: blue; } }') + a b { + color: blue; } + + +Docs +---- + +There's the user guide manual and the full API reference for ``libsass``: + +http://dahlia.kr/libsass-python/ + +You can build the docs by yourself: + +.. code-block:: console + + $ cd docs/ + $ make html + +The built docs will go to ``docs/_build/html/`` directory. + + +Credit +------ + +Hong Minhee wrote this Python binding of Libsass_. + +Hampton Catlin and Aaron Leung wrote Libsass_, which is portable C/C++ +implementation of SASS_. + +Hampton Catlin originally designed SASS_ language and wrote the first +reference implementation of it in Ruby. + +The above three softwares are all distributed under `MIT license`_. + +.. _MIT license: http://mit-license.org/ diff --git a/distribute_setup.py b/distribute_setup.py new file mode 100644 index 0000000000..8f5b0637bf --- /dev/null +++ b/distribute_setup.py @@ -0,0 +1,515 @@ +#!python +"""Bootstrap distribute installation + +If you want to use setuptools in your package's setup.py, just include this +file in the same directory with it, and add this to the top of your setup.py:: + + from distribute_setup import use_setuptools + use_setuptools() + +If you want to require a specific version of setuptools, set a download +mirror, or use an alternate download directory, you can do so by supplying +the appropriate options to ``use_setuptools()``. + +This file can also be run as a script to install or upgrade setuptools. +""" +import os +import sys +import time +import fnmatch +import tempfile +import tarfile +from distutils import log + +try: + from site import USER_SITE +except ImportError: + USER_SITE = None + +try: + import subprocess + + def _python_cmd(*args): + args = (sys.executable,) + args + return subprocess.call(args) == 0 + +except ImportError: + # will be used for python 2.3 + def _python_cmd(*args): + args = (sys.executable,) + args + # quoting arguments if windows + if sys.platform == 'win32': + def quote(arg): + if ' ' in arg: + return '"%s"' % arg + return arg + args = [quote(arg) for arg in args] + return os.spawnl(os.P_WAIT, sys.executable, *args) == 0 + +DEFAULT_VERSION = "0.6.28" +DEFAULT_URL = "http://pypi.python.org/packages/source/d/distribute/" +SETUPTOOLS_FAKED_VERSION = "0.6c11" + +SETUPTOOLS_PKG_INFO = """\ +Metadata-Version: 1.0 +Name: setuptools +Version: %s +Summary: xxxx +Home-page: xxx +Author: xxx +Author-email: xxx +License: xxx +Description: xxx +""" % SETUPTOOLS_FAKED_VERSION + + +def _install(tarball, install_args=()): + # extracting the tarball + tmpdir = tempfile.mkdtemp() + log.warn('Extracting in %s', tmpdir) + old_wd = os.getcwd() + try: + os.chdir(tmpdir) + tar = tarfile.open(tarball) + _extractall(tar) + tar.close() + + # going in the directory + subdir = os.path.join(tmpdir, os.listdir(tmpdir)[0]) + os.chdir(subdir) + log.warn('Now working in %s', subdir) + + # installing + log.warn('Installing Distribute') + if not _python_cmd('setup.py', 'install', *install_args): + log.warn('Something went wrong during the installation.') + log.warn('See the error message above.') + finally: + os.chdir(old_wd) + + +def _build_egg(egg, tarball, to_dir): + # extracting the tarball + tmpdir = tempfile.mkdtemp() + log.warn('Extracting in %s', tmpdir) + old_wd = os.getcwd() + try: + os.chdir(tmpdir) + tar = tarfile.open(tarball) + _extractall(tar) + tar.close() + + # going in the directory + subdir = os.path.join(tmpdir, os.listdir(tmpdir)[0]) + os.chdir(subdir) + log.warn('Now working in %s', subdir) + + # building an egg + log.warn('Building a Distribute egg in %s', to_dir) + _python_cmd('setup.py', '-q', 'bdist_egg', '--dist-dir', to_dir) + + finally: + os.chdir(old_wd) + # returning the result + log.warn(egg) + if not os.path.exists(egg): + raise IOError('Could not build the egg.') + + +def _do_download(version, download_base, to_dir, download_delay): + egg = os.path.join(to_dir, 'distribute-%s-py%d.%d.egg' + % (version, sys.version_info[0], sys.version_info[1])) + if not os.path.exists(egg): + tarball = download_setuptools(version, download_base, + to_dir, download_delay) + _build_egg(egg, tarball, to_dir) + sys.path.insert(0, egg) + import setuptools + setuptools.bootstrap_install_from = egg + + +def use_setuptools(version=DEFAULT_VERSION, download_base=DEFAULT_URL, + to_dir=os.curdir, download_delay=15, no_fake=True): + # making sure we use the absolute path + to_dir = os.path.abspath(to_dir) + was_imported = 'pkg_resources' in sys.modules or \ + 'setuptools' in sys.modules + try: + try: + import pkg_resources + if not hasattr(pkg_resources, '_distribute'): + if not no_fake: + _fake_setuptools() + raise ImportError + except ImportError: + return _do_download(version, download_base, to_dir, download_delay) + try: + pkg_resources.require("distribute>=" + version) + return + except pkg_resources.VersionConflict: + e = sys.exc_info()[1] + if was_imported: + sys.stderr.write( + "The required version of distribute (>=%s) is not available,\n" + "and can't be installed while this script is running. Please\n" + "install a more recent version first, using\n" + "'easy_install -U distribute'." + "\n\n(Currently using %r)\n" % (version, e.args[0])) + sys.exit(2) + else: + del pkg_resources, sys.modules['pkg_resources'] # reload ok + return _do_download(version, download_base, to_dir, + download_delay) + except pkg_resources.DistributionNotFound: + return _do_download(version, download_base, to_dir, + download_delay) + finally: + if not no_fake: + _create_fake_setuptools_pkg_info(to_dir) + + +def download_setuptools(version=DEFAULT_VERSION, download_base=DEFAULT_URL, + to_dir=os.curdir, delay=15): + """Download distribute from a specified location and return its filename + + `version` should be a valid distribute version number that is available + as an egg for download under the `download_base` URL (which should end + with a '/'). `to_dir` is the directory where the egg will be downloaded. + `delay` is the number of seconds to pause before an actual download + attempt. + """ + # making sure we use the absolute path + to_dir = os.path.abspath(to_dir) + try: + from urllib.request import urlopen + except ImportError: + from urllib2 import urlopen + tgz_name = "distribute-%s.tar.gz" % version + url = download_base + tgz_name + saveto = os.path.join(to_dir, tgz_name) + src = dst = None + if not os.path.exists(saveto): # Avoid repeated downloads + try: + log.warn("Downloading %s", url) + src = urlopen(url) + # Read/write all in one block, so we don't create a corrupt file + # if the download is interrupted. + data = src.read() + dst = open(saveto, "wb") + dst.write(data) + finally: + if src: + src.close() + if dst: + dst.close() + return os.path.realpath(saveto) + + +def _no_sandbox(function): + def __no_sandbox(*args, **kw): + try: + from setuptools.sandbox import DirectorySandbox + if not hasattr(DirectorySandbox, '_old'): + def violation(*args): + pass + DirectorySandbox._old = DirectorySandbox._violation + DirectorySandbox._violation = violation + patched = True + else: + patched = False + except ImportError: + patched = False + + try: + return function(*args, **kw) + finally: + if patched: + DirectorySandbox._violation = DirectorySandbox._old + del DirectorySandbox._old + + return __no_sandbox + + +def _patch_file(path, content): + """Will backup the file then patch it""" + existing_content = open(path).read() + if existing_content == content: + # already patched + log.warn('Already patched.') + return False + log.warn('Patching...') + _rename_path(path) + f = open(path, 'w') + try: + f.write(content) + finally: + f.close() + return True + +_patch_file = _no_sandbox(_patch_file) + + +def _same_content(path, content): + return open(path).read() == content + + +def _rename_path(path): + new_name = path + '.OLD.%s' % time.time() + log.warn('Renaming %s into %s', path, new_name) + os.rename(path, new_name) + return new_name + + +def _remove_flat_installation(placeholder): + if not os.path.isdir(placeholder): + log.warn('Unkown installation at %s', placeholder) + return False + found = False + for file in os.listdir(placeholder): + if fnmatch.fnmatch(file, 'setuptools*.egg-info'): + found = True + break + if not found: + log.warn('Could not locate setuptools*.egg-info') + return + + log.warn('Removing elements out of the way...') + pkg_info = os.path.join(placeholder, file) + if os.path.isdir(pkg_info): + patched = _patch_egg_dir(pkg_info) + else: + patched = _patch_file(pkg_info, SETUPTOOLS_PKG_INFO) + + if not patched: + log.warn('%s already patched.', pkg_info) + return False + # now let's move the files out of the way + for element in ('setuptools', 'pkg_resources.py', 'site.py'): + element = os.path.join(placeholder, element) + if os.path.exists(element): + _rename_path(element) + else: + log.warn('Could not find the %s element of the ' + 'Setuptools distribution', element) + return True + +_remove_flat_installation = _no_sandbox(_remove_flat_installation) + + +def _after_install(dist): + log.warn('After install bootstrap.') + placeholder = dist.get_command_obj('install').install_purelib + _create_fake_setuptools_pkg_info(placeholder) + + +def _create_fake_setuptools_pkg_info(placeholder): + if not placeholder or not os.path.exists(placeholder): + log.warn('Could not find the install location') + return + pyver = '%s.%s' % (sys.version_info[0], sys.version_info[1]) + setuptools_file = 'setuptools-%s-py%s.egg-info' % \ + (SETUPTOOLS_FAKED_VERSION, pyver) + pkg_info = os.path.join(placeholder, setuptools_file) + if os.path.exists(pkg_info): + log.warn('%s already exists', pkg_info) + return + + if not os.access(pkg_info, os.W_OK): + log.warn("Don't have permissions to write %s, skipping", pkg_info) + + log.warn('Creating %s', pkg_info) + f = open(pkg_info, 'w') + try: + f.write(SETUPTOOLS_PKG_INFO) + finally: + f.close() + + pth_file = os.path.join(placeholder, 'setuptools.pth') + log.warn('Creating %s', pth_file) + f = open(pth_file, 'w') + try: + f.write(os.path.join(os.curdir, setuptools_file)) + finally: + f.close() + +_create_fake_setuptools_pkg_info = _no_sandbox( + _create_fake_setuptools_pkg_info +) + + +def _patch_egg_dir(path): + # let's check if it's already patched + pkg_info = os.path.join(path, 'EGG-INFO', 'PKG-INFO') + if os.path.exists(pkg_info): + if _same_content(pkg_info, SETUPTOOLS_PKG_INFO): + log.warn('%s already patched.', pkg_info) + return False + _rename_path(path) + os.mkdir(path) + os.mkdir(os.path.join(path, 'EGG-INFO')) + pkg_info = os.path.join(path, 'EGG-INFO', 'PKG-INFO') + f = open(pkg_info, 'w') + try: + f.write(SETUPTOOLS_PKG_INFO) + finally: + f.close() + return True + +_patch_egg_dir = _no_sandbox(_patch_egg_dir) + + +def _before_install(): + log.warn('Before install bootstrap.') + _fake_setuptools() + + +def _under_prefix(location): + if 'install' not in sys.argv: + return True + args = sys.argv[sys.argv.index('install') + 1:] + for index, arg in enumerate(args): + for option in ('--root', '--prefix'): + if arg.startswith('%s=' % option): + top_dir = arg.split('root=')[-1] + return location.startswith(top_dir) + elif arg == option: + if len(args) > index: + top_dir = args[index + 1] + return location.startswith(top_dir) + if arg == '--user' and USER_SITE is not None: + return location.startswith(USER_SITE) + return True + + +def _fake_setuptools(): + log.warn('Scanning installed packages') + try: + import pkg_resources + except ImportError: + # we're cool + log.warn('Setuptools or Distribute does not seem to be installed.') + return + ws = pkg_resources.working_set + try: + setuptools_dist = ws.find( + pkg_resources.Requirement.parse('setuptools', replacement=False) + ) + except TypeError: + # old distribute API + setuptools_dist = ws.find( + pkg_resources.Requirement.parse('setuptools') + ) + + if setuptools_dist is None: + log.warn('No setuptools distribution found') + return + # detecting if it was already faked + setuptools_location = setuptools_dist.location + log.warn('Setuptools installation detected at %s', setuptools_location) + + # if --root or --preix was provided, and if + # setuptools is not located in them, we don't patch it + if not _under_prefix(setuptools_location): + log.warn('Not patching, --root or --prefix is installing Distribute' + ' in another location') + return + + # let's see if its an egg + if not setuptools_location.endswith('.egg'): + log.warn('Non-egg installation') + res = _remove_flat_installation(setuptools_location) + if not res: + return + else: + log.warn('Egg installation') + pkg_info = os.path.join(setuptools_location, 'EGG-INFO', 'PKG-INFO') + if (os.path.exists(pkg_info) and + _same_content(pkg_info, SETUPTOOLS_PKG_INFO)): + log.warn('Already patched.') + return + log.warn('Patching...') + # let's create a fake egg replacing setuptools one + res = _patch_egg_dir(setuptools_location) + if not res: + return + log.warn('Patched done.') + _relaunch() + + +def _relaunch(): + log.warn('Relaunching...') + # we have to relaunch the process + # pip marker to avoid a relaunch bug + _cmd = ['-c', 'install', '--single-version-externally-managed'] + if sys.argv[:3] == _cmd: + sys.argv[0] = 'setup.py' + args = [sys.executable] + sys.argv + sys.exit(subprocess.call(args)) + + +def _extractall(self, path=".", members=None): + """Extract all members from the archive to the current working + directory and set owner, modification time and permissions on + directories afterwards. `path' specifies a different directory + to extract to. `members' is optional and must be a subset of the + list returned by getmembers(). + """ + import copy + import operator + from tarfile import ExtractError + directories = [] + + if members is None: + members = self + + for tarinfo in members: + if tarinfo.isdir(): + # Extract directories with a safe mode. + directories.append(tarinfo) + tarinfo = copy.copy(tarinfo) + tarinfo.mode = 448 # decimal for oct 0700 + self.extract(tarinfo, path) + + # Reverse sort directories. + if sys.version_info < (2, 4): + def sorter(dir1, dir2): + return cmp(dir1.name, dir2.name) + directories.sort(sorter) + directories.reverse() + else: + directories.sort(key=operator.attrgetter('name'), reverse=True) + + # Set correct owner, mtime and filemode on directories. + for tarinfo in directories: + dirpath = os.path.join(path, tarinfo.name) + try: + self.chown(tarinfo, dirpath) + self.utime(tarinfo, dirpath) + self.chmod(tarinfo, dirpath) + except ExtractError: + e = sys.exc_info()[1] + if self.errorlevel > 1: + raise + else: + self._dbg(1, "tarfile: %s" % e) + + +def _build_install_args(argv): + install_args = [] + user_install = '--user' in argv + if user_install and sys.version_info < (2, 6): + log.warn("--user requires Python 2.6 or later") + raise SystemExit(1) + if user_install: + install_args.append('--user') + return install_args + + +def main(argv, version=DEFAULT_VERSION): + """Install or upgrade setuptools and EasyInstall""" + tarball = download_setuptools() + _install(tarball, _build_install_args(argv)) + + +if __name__ == '__main__': + main(sys.argv[1:]) diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000..bfbbccefa5 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,153 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/libsass.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/libsass.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/libsass" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/libsass" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/changes.rst b/docs/changes.rst new file mode 100644 index 0000000000..451ce2ab61 --- /dev/null +++ b/docs/changes.rst @@ -0,0 +1,73 @@ +Changelog +========= + +Version 0.2.4 +------------- + +Released on December 4, 2012. + +- Added :mod:`sassc` CLI executable script. +- Added :const:`sass.OUTPUT_STYLES` constant map. +- Merged recent changes from libsass upstream: + `e997102--a84b181`__. + +__ https://github.com/hcatlin/libsass/compare/e9971023785dabd41aa44f431f603f62b15e6017...a84b181a6e59463c0ac9796ca7fdaf4864f0ad84 + + +Version 0.2.3 +------------- + +Released on October 24, 2012. + +- :mod:`sassutils.distutils`: Prevent double monkey patch of ``sdist``. +- Merged upstream changes of libsass. + + +Version 0.2.2 +------------- + +Released on September 28, 2012. + +- Fixed a link error on PyPy and Linux. +- Fixed build errors on Windows. + + +Version 0.2.1 +------------- + +Released on September 12, 2012. + +- Support Windows. + + +Version 0.2.0 +------------- + +Released on August 24, 2012. + +- Added new :mod:`sassutils` package. + + - Added :mod:`sassutils.builder` module to build the whole directory + at a time. + - Added :mod:`sassutils.distutils` module for :mod:`distutils` and + :mod:`setuptools` integration. + - Added :mod:`sassutils.wsgi` module which provides a development-purpose + WSGI middleware. + +- Added :class:`~sassutils.distutils.build_sass` command for + :mod:`distutils`/:mod:`setuptools`. + + +Version 0.1.1 +------------- + +Released on August 18, 2012. + +- Fixed segmentation fault for reading ``filename`` which does not exist. + Now it raises a proper ``exceptions.IOError`` exception. + + +Version 0.1.0 +------------- + +Released on August 17, 2012. Initial version. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000..e9e3e57fec --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,263 @@ +# -*- coding: utf-8 -*- +# +# libsass documentation build configuration file, created by +# sphinx-quickstart on Sun Aug 19 22:45:57 2012. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. +import ast +import os +import sys +import warnings + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('..')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +needs_sphinx = '1.1' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'libsass' +copyright = u'2012, Hong Minhee' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. (Parse setup.py script.) +with open('../setup.py') as f: + setup_py = ast.parse(f.read(), f.name) +for node in setup_py.body: + if (isinstance(node, ast.Assign) and len(node.targets) == 1 and + node.targets[0].id == 'version' and isinstance(node.value, ast.Str)): + version = node.value.s + break +else: + warnings.warn('cannot find "version = \'...\'" expression in setup.py ' + "script; set version = 'unknown' instead") + version = 'unknown' +# The full version, including alpha/beta/rc tags. +release = version + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'sphinxdoc' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'libsassdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'libsass.tex', u'libsass Documentation', + u'Hong Minhee', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'libsass', u'libsass Documentation', + [u'Hong Minhee'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'libsass', u'libsass Documentation', + u'Hong Minhee', 'libsass', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = { + 'python': ('http://docs.python.org/', None), + 'distribute': ('http://packages.python.org/distribute/', None), + 'flask': ('http://flask.pocoo.org/docs/', None) +} + diff --git a/docs/frameworks/flask.rst b/docs/frameworks/flask.rst new file mode 100644 index 0000000000..653ff154f4 --- /dev/null +++ b/docs/frameworks/flask.rst @@ -0,0 +1,176 @@ +Using with Flask +================ + +This guide explains how to use libsass with Flask_ web framework. +:mod:`sassutils` package provides several tools that can be integrated +to web applications written in Flask. + +.. _Flask: http://flask.pocoo.org/ + +.. contents:: + + +Directory layout +---------------- + +Imagine the project contained in such directory layout: + +- :file:`setup.py` +- :file:`myapp/` + + - :file:`__init__.py` + - :file:`static/` + + - :file:`sass/` + - :file:`css/` + - :file:`templates/` + +SASS/SCSS files will go inside :file:`myapp/static/sass/` directory. +Compiled CSS files will go inside :file:`myapp/static/css/` directory. +CSS files can be regenerated, so add :file:`myapp/static/css/` into your +ignore list like :file:`.gitignore` or :file:`.hgignore`. + + +Defining manifest +----------------- + +The :mod:`sassutils` defines a concept named :dfn:`manifest`. +Manifest is building settings of SASS/SCSS. It specifies some paths +related to building SASS/SCSS: + +- The path of the directory which contains SASS/SCSS source files. +- The path of the directory compiled CSS files will go. +- The path, is exposed to HTTP (through WSGI), of the directory that + will contain compiled CSS files. + +Every package may have their own manifest. Paths have to be relative +to the path of the package. + +For example, in the project the package name is :mod:`myapp`. +The path of the package is :file:`myapp/`. The path of SASS/SCSS directory +is :file:`static/sass/` (relative to the package directory). +The path of CSS directory is :file:`static/css/`. +The exposed path is :file:`/static/css`. + +This settings can be represented as the following manifests:: + + { + 'myapp': ('static/sass', 'static/css', '/static/css') + } + +As you can see the above, the set of manifests are represented in dictionary. +Keys are packages names. Values are tuples of paths. + + +Building SASS/SCSS for each request +----------------------------------- + +.. seealso:: + + Flask --- `Hooking in WSGI Middlewares`__ + The section which explains how to integrate WSGI middlewares to + Flask. + + Flask --- :ref:`flask:app-dispatch` + The documentation which explains how Flask dispatch each + request internally. + + __ http://flask.pocoo.org/docs/quickstart/#hooking-in-wsgi-middlewares + +In development, to manually build SASS/SCSS files for each change is +so tiring. :class:`~sassutils.wsgi.SassMiddleware` makes the web +application to automatically build SASS/SCSS files for each request. +It's a WSGI middleware, so it can be plugged into the web app written in +Flask. + +:class:`~sassutils.wsgi.SassMiddleware` takes two required parameters: + +- The WSGI-compliant callable object. +- The set of manifests represented as dictionary. + +So:: + + from flask import Flask + from sassutils.wsgi import SassMiddleware + + app = Flask(__name__) + + app.wsgi_app = SassMiddleware(app.wsgi_app, { + 'myapp': ('static/sass', 'static/css', '/static/css') + }) + +And then, if you want to link a compiled CSS file, use :func:`~flask.url_for()` +function: + +.. sourcecode:: html+jinja + + + +.. note:: + + The linked filename is :file:`style.scss.css`, not just :file:`style.scss`. + All compiled filenames have trailing ``.css`` suffix. + + +Building SASS/SCSS for each deployment +-------------------------------------- + +.. note:: + + This section assumes that you use distribute_ (:mod:`setuptools`) + for deployment. + +.. seealso:: + + Flask --- :ref:`flask:distribute-deployment` + How to deploy Flask application using distribute_. + +If libsass has been installed in the :file:`site-packages` (for example, +your virtualenv), :file:`setup.py` script also gets had new command +provided by libsass: :class:`~sassutils.distutils.build_sass`. +The command is aware of ``sass_manifests`` option of :file:`setup.py` and +builds all SASS/SCSS sources according to the manifests. + +Add these arguments to :file:`setup.py` script:: + + setup( + # ..., + setup_requires=['libsass >= 0.2.0'], + sass_manifests={ + 'myapp': ('static/sass', 'static/css', '/static/css') + } + ) + +The ``setup_requires`` option makes sure that the libsass is installed +in :file:`site-packages` (for example, your virtualenv) before +:file:`setup.py` script. That means: if you run :file:`setup.py` script +and libsass isn't installed yet at the moment, it will automatically +install libsass first. + +The ``sass_manifests`` specifies the manifests for libsass. + +Now :program:`setup.py build_sass` will compile all SASS/SCSS files +in the specified path and generates compiled CSS files into the specified +path (according to the manifests). + +If you use it with ``sdist`` or ``bdist`` command, a packed archive also +will contain compiled CSS files! + +.. sourcecode:: console + + $ python setup.py build_sass sdist + +You can add aliases to make these commands to always run ``build_sass`` +command before. Make :file:`setup.cfg` config: + +.. sourcecode:: ini + + [aliases] + sdist = build_sass sdist + bdist = build_sass bdist + +Now it automatically builds SASS/SCSS sources and include compiled CSS files +to the package archive when you run :program:`setup.py sdist`. + +.. _distribute: http://pypi.python.org/pypi/distribute diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000000..0f0c2b17cf --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,100 @@ +libsass +======= + +This package provides a simple Python extension module :mod:`sass` which is +binding Libsass_ (written in C/C++ by Hampton Catlin and Aaron Leung). +It's very straightforward and there isn't any headache related Python +distribution/deployment. That means you can add just ``libsass`` into +your :file:`setup.py`'s ``install_requires`` list or :file:`requirements.txt` +file. + +It currently supports CPython 2.5, 2.6, 2.7, and PyPy 1.9! + +.. _SASS: http://sass-lang.com/ +.. _Libsass: https://github.com/hcatlin/libsass + + +Install +------- + +It's available on PyPI_, so you can install it using :program:`easy_install` +or :program:`pip`: + +.. sourcecode:: console + + $ easy_install libsass + +.. _PyPI: http://pypi.python.org/pypi/libsass + + +Example +------- + +>>> import sass +>>> sass.compile(string='a { b { color: blue; } }') +'a b {\n color: blue; }\n' + + +User's Guide +------------ + +.. toctree:: + :maxdepth: 2 + + frameworks/flask + changes + + +References +---------- + +.. toctree:: + :maxdepth: 2 + + sassc + sass + sassutils + + +Credit +------ + +Hong Minhee wrote this Python binding of Libsass_. + +Hampton Catlin and Aaron Leung wrote Libsass_, which is portable C/C++ +implementation of SASS_. + +Hampton Catlin originally designed SASS_ language and wrote the first +reference implementation of it in Ruby. + +The above three softwares are all distributed under `MIT license`_. + +.. _MIT license: http://mit-license.org/ + + +Open source +----------- + +GitHub (Git repository + issues) + https://github.com/dahlia/libsass-python + +Travis CI + http://travis-ci.org/dahlia/libsass-python + + .. image:: https://secure.travis-ci.org/dahlia/libsass-python.png?branch=python + :alt: Build Status + :target: http://travis-ci.org/dahlia/libsass-python + +PyPI + http://pypi.python.org/pypi/libsass + +Changelog + :doc:`changes` + + +Indices and tables +------------------ + +- :ref:`genindex` +- :ref:`modindex` +- :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000000..78edea1db1 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,190 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\libsass.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\libsass.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +:end diff --git a/docs/sass.rst b/docs/sass.rst new file mode 100644 index 0000000000..964ffc10e2 --- /dev/null +++ b/docs/sass.rst @@ -0,0 +1,49 @@ +.. module:: sass + +:mod:`sass` --- Binding of ``libsass`` +====================================== + +This simple C extension module provides a very simple binding of ``libsass``, +which is written in C/C++. It contains only one function and one exception +type. + +>>> import sass +>>> sass.compile(string='a { b { color: blue; } }') +'a b {\n color: blue; }\n' + +.. function:: compile(string, filename, output_style, include_paths, image_path) + + It takes a source ``string`` or a ``filename`` and returns the compiled + CSS string. + + :param string: SASS source code to compile. it's exclusive to + ``filename`` parameter + :type string: :class:`str` + :param filename: the filename of SASS source code to compile. + it's exclusive to ``string`` parameter + :type filename: :class:`str` + :param output_style: an optional coding style of the compiled result. + choose one in: ``'nested'`` (default), ``'expanded'``, + ``'compact'``, ``'compressed'`` + :type output_style: :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` + :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 + cannot be read + +.. data:: OUTPUT_STYLES + + (:class:`collections.Mapping`) The dictionary of output styles. + Keys are output name strings, and values are flag integers. + +.. exception:: CompileError + + The exception type that is raised by :func:`compile()`. It is a subtype + of :exc:`exceptions.ValueError`. diff --git a/docs/sassc.rst b/docs/sassc.rst new file mode 100644 index 0000000000..27f2aa4c9c --- /dev/null +++ b/docs/sassc.rst @@ -0,0 +1,5 @@ + +.. program:: sassc + +.. automodule:: sassc + :members: diff --git a/docs/sassutils.rst b/docs/sassutils.rst new file mode 100644 index 0000000000..680f23672c --- /dev/null +++ b/docs/sassutils.rst @@ -0,0 +1,10 @@ + +.. automodule:: sassutils + + .. toctree:: + :maxdepth: 2 + + sassutils/builder + sassutils/distutils + sassutils/utils + sassutils/wsgi diff --git a/docs/sassutils/builder.rst b/docs/sassutils/builder.rst new file mode 100644 index 0000000000..1234e94fcd --- /dev/null +++ b/docs/sassutils/builder.rst @@ -0,0 +1,3 @@ + +.. automodule:: sassutils.builder + :members: diff --git a/docs/sassutils/distutils.rst b/docs/sassutils/distutils.rst new file mode 100644 index 0000000000..ff90702860 --- /dev/null +++ b/docs/sassutils/distutils.rst @@ -0,0 +1,3 @@ + +.. automodule:: sassutils.distutils + :members: diff --git a/docs/sassutils/utils.rst b/docs/sassutils/utils.rst new file mode 100644 index 0000000000..d85c95f039 --- /dev/null +++ b/docs/sassutils/utils.rst @@ -0,0 +1,3 @@ + +.. automodule:: sassutils.utils + :members: diff --git a/docs/sassutils/wsgi.rst b/docs/sassutils/wsgi.rst new file mode 100644 index 0000000000..27d1199e1c --- /dev/null +++ b/docs/sassutils/wsgi.rst @@ -0,0 +1,3 @@ + +.. automodule:: sassutils.wsgi + :members: diff --git a/document.cpp b/document.cpp index 4e57071930..d87639382d 100644 --- a/document.cpp +++ b/document.cpp @@ -10,6 +10,7 @@ #include #include #include +#include namespace Sass { diff --git a/sass.c b/sass.c new file mode 100644 index 0000000000..71c9d3bd63 --- /dev/null +++ b/sass.c @@ -0,0 +1,305 @@ +#include +#include +#include "sass_interface.h" + +static struct { + char *label; + int value; +} PySass_output_style_enum[] = { + {"nested", SASS_STYLE_NESTED}, + {"expanded", SASS_STYLE_EXPANDED}, + {"compact", SASS_STYLE_COMPACT}, + {"compressed", SASS_STYLE_COMPRESSED}, + {NULL} +}; + +static PyObject *PySass_CompileError; + +static PyObject * +PySass_compile(PyObject *self, PyObject *args, PyObject *kwds) +{ + PyObject *string, *filename, *dirname, *search_path, *output_path, + *output_style, *include_paths, *image_path, + *result, *item; + int expected_kwds, output_style_v; + char *filename_v, *include_paths_v, *image_path_v, *item_buffer; + Py_ssize_t include_paths_num, include_paths_size, i, offset, item_size; + union { + struct sass_context *string; + struct sass_file_context *filename; + struct sass_folder_context *dirname; + } context; + + if (PyTuple_Size(args)) { + PyErr_SetString(PyExc_TypeError, "compile() takes only keywords"); + return NULL; + } + if (PyDict_Size(kwds) < 1) { + PyErr_SetString(PyExc_TypeError, + "compile() requires one of string, filename, or " + "dirname"); + return NULL; + } + + expected_kwds = 1; + string = PyDict_GetItemString(kwds, "string"); + filename = PyDict_GetItemString(kwds, "filename"); + dirname = PyDict_GetItemString(kwds, "dirname"); + + if (string == NULL && filename == NULL && dirname == NULL) { + PyErr_SetString(PyExc_TypeError, + "compile() requires one of string, filename, or " + "dirname"); + return NULL; + } + if (string != NULL && !(filename == NULL && dirname == NULL) || + filename != NULL && !(string == NULL && dirname == NULL) || + dirname != NULL && !(string == NULL && filename == NULL)) { + PyErr_SetString(PyExc_TypeError, + "string, filename, and dirname arguments are " + "exclusive for each other. use only one at a time"); + return NULL; + } + + output_style = PyDict_GetItemString(kwds, "output_style"); + include_paths = PyDict_GetItemString(kwds, "include_paths"); + image_path = PyDict_GetItemString(kwds, "image_path"); + + if (output_style == NULL || output_style == Py_None) { + output_style_v = SASS_STYLE_NESTED; + } + else if (PyString_Check(output_style)) { + item_size = PyString_Size(output_style); + if (item_size) { + for (i = 0; PySass_output_style_enum[i].label; ++i) { + if (0 == strncmp(PyString_AsString(output_style), + PySass_output_style_enum[i].label, + item_size)) { + output_style_v = PySass_output_style_enum[i].value; + break; + } + } + } + if (PySass_output_style_enum[i].label == NULL) { + PyErr_SetString(PyExc_ValueError, "invalid output_style option"); + return NULL; + } + ++expected_kwds; + } + else { + PyErr_SetString(PyExc_TypeError, "output_style must be a string"); + return NULL; + } + + if (include_paths == NULL || include_paths == Py_None) { + include_paths_v = ""; + } + else if (PyString_Check(include_paths)) { + include_paths_v = PyString_AsString(include_paths); + ++expected_kwds; + } + else if (PySequence_Check(include_paths)) { + include_paths_num = PySequence_Size(include_paths); + include_paths_size = 0; + for (i = 0; i < include_paths_num; ++i) { + item = PySequence_GetItem(include_paths, i); + if (item == NULL) { + return NULL; + } + if (!PyString_Check(item)) { + PyErr_Format(PyExc_TypeError, + "include_paths must consists of only strings, " + "but #%zd is not a string", i); + return NULL; + } + include_paths_size += PyString_Size(item); + } + // add glue chars + if (include_paths_num > 1) { + include_paths_size += include_paths_num - 1; + } + include_paths_v = malloc(sizeof(char) * (include_paths_size + 1)); + // join + offset = 0; + for (i = 0; i < include_paths_num; ++i) { + if (i) { + include_paths_v[offset] = ':'; + ++offset; + } + item = PySequence_GetItem(include_paths, i); + PyString_AsStringAndSize(item, &item_buffer, &item_size); + strncpy(include_paths_v + offset, item_buffer, item_size); + offset += item_size; + } + include_paths_v[include_paths_size] = '\0'; + } + else { + PyErr_SetString(PyExc_TypeError, + "include_paths must be a list or a colon-separated " + "string"); + return NULL; + } + + if (image_path == NULL || image_path == Py_None) { + image_path_v = "."; + } + else if (PyString_Check(image_path)) { + image_path_v = PyString_AsString(image_path); + ++expected_kwds; + } + else { + PyErr_SetString(PyExc_TypeError, "image_path must be a string"); + return NULL; + } + + if (string) { + if (!PyString_Check(string)) { + PyErr_SetString(PyExc_TypeError, "string must be a string"); + result = NULL; + goto finalize; + } + + context.string = sass_new_context(); + context.string->source_string = PyString_AsString(string); + context.string->options.output_style = output_style_v; + context.string->options.include_paths = include_paths_v; + context.string->options.image_path = image_path_v; + + sass_compile(context.string); + + if (context.string->error_status) { + PyErr_SetString(PySass_CompileError, context.string->error_message); + result = NULL; + goto finalize_string; + } + + result = PyString_FromString(context.string->output_string); + +finalize_string: + sass_free_context(context.string); + goto finalize; + } + else if (filename) { + if (!PyString_Check(filename)) { + PyErr_SetString(PyExc_TypeError, "filename must be a string"); + result = NULL; + goto finalize; + } + + filename_v = PyString_AsString(filename); + + if (access(filename_v, R_OK) < 0) { + PyErr_Format(PyExc_IOError, + "filename '%s' cannot be read", + filename_v); + result = NULL; + goto finalize; + } + + context.filename = sass_new_file_context(); + context.filename->input_path = filename_v; + context.filename->options.output_style = output_style_v; + context.filename->options.include_paths = include_paths_v; + context.filename->options.image_path = image_path_v; + + sass_compile_file(context.filename); + + if (context.filename->error_status) { + PyErr_SetString(PySass_CompileError, + context.filename->error_message); + result = NULL; + goto finalize_filename; + } + + result = PyString_FromString(context.filename->output_string); + +finalize_filename: + sass_free_file_context(context.filename); + goto finalize; + } + else if (dirname) { + if (!PySequence_Check(dirname) || PySequence_Size(dirname) != 2) { + PyErr_SetString( + PySequence_Check(dirname) ? PyExc_ValueError: PyExc_TypeError, + "dirname must be a (search_path, output_path) pair" + ); + result = NULL; + goto finalize; + } + + search_path = PySequence_GetItem(dirname, 0); + output_path = PySequence_GetItem(dirname, 1); + + context.dirname = sass_new_folder_context(); + context.dirname->search_path = PyString_AsString(search_path); + context.dirname->output_path = PyString_AsString(output_path); + context.dirname->options.output_style = output_style_v; + context.dirname->options.include_paths = include_paths_v; + context.dirname->options.image_path = image_path_v; + + sass_compile_folder(context.dirname); + + if (context.dirname->error_status) { + PyErr_SetString(PySass_CompileError, + context.dirname->error_message); + result = NULL; + goto finalize_dirname; + } + + result = Py_None; + +finalize_dirname: + sass_free_folder_context(context.dirname); + goto finalize; + } + else { + PyErr_SetString(PyExc_RuntimeError, "something went wrong"); + goto finalize; + } + +finalize: + if (include_paths != NULL && PySequence_Check(include_paths)) { + free(include_paths_v); + } + return result; +} + +static PyMethodDef PySass_methods[] = { + {"compile", PySass_compile, METH_KEYWORDS, "Compile a SASS source."}, + {NULL, NULL, 0, NULL} +}; + +PyMODINIT_FUNC +initsass() +{ + PyObject *module, *version, *output_styles; + size_t i = 0; + + module = Py_InitModule3("sass", PySass_methods, + "The thin binding of libsass for Python."); + if (module == NULL) { + return; + } + + output_styles = PyDict_New(); + for (i = 0; PySass_output_style_enum[i].label; ++i) { + PyDict_SetItemString( + output_styles, + PySass_output_style_enum[i].label, + PyInt_FromLong((long) PySass_output_style_enum[i].value) + ); + } + PyModule_AddObject(module, "OUTPUT_STYLES", output_styles); + +#ifdef LIBSASS_PYTHON_VERSION + version = PyString_FromString(LIBSASS_PYTHON_VERSION); +#else + version = PyString_FromString("unknown"); +#endif + PyModule_AddObject(module, "__version__", version); + PySass_CompileError = PyErr_NewException("sass.CompileError", + PyExc_ValueError, + NULL); + Py_INCREF(PySass_CompileError); + PyModule_AddObject(module, "CompileError", PySass_CompileError); +} diff --git a/sass_interface.cpp b/sass_interface.cpp index 325c777a4f..cfa04b1d5a 100644 --- a/sass_interface.cpp +++ b/sass_interface.cpp @@ -42,6 +42,13 @@ extern "C" { sass_folder_context* sass_new_folder_context() { return (sass_folder_context*) calloc(1, sizeof(sass_folder_context)); } + void sass_free_folder_context(sass_folder_context* ctx) + { + if (ctx->error_message) free(ctx->error_message); + + free(ctx); + } + static char* process_document(Sass::Document& doc, int style) { using namespace Sass; diff --git a/sassc.py b/sassc.py new file mode 100755 index 0000000000..ff65ffea87 --- /dev/null +++ b/sassc.py @@ -0,0 +1,88 @@ +#!/usr/bin/env python +""":mod:`sassc` --- SassC compliant command line interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This provides SassC_ compliant CLI executable named :program:`sassc`: + +.. sourcecode:: console + + $ sassc + Usage: sassc [options] SCSS_FILE... + +There are options as well: + +.. option:: -s