API

WSGI components

fanstatic.Fanstatic(app, publisher_signature='fanstatic', **config)

Fanstatic WSGI framework component.

Parameters:

• app – The WSGI app to wrap with Fanstatic.
• publisher_signature – Optional argument to define the signature of the publisher in a URL. The default is fanstatic.
• **config – Optional keyword arguments. These are passed to NeededInclusions when it is constructed.

fanstatic.Serf(resource)

Serf WSGI application.

Serve a very simple HTML page while needing a resource. Can be configured behind the Fanstatic() WSGI framework component to let the resource be included.

Parameters:resource – The Resource to include.

class fanstatic.Injector(app, **config)

Fanstatic injector WSGI framework component.

This WSGI component takes care of injecting the proper resource inclusions into HTML when needed.

This WSGI component is used automatically by the Fanstatic() WSGI framework component, but can also be used independently if you need more control.

Parameters:

• app – The WSGI app to wrap with the injector.
• **config – Optional keyword arguments. These are passed to NeededResources when it is constructed. It also makes sure that when initialized, it isn’t given any configuration parameters that cannot be passed to NeededResources.

class fanstatic.Publisher(library_registry)

Fanstatic publisher WSGI application.

This WSGI application serves Fanstatic Library instances. Libraries are published as <library_name>/<optional_version>/path/to/resource.js.

All static resources contained in the libraries will be published to the web. If a step prefixed with :version: appears in the URL, this will be automatically skipped, and the HTTP response will indicate the resource can be cached forever.

This WSGI component is used automatically by the Fanstatic() WSGI framework component, but can also be used independently if you need more control.

Parameters:library_registry – an instance of LibraryRegistry with those resource libraries that should be published.

class fanstatic.LibraryPublisher(library)

Fanstatic directory publisher WSGI application.

This WSGI application serves a directory of static resources to the web.

This WSGI component is used automatically by the Fanstatic() WSGI framework component, but can also be used independently if you need more control.

Parameters:library – The fanstatic library instance.

class fanstatic.Delegator(app, publisher, publisher_signature='fanstatic')

Fanstatic delegator WSGI framework component.

This WSGI component recognizes URLs that point to Fanstatic libraries, and delegates them to the Publisher WSGI application.

In order to recognize such URLs it looks for occurrences of the publisher_signature parameter as a URL step. By default it looks for /fanstatic/.

This WSGI component is used automatically by the Fanstatic() WSGI framework component, but can also be used independently if you need more control.

Parameters:

• app – The WSGI app to wrap with the delegator.
• publisher – An instance of the Publisher component.
• publisher_signature – Optional argument to define the signature of the publisher in a URL. The default is fanstatic.

Python components

class fanstatic.Library(name, rootpath, ignores=None, version=None, compilers=None, minifiers=None)

The resource library.

This object defines which directory is published and can be referred to by Resource objects to describe these resources.

Parameters:

• name – A string that uniquely identifies this library.
• rootpath – An absolute or relative path to the directory that contains the static resources this library publishes. If relative, it will be relative to the directory of the module that initializes the library.
• ignores – A list of globs used to determine which files and directories not to publish.

init_library_nr()

This can only be called once all resources are known.

i.e. once sort_resources is called this can be called. once library numbers are calculated once this will be done very quickly.

path = None

The absolute path to the directory which contains the static resources this library publishes.

register(resource)

Register a Resource with this Library.

A Resource knows about its Library. After a Resource has registered itself with its Library, the Library knows about the Resources associated to it.

signature(recompute_hashes=False, version_method=None)

Get a unique signature for this Library.

If a version has been defined, we return the version.

If no version is defined, a hash of the contents of the directory indicated by path is calculated. If recompute_hashes is set to True, the signature will be recalculated each time, which is useful during development when changing Javascript/css code and images.

class fanstatic.Resource(library, relpath, depends=None, supersedes=None, bottom=False, renderer=None, debug=None, dont_bundle=False, minified=None, minifier=<object object at 0x208eb30>, compiler=<object object at 0x208eb30>, source=None, mode_parent=None)

A resource.

A resource specifies a single resource in a library so that it can be included in a web page. This is useful for Javascript and CSS resources in particular. Some static resources such as images are not included in this way and therefore do not have to be defined this way.

Parameters:

