Package: webresource
webresourceA resource registry for web applications.Webresource is a compact Python library to declare resources
(primarily Javascript and CSS files) for delivery in your web application.FeaturesDeclare web resources via python.Manage dependencies between resources.Grouping of resources.Conditional delivery of resources.Development and a production mode.Detailed DocumentationThe detailedwebresourcedocumentation is availablehere.Source CodeThe sources are in a GIT DVCS with its main branches atgithub.CopyrightCopyright (c) 2021-2022 Cone ContributorsContributorsRobert Niederreiter (Author)OverviewDeclaring resourcesWebresource provides 3 types of resources.ScriptResourceis used for
registering Javascript,StyleResourcefor CSS files andLinkResourcecan be used for registering all sorts of resource links.Declare a script:importwebresourceaswrmy_js=wr.ScriptResource(name='my_js',directory='/path/to/scripts',resource='my.js',compressed='my.min.js',path='js')nameis a unique identifier for the resource.directorydefines the
location in the file system where the resource can be found.resourceis
the default resource file corresponding to this declaration.compressedis
the minified version of the resource, which gets considered if Webresource
is used in production mode.pathdefines the path part of the URL at which
this resource is published.Dependencies between resources are defined by passingdependsargument,
which can be a single dependency or multiple dependencies as tuple or list:other_js=wr.ScriptResource(name='other_js',depends='my_js',...)It’s possible to pass a callback funtion asincludeargument. It can be
used to calculate whether a resource should be included or not:definclude_conditional_js():# Compute whether to include resource here.returnTrueconditional_js=wr.ScriptResource(name='conditional_js',include=include_conditional_js,...)Theincludeproperty can also be set as boolean which might be useful for
excluding some already registered resources:conditional_js.include=FalseResource URLs can be rendered including a unique key of the resource file.
This is useful in environments with strong caching to make sure changed
resources get reloaded properly. When working with unique resource URLs, the
unique key gets rendered intermediate between path and file name, thus the
integrator needs to implement custom URL rewriting/dispatching/traversal for
correct resource delivery:cached_js=wr.ScriptResource(name='cached_js',unique=True,unique_prefix='++webresource++',...)If external resources should be declared, passurlargument. In this casepath,resourceandcompressedget ignored:external_js=wr.ScriptResource(name='external_js',url='https://example.org/resource.js'...)It is possible to render additional attributes on resource tags by passing
additional keyword arguments to the constructor. This can be usefule when
working with web compilers like Diazo.custom_attr_js=wr.ScriptResource(name='custom_attr_js',**{'data-bundle':'bundle-name'})This examples usesScriptResourcebut the above described behavior applies
to all provided Resource types.Resource groupsResources can be grouped by adding them toResourceGroupobjects:scripts=wr.ResourceGroup(name='scripts')Resources can be added to a group at instantiation time if group is known in
advance.script=wr.ScriptResource(name='script',group=scripts...)or an already declared resource can be added to a group:scripts.add(script)Groups can be nested:scripts=wr.ResourceGroup(name='scripts')base_scripts=wr.ResourceGroup(name='base_scripts',group=scripts)addon_scripts=wr.ResourceGroup(name='addon_scripts',group=scripts)A group can define the defaultpathfor its members. It is taken unless
a contained group member defines a path on its own:scripts=wr.ResourceGroup(name='scripts',path='js')Same applies for the resourcedirectory. If defined on a resource group,
is taken unless a contained member overrides it.scripts=wr.ResourceGroup(name='scripts',directory='/path/to/scripts')To control whether an entire group should be included, define anincludecallback funtion or flag.definclude_group():# Compute whether to include resource group here.returnTruegroup=wr.ResourceGroup(name='group',include=include_group,...)Deliver resourcesWebresource not provides any mechanism to publish the declared resources.
It’s up to the user to make the resources in the defined directories available
to the browser at the defined paths.But it provides a renderer for the resulting resource HTML tags.First aResourceResolverneeds to be created knowing about the resources to
deliver.memberscan be an instance or list of resources or resource groups.TheResourceRendererthen is used to create the markup.TheGracefulResourceRenderercreates the markup, but does not fail if one
resource is invalid. It logs an error and places a comment about the failure
instead of a HTML-tag.A complete example:importwebresourceaswricon=wr.LinkResource(name='icon',resource='icon.png',rel='icon',type_='image/png')css=wr.StyleResource(name='css',resource='styles.css')ext_css=wr.StyleResource(name='ext_css',url='https://ext.org/styles.css')script=wr.ScriptResource(name='script',resource='script.js',compressed='script.min.js')resources=wr.ResourceGroup(name='resources',path='res')resources.add(icon)resources.add(css)resources.add(ext_css)resources.add(script)resolver=wr.ResourceResolver(resources)renderer=wr.ResourceRenderer(resolver,base_url='https://tld.org')rendered=renderer.render()renderedresults in:<linkhref="https://tld.org/res/icon.png"rel="icon"type="image/png"/><linkhref="https://tld.org/res/styles.css"media="all"rel="stylesheet"type="text/css"/><linkhref="https://ext.org/styles.css"media="all"rel="stylesheet"type="text/css"/><scriptsrc="https://tld.org/res/script.min.js"></script>DebuggingTo prevent Webresource generating links to the compressed versions of
declared resources,developmentflag of the config singleton needs to be
set:wr.config.development=TrueChangelog1.2 (2022-12-21)Accept additional keyword arguments in resources. They get rendered as
additional attributes on resource tag.
[rnix, aormazabal]1.1 (2022-07-01)Remove relative directory resolving.
[rnix]Addremovefunction toResourceMixin.
[rnix]Addcopyfunction toResourceMixin.
[rnix]Addscripts,styles, andlinksproperties toResourceGroup.
[rnix]Introduceparentattribute onResourceMixin. Gets set inResourceGroup.addmethod to provide hierarchy information.
[rnix]Remove magic path resolving behavior for resources. Path no longer gets
overwritten in resolver. It gets now aquired from parent if not set on
resource or resource group.
[rnix]LinkResourceandStyleResourcehave common superclassLinkMixinnow.StyleResourceno longer derives fromLinkResource. This way,
link and style resources respective subclasses of it can be differentiated
withisinstance.
[rnix]Removesizeskeyword argument fromStyleResourceconstructor.
[rnix]ResourceGroupcan define a directory for contained resources.
[rnix]Resource.directoryno longer gets set to package path by default but
remainsNone.
[rnix]Resources can define multiple dependencies.
[rnix]1.0 (2022-03-24)Add Tox, Github actions and make it run on Windows.
Modernize setup.[py|cfg].
[jensens]AddedGracefulResourceRenderer.
Fixes #1.
[jensens]1.0b8 (2021-09-23)Renamehash_keyword argument of resources tounique.Introduceunique_prefixkeyword argument on resources.Change behavior of unique URL generation. Unique key now gets rendered
itermediate between URL path and file name. This way we play nice with caching
servers, but this also implies the need of custom URL
dispatching/rewriting/traversal when working with unique resource URLs.1.0b7 (2021-08-16)Add auto integrity hash calculation onScriptResource.Addhash_andhash_algorithmkeyword arguments toResource,ScriptResource,LinkResourceandFileResource.AddResource.file_hashproperty.AddResource.file_dataproperty.1.0b6 (2021-08-10)Raise explicitResourceErrorinstead of genericValueError.1.0b5 (2021-08-09)MakeResource.directorya R/W property.1.0b4 (2021-08-08)Changepathcascading behavior. Path set onResourceGroupalways takes
precedence over its members paths.includeproperty ofResourceandResourceGroupcan be set from
outside.1.0b3 (2021-08-06)Add remaining missing rst files to release.1.0b2 (2021-08-06)Add missingdocs/source/overview.rstto release.1.0b1 (2021-08-06)Initial release.