Move core functionality out of management command and into library

vsalvino · vsalvino · commit 4345509aeaba · 2020-02-20T15:01:32.000-05:00
diff --git a/README.md b/README.md
@@ -178,14 +178,55 @@ django-sass only depends on libsass (which provides pre-built wheels for Windows
 and Linux), and of course Django (any version).
 
 
+Programmatically Compiling Sass
+-------------------------------
+
+You can also use `django-sass` in Python to programmatically compile the sass.
+This is useful for build scripts and static site generators.
+
+```python
+from django_sass import compile_sass
+
+# Compile scss and write to output file.
+compile_sass(
+    inpath="/path/to/file.scss",
+    outpath="/path/to/output.css",
+    output_style="compressed",
+    precision=8,
+    source_map=True
+)
+```
+
+For more advanced usage, you can specify additional sass search paths outside
+of your Django project by using the `include_paths` argument.
+
+```python
+from django_sass import compile_sass, find_static_paths
+
+# Get Django's static paths.
+dirs = find_static_paths()
+
+# Add external paths.
+dirs.append("/external/path/")
+
+# Compile scss and write to output file.
+compile_sass(
+    inpath="/path/to/file.scss",
+    outpath="/path/to/output.css",
+    output_style="compressed",
+    precision=8,
+    source_map=True,
+    include_paths=dirs,
+)
+```
+
 Contributing
 ------------
 
 To set up a development environment, first check out this repository, create a
 venv, then:
 
 ```
-(myvenv)$ pip install -e ./
 (myvenv)$ pip install -r requirements-dev.txt
 ```
 