• library – the Library this resource is in.
• relpath – the relative path (from the root of the library path) that indicates the actual resource file.
• depends – optionally, a list of resources that this resource depends on. Entries in the list are Resource instances.
• supersedes – optionally, a list of Resource instances that this resource supersedes as a rollup resource. If all these resources are required for render a page, the superseding resource will be included instead.
• bottom – indicate that this resource is “bottom safe”: it can be safely included on the bottom of the page (just before </body>). This can be used to improve the performance of page loads when Javascript resources are in use. Not all Javascript-based resources can however be safely included that way, so you have to set this explicitly (or use the force_bottom option on NeededResources).
• renderer – optionally, a callable that accepts an URL argument and returns a rendered HTML snippet for this resource. If no renderer is provided, a renderer is looked up based on the resource’s filename extension.
• debug – optionally, a debug version of the resource. The argument is a Resource instance, or a string that indicates a relative path to the resource. In the latter case a Resource instance is constructed that has the same library as the resource.
• dont_bundle – Don’t bundle this resource in any bundles (if bundling is enabled).
• minified – optionally, a minified version of the resource. The argument is a Resource instance, or a string that indicates a relative path to the resource. In the latter case a Resource instance is constructed that has the same library as the resource.

mode(mode)

Get Resource in another mode.

If the mode is None or if the mode cannot be found, this Resource instance is returned instead.

Parameters:mode – a string indicating the mode, or None.

need(slots=None)

Declare that the application needs this resource.

If you call .need() on Resource sometime during the rendering process of your web page, this resource and all its dependencies will be inserted as inclusions into the web page.

Parameters:slots – an optional dictionary mapping from Slot instances to Resource instances. This dictionary describes how to fill in the slots that this resource might depend on (directly or indirectly). If a slot is required, the dictionary must contain an entry for it.

class fanstatic.Slot(library, extension, depends=None, required=<object object at 0x208eb40>, default=None)

A resource slot.

Sometimes only the application has knowledge on how to fill in a dependency for a resource, and this cannot be known at resource definition time. In this case you can define a slot, and make your resource depend on that. This slot can then be filled in with a real resource by the application when you .need() that resource (or when you need something that depends on the slot indirectly).

Parameters:

• library – the Library this slot is in.
• ext – the extension of the slot, for instance ‘.js’. This determines what kind of resources can be slotted in here.
• required – a boolean indicating whether this slot is required to be filled in when a resource that depends on a slot is needed, or whether it’s optional. By default filling in a slot is required.
• depends – optionally, a list of resources that this slot depends on. Resources that are slotted in here need to have the same dependencies as that of the slot, or a strict subset.

class fanstatic.Group(depends)

A resource used to group resources together.

It doesn’t define a resource file itself, but instead depends on other resources. When a Group is depended on, all the resources grouped together will be included.

Parameters:depends – a list of resources that this resource depends on. Entries in the list can be Resource instances, or Group instances.

need(slots=None)

Need this group resource.

If you call .need() on Group sometime during the rendering process of your web page, all dependencies of this group resources will be inserted into the web page.

Parameters:slots – an optional dictionary mapping from Slot instances to Resource instances. This dictionary describes how to fill in the slots that this resource might depend on (directly or indirectly). If a slot is required, the dictionary must contain an entry for it.

class fanstatic.NeededResources(versioning=False, versioning_use_md5=False, recompute_hashes=True, bottom=False, force_bottom=False, minified=False, debug=False, rollup=False, base_url=None, script_name=None, publisher_signature='fanstatic', bundle=False, resources=None, compile=False)

The current selection of needed resources..

The NeededResources instance maintains a set of needed resources for a particular web page.

Parameters:

• versioning – If True, Fanstatic will automatically include a version identifier in all URLs pointing to resources. Since the version identifier will change when you update a resource, the URLs can both be infinitely cached and the resources will always be up to date. See also the recompute_hashes parameter.
• versioning_use_md5 – If True, Fanstatic will use and md5 algorithm instead of an algorithm based on the last modification time of the Resource files to compute versions. Use md5 if you don’t trust your filesystem.
• recompute_hashes – If True and versioning is enabled, Fanstatic will recalculate hash URLs on the fly whenever you make changes, even without restarting the server. This is useful during development, but slower, so should be turned off during deployment. If set to False, the hash URLs will only be calculated once after server startup.
• bottom – If set to True, Fanstatic will include any resource that has been marked as “bottom safe” at the bottom of the web page, at the end of <body>, as opposed to in the <head> section. This is useful for optimizing the load-time of Javascript resources.
• force_bottom – If set to True and bottom is set to True as well, all Javascript resources will be included at the bottom of a web page, even if they aren’t marked bottom safe.
• minified – If set to True, Fanstatic will include all resources in minified form. If a Resource instance does not provide a minified mode, the “main” (non-named) mode is used.
• debug – If set to True, Fanstatic will include all resources in debug form. If a Resource instance does not provide a debug mode, the “main” (non-named) mode is used. An exception is raised when both the debug and minified parameters are True.
• rollup – If set to True (default is False) rolled up combined resources will be served if they exist and supersede existing resources that are needed.
• base_url – This URL will be prefixed in front of all resource URLs. This can be useful if your web framework wants the resources to be published on a sub-URL. By default, there is no base_url, and resources are served in the script root. Note that this can also be set with the set_base_url method on a NeededResources instance.
• script_name – The script_name is a fallback for computing library URLs. The base_url parameter should be honoured if it is provided.
• publisher_signature – The name under which resource libraries should be served in the URL. By default this is fanstatic, so URLs to resources will start with /fanstatic/.
• bundle – If set to True, Fanstatic will attempt to bundle resources that fit together into larger Bundle objects. These can then be rendered as single URLs to these bundles.
• resources – Optionally, a list of resources we want to include. Normally you specify resources to include by calling .need() on them, or alternatively by calling .need() on an instance of this class.

