API¶
WSGI components¶
- fanstatic.Fanstatic(app, publisher_signature='fanstatic', injector=None, **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
.injector – A injector callable.
**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, injector=None, **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 toNeededResources
.
- class fanstatic.Publisher(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:
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. Ifrecompute_hashes
is set toTrue
, 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>, compiler=<object object>, 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 theforce_bottom
option onNeededResources
).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.
dont_bundle – Don’t bundle this resource in any bundles (if bundling is enabled).
- mode(mode)¶
Get Resource in another mode.
If the mode is
None
or if the mode cannot be found, thisResource
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()
onResource
sometime during the rendering process of your web page, this resource and all its dependencies will be inserted as inclusions into the web page.
- render(library_url)¶
Render this renderable as something to insert in HTML.
This returns a snippet.
- class fanstatic.Slot(library, extension, depends=None, required=<object object>, 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, orGroup
instances.
- need(slots=None)¶
Need this group resource.
If you call
.need()
onGroup
sometime during the rendering process of your web page, all dependencies of this group resources will be inserted into the web page.
- class fanstatic.NeededResources(versioning=False, versioning_use_md5=False, recompute_hashes=True, base_url=None, script_name=None, publisher_signature='fanstatic', resources=None)¶
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 therecompute_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 toFalse
, the hash URLs will only be calculated once after server startup.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 aNeededResources
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/
.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
andbase_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:
- 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:
Registry
A dictionary-like registry of libraries.
This is a dictionary that maintains libraries. A value is a
Library
instance, and a key is its libraryname
.Normally there is only a single global LibraryRegistry, obtained by calling
get_library_registry()
.- Parameters:
libraries – a sequence of libraries
- clear() None. Remove all items from D. ¶
- class fanstatic.ConfigurationError¶
Bases:
Exception
Impossible or illegal configuration.
- class fanstatic.UnknownResourceError¶
Bases:
Exception
Resource refers to non-existent resource file.
- class fanstatic.UnknownResourceExtensionError¶
Bases:
Exception
A resource has an unrecognized extension.
- class fanstatic.LibraryDependencyCycleError¶
Bases:
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:
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 requiredSlot
toResource
.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(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.