@@ -196,6 +237,12 @@ Before committing, run static analysis tools:
 (myvenv)$ mypy
 ```
 
+Then run the unit tests:
+
+```
+(myvenv)$ pytest
+```
+
 
 Changelog
 ---------
diff --git a/django_sass/__init__.py b/django_sass/__init__.py
@@ -1 +1,123 @@
-__version__ = "0.2.0"
+from typing import Dict, List
+import os
+
+from django.contrib.staticfiles.finders import get_finders
+import sass
+
+
+def find_static_paths() -> List[str]:
+    """
+    Finds all static paths available in this Django project.
+
+    :returns:
+        List of paths containing static files.
+    """
+    found_paths = []
+    for finder in get_finders():
+        if hasattr(finder, "storages"):
+            for appname in finder.storages:
+                if hasattr(finder.storages[appname], "location"):
+                    abspath = finder.storages[appname].location
+                    found_paths.append(abspath)
+    return found_paths
+
+
+def find_static_scss() -> List[str]:
+    """
+    Finds all static scss files available in this Django project.
+
+    :returns:
+        List of paths of static scss files.
+    """
+    scss_files = []
+    for finder in get_finders():
+        for path, storage in finder.list([]):
+            if path.endswith(".scss"):
+                fullpath = finder.find(path)
+                scss_files.append(fullpath)
+    return scss_files
+
+
+def compile_sass(inpath: str, outpath: str, output_style: str = None, precision: int = None,
+                 source_map: bool = False, include_paths: List[str] = None) -> None:
+    """
+    Calls sass.compile() within context of Django's known static file paths,
+    and writes output CSS and/or sourcemaps to file.
+
+    :param str inpath:
+        Path to SCSS file or directory of SCSS files.
+    :param str outpath:
+        Path to a CSS file or directory in which to write output. The path will
+        be created if it does not exist.
+    :param str output_style:
+        Corresponds to `output_style` from sass package.
+    :param int precision:
+        Corresponds to `precision` from sass package.
+    :param bool source_map:
+        If True, write a source map along with the output CSS file.
+        Only valid when `inpath` is a file.
+    :returns:
+        None
+    """
+
+    # If include paths are not specified, use Django static paths
+    include_paths = include_paths or find_static_paths()
+
+    # Additional sass args that must be figured out.
+    sassargs = {}  # type: Dict[str, object]
+
+    # Handle input directories.
+    if os.path.isdir(inpath):
+        # Assume outpath is also a dir, or make it.
+        if not os.path.exists(outpath):
+            os.makedirs(outpath)
+        if os.path.isdir(outpath):
+            sassargs.update({"dirname": (inpath, outpath)})
+        else:
+            raise NotADirectoryError(
+                "Output path must also be a directory when input path is a directory."
+            )
+
+    # Handle input files.
+    outfile = None
+    if os.path.isfile(inpath):
+        sassargs.update({"filename": inpath})
+        if os.path.isdir(outpath):
+            outfile = os.path.join(
+                outpath, os.path.basename(inpath.replace(".scss", ".css"))
+            )
+        else:
+            outfile = outpath
+        if source_map:
+            sassargs.update({"source_map_filename": outfile + ".map"})
+
+    # Compile the sass.
+    rval = sass.compile(
+        output_style=output_style,
+        precision=precision,
+        include_paths=include_paths,
+        **sassargs,
+    )
+
+    # Write output.
+    # sass.compile() will return None if used with dirname.
+    # If used with filename, it will return a string of file contents.
+    if rval and outfile:
+        # If we got a css and sourcemap tuple, write the sourcemap.
+        if isinstance(rval, tuple):
+            map_outfile = outfile + ".map"
+            outfile_dir = os.path.dirname(map_outfile)
+            if not os.path.exists(outfile_dir):
+                os.makedirs(outfile_dir, exist_ok=True)
+            file = open(map_outfile, "w", encoding="utf8")
+            file.write(rval[1])
+            file.close()
+            rval = rval[0]
+
+        # Write the outputted css to file.
+        outfile_dir = os.path.dirname(outfile)
+        if not os.path.exists(outfile_dir):
+            os.makedirs(outfile_dir, exist_ok=True)
+        file = open(outfile, "w", encoding="utf8")
+        file.write(rval)
+        file.close()
diff --git a/django_sass/management/commands/sass.py b/django_sass/management/commands/sass.py
@@ -3,9 +3,10 @@
 import time
 
 from django.core.management.base import BaseCommand
-from django.contrib.staticfiles.finders import get_finders
 import sass
 
+from django_sass import compile_sass, find_static_scss
+
 
 class Command(BaseCommand):
     help = "Runs libsass including all paths from STATICFILES_FINDERS."
@@ -51,109 +52,66 @@ def add_arguments(self, parser):
             help="Watch input path and re-generate css files when scss files are changed.",
         )
 
-    def compile_sass(self, outfile: str, **kwargs) -> None:
-        rval = sass.compile(**kwargs)
-        # sass.compile() will return None if used with dirname.
-        # If used with filename, it will return a string of file contents.
-        if rval and outfile:
-            # If we got a css and sourcemap tuple, write the sourcemap.
-            if isinstance(rval, tuple):
-                map_outfile = outfile + ".map"
-                outfile_dir = os.path.dirname(map_outfile)
-                if not os.path.exists(outfile_dir):
-                    os.makedirs(outfile_dir, exist_ok=True)
-                file = open(map_outfile, "w", encoding="utf8")
-                file.write(rval[1])
-                file.close()
-                rval = rval[0]
-
-            # Write the outputted css to file.
-            outfile_dir = os.path.dirname(outfile)
-            if not os.path.exists(outfile_dir):
-                os.makedirs(outfile_dir, exist_ok=True)
-            file = open(outfile, "w", encoding="utf8")
-            file.write(rval)
-            file.close()
-
     def handle(self, *args, **options) -> None:
         """
         Finds all static paths used by the project, and runs sass
         including those paths.
         """
-        found_paths = []
-        for finder in get_finders():
-            if hasattr(finder, "storages"):
-                for appname in finder.storages:
-                    if hasattr(finder.storages[appname], "location"):
-                        abspath = finder.storages[appname].location
-                        found_paths.append(abspath)
-
-        sassargs = {"output_style": options["t"], "precision": options["p"]}
-        inpath = options["in"][0]
-        outpath = options["out"][0]
-        outfile = None
 
-        if found_paths:
-            sassargs.update({"include_paths": found_paths})
-
-        if os.path.isdir(inpath):
-            # Assume outpath is also a dir, or make it.
-            if not os.path.exists(outpath):
-                os.makedirs(outpath)
-            if os.path.isdir(outpath):
-                sassargs.update({"dirname": (inpath, outpath)})
-            else:
-                raise NotADirectoryError(
-                    "Output path must also be a directory when input path is a directory."
-                )
-
-        if os.path.isfile(inpath):
-            sassargs.update({"filename": inpath})
-            if os.path.isdir(outpath):
-                outfile = os.path.join(
-                    outpath, os.path.basename(inpath.replace(".scss", ".css"))
-                )
-            else:
-                outfile = outpath
-            if options["g"]:
-                sassargs.update({"source_map_filename": outfile + ".map"})
+        # Parse options.
+        o_inpath = options["in"][0]
+        o_outpath = options["out"][0]
+        o_srcmap = options["g"]
+        o_precision = options["p"]
+        o_style = options["t"]
 
         # Watch files for changes if specified.
         if options["watch"]:
             try:
                 self.stdout.write("Watching...")
+
+                # Track list of files to watch and their modified time.
                 watchfiles = {}
                 while True:
                     needs_updated = False
 
                     # Build/update list of ALL scss files in static paths.
-                    for finder in get_finders():
-                        for path, storage in finder.list([]):
-                            if path.endswith(".scss"):
-                                fullpath = finder.find(path)
-                                prev_mtime = watchfiles.get(fullpath, 0)
-                                curr_mtime = os.stat(fullpath).st_mtime
-                                if curr_mtime > prev_mtime:
-                                    needs_updated = True
-                                    watchfiles.update({fullpath: curr_mtime})
+                    for fullpath in find_static_scss():
+                        prev_mtime = watchfiles.get(fullpath, 0)
+                        curr_mtime = os.stat(fullpath).st_mtime
+                        if curr_mtime > prev_mtime:
+                            needs_updated = True
+                            watchfiles.update({fullpath: curr_mtime})
 
                     # Recompile the sass if needed.
                     if needs_updated:
                         # Catch compile errors to keep the watcher running.
                         try:
-                            self.compile_sass(outfile, **sassargs)
+                            compile_sass(
+                                inpath=o_inpath,
+                                outpath=o_outpath,
+                                output_style=o_style,
+                                precision=o_precision,
+                                source_map=o_srcmap,
+                            )
                             self.stdout.write("Updated files at %s" % time.time())
                         except sass.CompileError as exc:
                             self.stdout.write(str(exc))
 
                     # Go back to sleep.
                     time.sleep(3)
 
-            except KeyboardInterrupt:
+            except (KeyboardInterrupt, InterruptedError):
                 self.stdout.write("Bye.")
                 sys.exit(0)
 
         # Write css.
         self.stdout.write("Writing css...")
-        self.compile_sass(outfile, **sassargs)
+        compile_sass(
+            inpath=o_inpath,
+            outpath=o_outpath,
+            output_style=o_style,
+            precision=o_precision,
+            source_map=o_srcmap,
+        )
         self.stdout.write("Done.")
diff --git a/setup.cfg b/setup.cfg
@@ -8,7 +8,7 @@ ignore_missing_imports = True
 [tool:pytest]
 DJANGO_SETTINGS_MODULE = testproject.settings
 junit_family = xunit2
-addopts = --cov django_sass --cov-report html --cov-report xml --junitxml junit/test-results.xml
+addopts = --cov django_sass --cov-report html --cov-report xml --junitxml junit/test-results.xml ./testproject/
 python_files = tests.py test_*.py
 filterwarnings =
     ignore
diff --git a/setup.py b/setup.py
@@ -1,15 +1,13 @@
 import os
 from setuptools import setup, find_packages
 
-from django_sass import __version__
-
 
 with open(os.path.join(os.path.dirname(__file__), "README.md"), encoding="utf8") as readme:
     README = readme.read()
 
 setup(
     name="django-sass",
-    version=__version__,
+    version="0.2.0",
     author="CodeRed LLC",
     author_email="info@coderedcorp.com",
     url="https://github.com/coderedcorp/django-sass",
diff --git a/testproject/tests.py b/testproject/tests.py