has_base_url()

Returns True if base_url has been set.

has_resources()

Returns True if any resources are needed.

library_url(library)

Construct URL to library.

This constructs a URL to a library, obey versioning and base_url configuration.

Parameters:library – A Library instance.

need(resource, slots=None)

Add a particular resource to the needed resources.

This is an alternative to calling .need() on the resource directly.

Parameters:

• resource – A Resource instance.
• slots – an optional dictionary mapping from Slot instances to Resource instances. This dictionary describes how to fill in the slots that the given resource might depend on (directly or indirectly). If a slot is required, the dictionary must contain an entry for it.

render()

Render needed resource inclusions.

This returns a string with the rendered resource inclusions (<script> and <link> tags), suitable for including in the <head> section of a web page.

render_inclusions(resources)

Render a set of resources as inclusions.

This renders the listed inclusions and their dependencies as HTML ((<script> and <link> tags), suitable for inclusion on a web page.

Parameters:inclusions – A list of Resource instances.

render_into_html(html)

Render needed resource inclusions into HTML.

Parameters:html – A string with HTML to render the resource inclusions into. This string must have a <head> section.

render_topbottom()

Render resource inclusions separately into top and bottom fragments.

Returns a tuple of two HTML snippets, top and bottom. The top one is to be included in a <head> section, and the bottom one is to be included at the end of the <body> section. Only bottom safe resources are included in the bottom section, unless force_bottom is enabled, in which case all Javascript resources will be included in the bottom.

render_topbottom_into_html(html)

Render needed resource inclusions into HTML.

Only bottom safe resources are included in the bottom section, unless force_bottom is enabled, in which case all Javascript resources will be included in the bottom, just before the </body> tag.

Parameters:html – The HTML string in which to insert the rendered resource inclusions. This string must have a <head> and a <body> section.

resources()

Retrieve the list of resources needed.

This returns the needed Resource instances. Resources are guaranteed to come earlier in the list than those resources that depend on them.

Resources are also sorted by extension.

set_base_url(url)

Set the base_url. The base_url can only be set (1) if it has not been set in the NeededResources configuration and (2) if it has not been set before using this method.

class fanstatic.LibraryRegistry(items=())

Bases: fanstatic.registry.Registry

A dictionary-like registry of libraries.

This is a dictionary that mains libraries. A value is a Library instance, and a key is its library name.

Normally there is only a single global LibraryRegistry, obtained by calling get_library_registry().

Parameters:libraries – a sequence of libraries

class fanstatic.ConfigurationError

Bases: exceptions.Exception

Impossible or illegal configuration.

class fanstatic.UnknownResourceError

Bases: exceptions.Exception

Resource refers to non-existent resource file.

class fanstatic.UnknownResourceExtensionError

Bases: exceptions.Exception

A resource has an unrecognized extension.

class fanstatic.LibraryDependencyCycleError

Bases: exceptions.Exception

Dependency cycles between libraries aren’t allowed.

A dependency cycle between libraries occurs when the file in one library depends on a file in another library, while that library depends on a file in the first library.

class fanstatic.SlotError

Bases: exceptions.Exception

A slot was filled in incorrectly.

If a slot is required, it must be filled in by passing an extra dictionary parameter to the .need method, containing a mapping from the required Slot to Resource.

When a slot is filled, the resource filled in should have the same dependencies as the slot, or a subset of the dependencies of the slot. It should also have the same extension as the slot. If this is not the case, it is an error.

Functions

fanstatic.register_inclusion_renderer(self, extension, renderer, order=None)

Register a renderer function for a given filename extension.

Parameters:

• extension – the filename extension to register the renderer for.
• renderer – a callable that should accept a URL argument and return a rendered HTML snippet for this resource.
• order – optionally, to control the order in which the snippets are included in the HTML document. If no order is given, the resource will be included after all other resource inclusions. The lower the order number, the earlier in the rendering the inclusion will appear.

fanstatic.set_resource_file_existence_checking(v)

Set resource file existence checking to True or False.

By default, this is set to True, so that resources that point to non-existent files will result in an error. We recommend you keep it at this value when using Fanstatic. An UnknownResourceError will then be raised if you accidentally refer to a non-existent resource.

When running tests it’s often useful to make fake resources that don’t really have a filesystem representation, so this is set to False temporarily; for the Fanstatic tests this is done. Inside a test for this particular feature, this can temporarily be set to True.