Add useful finders for Pipeline assets

docs/storages.rst

@@ -26,6 +26,31 @@ Also available if you want versioning ::
 
   STATICFILES_STORAGE = 'pipeline.storage.NonPackagingPipelineCachedStorage'
 
+If you use staticfiles with ``DEBUG = False`` (i.e. for integration tests
+with `Selenium <http://docs.seleniumhq.org/>`_) you should install the finder
+that allows staticfiles to locate your outputted assets : ::
+
+  STATICFILES_FINDERS = (
+      'django.contrib.staticfiles.finders.FileSystemFinder',
+      'django.contrib.staticfiles.finders.AppDirectoriesFinder',
+      'pipeline.finders.PipelineFinder',
+  )
+
+If you use ``PipelineCachedStorage`` you may also like the ``CachedFileFinder``,
+which allows you to use integration tests with cached file URLs.
+
+If you want to exclude Pipelinable content from your collected static files,
+you can also use Pipeline's ``FileSystemFinder`` and ``AppDirectoriesFinder``.
+These finders will also exclude `unwanted` content like READMEs, tests and
+examples, which are particularly useful if you're collecting content from a
+tool like Bower. ::
+
+  STATICFILES_FINDERS = (
+      'pipeline.finders.FileSystemFinder',
+      'pipeline.finders.AppDirectoriesFinder',
+      'pipeline.finders.PipelineFinder',
+      'pipeline.finders.CachedFileFinder',
+  )
 
 Using with other storages
 =========================
@@ -45,3 +70,33 @@ Your storage only need to inherit from ``PipelineMixin`` and/or ``CachedFilesMix
 
   class S3PipelineStorage(PipelineMixin, CachedFilesMixin, S3BotoStorage):
        pass
+
+Using Pipeline with Bower
+=========================
+
+`Bower <http://bower.io/>`_ is a `package manager for the web` that allows
+you to easily include frontend components with named versions. Integrating
+Bower with Pipeline is straightforward.
+
+Add your Bower directory to your ``STATICFILES_DIRS`` : ::
+
+  STATICFILES_DIRS = (
+    os.path.join(os.path.dirname(__file__), '..', 'bower_components'),
+  )
+
+Then process the relevant content through Pipeline : ::
+
+  PIPELINE_JS = {
+    'components': {
+      'source_filenames: (
+        'jquery/jquery.js',
+        # you can choose to be specific to reduce your payload
+        'jquery-ui/ui/*.js',
+      ),
+      'output_filename': 'js/components.js',
+    },
+  }
+
+``pipeline.finders.FileSystemFinder`` will help you by excluding much of the
+extra content that Bower includes with its components, such as READMEs, tests
+and examples, while still including images, fonts, CSS fragments etc.

pipeline/finders.py

+from django.contrib.staticfiles.finders import BaseFinder, AppDirectoriesFinder, FileSystemFinder, find
+from django.utils._os import safe_join
+
+from pipeline.conf import settings
+
+
+class PipelineFinder(BaseFinder):
+    def find(self, path, all=False):
+        """
+        Looks for files in PIPELINE_CSS and PIPELINE_JS
+        """
+        matches = []
+        for elem in settings.PIPELINE_CSS.values() + settings.PIPELINE_JS.values():
+            if elem['output_filename'] == path:
+                match = safe_join(settings.PIPELINE_ROOT, path)
+                if not all:
+                    return match
+                matches.append(match)
+        return matches
+
+    def list(self, *args):
+        return []
+
+
+class CachedFileFinder(BaseFinder):
+    def find(self, path, all=False):
+        """
+        Work out the uncached name of the file and look that up instead
+        """
+        try:
+            start, _, extn = path.rsplit('.', 2)
+            path = '.'.join((start, extn))
+            return find(path, all=all)
+        except ValueError:
+            return []
+
+    def list(self, *args):
+        return []
+
+
+class PatternFilterMixin(object):
+    ignore_patterns = []
+
+    def get_ignored_patterns(self):
+        return list(set(self.ignore_patterns))
+
+    def list(self, ignore_patterns):
+        if ignore_patterns:
+            ignore_patterns = ignore_patterns + self.get_ignored_patterns()
+        return super(PatternFilterMixin, self).list(ignore_patterns)
+
+
+class AppDirectoriesFinder(PatternFilterMixin, AppDirectoriesFinder):
+    """
+    Like AppDirectoriesFinder, but doesn't return any additional ignored
+    patterns.
+
+    This allows us to concentrate/compress our components without dragging
+    the raw versions in via collectstatic.
+    """
+    ignore_patterns = [
+        '*.js',
+        '*.css',
+        '*.less',
+        '*.scss',
+    ]
+
+
+class FileSystemFinder(PatternFilterMixin, FileSystemFinder):
+    """
+    Like FileSystemFinder, but doesn't return any additional ignored patterns
+
+    This allows us to concentrate/compress our components without dragging
+    the raw versions in too.
+    """
+    ignore_patterns = [
+        '*.js',
+        '*.less',
+        '*.scss',
+        '*.sh',
+        '*.html',
+        '*.md',
+        '*.markdown',
+        '*.php',
+        '*.txt',
+        'README*',
+        'LICENSE*',
+        '*examples*',
+        '*test*',
+        '*bin*',
+        '*samples*',
+        '*docs*',
+        '*build*',
+        '*demo*',
+        'Makefile*',
+        'Gemfile*',
+    ]