class Version( six.with_metaclass( RegistryMetaclass(clazz=lambda: Version, attribute='determine_version', desc='a version implementation'))): """A Version class that can be assigned to the ``Environment.versioner`` attribute. Given a bundle, this must determine its "version". This version can then be used in the output filename of the bundle, or appended to the url as a query string, in order to expire cached assets. A version could be a timestamp, a content hash, or a git revision etc. As a user, all you need to care about, in most cases, is whether you want to set the ``Environment.versioner`` attribute to ``hash`` or ``timestamp``. A single instance can be used with different environments. """ def determine_version(self, bundle, ctx, hunk=None): """Return a string that represents the current version of the given bundle. This method is called on two separate occasions: 1) After a bundle has been built and is about to be saved. If the output filename contains a placeholder, this method is asked for the version. This mode is indicated by the ``hunk`` argument being available. 2) When a version is required for an already built file, either because: *) An URL needs to be constructed. *) It needs to be determined if a bundle needs an update. *This will only occur* if *no manifest* is used. If there is a manifest, it would be used to determine the version instead. Support for option (2) is optional. If not supported, then in those cases a manifest needs to be configured. ``VersionIndeterminableError`` should be raised with a message why. """ raise NotImplementedError() def set_version(self, bundle, ctx, filename, version): """Hook called after a bundle has been built. Some version classes
class BaseUpdater(six.with_metaclass(RegistryMetaclass( clazz=lambda: BaseUpdater, attribute='needs_rebuild', desc='an updater implementation'))): """Base updater class. Child classes that define an ``id`` attribute are accessible via their string id in the configuration. A single instance can be used with different environments. """ def needs_rebuild(self, bundle, env): """Returns ``True`` if the given bundle needs to be rebuilt, ``False`` otherwise. """ raise NotImplementedError() def build_done(self, bundle, env): """This will be called once a bundle has been successfully built.
class Manifest( six.with_metaclass( RegistryMetaclass(clazz=lambda: Manifest, desc='a manifest implementation'))): """Persists information about the versions bundles are at. The Manifest plays a role only if you insert the bundle version in your output filenames, or append the version as a querystring to the url (via the url_expire option). It serves two purposes: - Without a manifest, it may be impossible to determine the version at runtime. In a deployed app, the media files may be stored on a different server entirely, and be inaccessible from the application code. The manifest, if shipped with your application, is what still allows to construct the proper URLs. - Even if it were possible to determine the version at runtime without a manifest, it may be a costly process, and using a manifest may give you better performance. If you use a hash-based version for example, this hash would need to be recalculated every time a new process is started. (*) (*) It needs to happen only once per process, because Bundles are smart enough to cache their own version in memory. A special case is the ``Environment.auto_build`` option. A manifest implementation should re-read its data from its out-of-process data source on every request, if ``auto_build`` is enabled. Otherwise, if your application is served by multiple processes, then after an automatic rebuild in one process all other processes would continue to serve an old version of the file (or attach an old version to the query string). A manifest instance is currently not guaranteed to function correctly with multiple Environment instances. """ def remember(self, bundle, ctx, version): raise NotImplementedError() def query(self, bundle, ctx): raise NotImplementedError()
class ExternalTool(six.with_metaclass(ExternalToolMetaclass, Filter)): """Subclass that helps creating filters that need to run an external program. You are encouraged to use this when possible, as it helps consistency. In the simplest possible case, subclasses only have to define one or more of the following attributes, without needing to write any code: ``argv`` The command line that will be passed to subprocess.Popen. New-style format strings can be used to access all kinds of data: The arguments to the filter method, as well as the filter instance via ``self``: argv = ['{self.binary}', '--input', '{source_path}', '--cwd', '{self.env.directory}'] ``method`` The filter method to implement. One of ``input``, ``output`` or ``open``. """ argv = [] method = None def open(self, out, source_path, **kw): self._evaluate([out, source_path], kw, out) def input(self, _in, out, **kw): self._evaluate([_in, out], kw, out, _in) def output(self, _in, out, **kw): self._evaluate([_in, out], kw, out, _in) def _evaluate(self, args, kwargs, out, data=None): # For now, still support Python 2.5, but the format strings in argv # are not supported (making the feature mostly useless). For this # reason none of the builtin filters is using argv currently. if hasattr(str, 'format'): # Add 'self' to the keywords available in format strings kwargs = kwargs.copy() kwargs.update({'self': self}) # Resolve all the format strings in argv def replace(arg): try: return arg.format(*args, **kwargs) except KeyError as e: # Treat "output" and "input" variables special, they # are dealt with in :meth:`subprocess` instead. if e.args[0] not in ('input', 'output'): raise return arg argv = list(map(replace, self.argv)) else: argv = self.argv self.subprocess(argv, out, data=data) @classmethod def subprocess(cls, argv, out, data=None): """Execute the commandline given by the list in ``argv``. If a byestring is given via ``data``, it is piped into data. ``argv`` may contain two placeholders: ``{input}`` If given, ``data`` will be written to a temporary file instead of data. The placeholder is then replaced with that file. ``{output}`` Will be replaced by a temporary filename. The return value then will be the content of this file, rather than stdout. """ class tempfile_on_demand(object): def __repr__(self): if not hasattr(self, 'filename'): self.fd, self.filename = tempfile.mkstemp() return self.filename @property def created(self): return hasattr(self, 'filename') # Replace input and output placeholders input_file = tempfile_on_demand() output_file = tempfile_on_demand() if hasattr(str, 'format'): # Support Python 2.5 without the feature argv = list( map( lambda item: item.format(input=input_file, output=output_file), argv)) try: data = (data.read() if hasattr(data, 'read') else data) if data is not None: data = data.encode('utf-8') if input_file.created: if not data: raise ValueError( '{input} placeholder given, but no data passed') with os.fdopen(input_file.fd, 'wb') as f: f.write(data) # No longer pass to stdin data = None proc = subprocess.Popen( argv, # we cannot use the in/out streams directly, as they might be # StringIO objects (which are not supported by subprocess) stdout=subprocess.PIPE, stdin=subprocess.PIPE, stderr=subprocess.PIPE, shell=os.name == 'nt') stdout, stderr = proc.communicate(data) if proc.returncode: raise FilterError( '%s: subprocess returned a non-success result code: ' '%s, stdout=%s, stderr=%s' % (cls.name or cls.__name__, proc.returncode, stdout, stderr)) else: if output_file.created: with open(output_file.filename, 'rb') as f: out.write(f.read().decode('utf-8')) else: out.write(stdout.decode('utf-8')) finally: if output_file.created: os.unlink(output_file.filename) if input_file.created: os.unlink(input_file.filename)