Skip to main content

Deliver web resources

Project description

webresource

A resource registry for you Web Application.

webresource is a small library for defining and registering resources (primarily Javascript and CSS files) to deliver in your Web Application.

Features

  • Register web resources via python.

  • Manage dependencies between resources.

  • Grouping of resources.

  • Conditional delivery of resources.

  • Develoment and a production mode.

Contributors

  • Robert Niederreiter (Author)

Overview

Declaring resources

webresource provides 3 types of resources. ScriptResource is used for registering Javascript, StyleResource for CSS files and LinkResource can be used for registering all sorts of resource links.

Declare a script:

import webresource as wr

my_js = wr.ScriptResource(
    name='my_js',
    directory='./bundle',
    resource='my.js',
    compressed='my.min.js',
    path='js'
)

name is a unique identifier for the resource. directory defines the location n the file system where the resource can be found. resource is the default resource file corresponding to this declaration. compressed is the minified version of the resource, which gets considered if webresource is used in production mode. path defines the path part of the URL at which this resource is published.

Dependencies between resources are defined by passing depends argument:

other_js = wr.ScriptResource(
    name='other_js',
    depends='my_js',
    ...
)

It’s possible to pass a callback funtion as include argument. It can be used to calculate whether a resource should be included or not:

def include_conditional_js():
    # Compute whether to include resource here.
    return True

conditional_js = wr.ScriptResource(
    name='conditional_js',
    include=include_conditional_js,
    ...
)

The include property can also be set as boolean which might be useful for excluding some already registered resources:

conditional_js.include = False

If external resources should be declared, pass url argument. In this case path, resource and compressed get ignored:

external_js = wr.ScriptResource(
    name='external_js',
    url='https://example.org/resource.js'
    ...
)

This examples uses ScriptResource but the above described behavior applies to all provided Resource types.

Resource groups

Resources can be grouped by adding them to ResourceGroup objects:

scripts = wr.ResourceGroup(name='scripts')

Resources can be added to a group at instanciation 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 be used to define the path for all resources inside the group. This applies only if contained groups not define path on it’s own:

scripts = wr.ResourceGroup(name='scripts', path='js')

This also works for nested groups.

Deliver resources

webresource 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 a ResourceResolver needs to be created knowing about the resources to deliver. members can be an instance or list of resources or resource groups

The ResourceRenderer then is uses to create the markup.

A complete example:

import webresource as wr

icon = wr.LinkResource(
    name='icon',
    resource='icon.png',
    rel='icon',
    type_='image/png'
)

css = wr.StyleResource(name='css', resource='styles.css')

ext_css = wr.StyleResource(
    'ext_css',
    url='https://ext.org/styles.css'
)

script = wr.ScriptResource(
    'script',
    resource='script.js',
    compressed='script.min.js'
)

resources = wr.ResourceGroup('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://example.com'
)

rendered = renderer.render()

rendered results in:

<link href="https://example.com/res/icon.png"
      rel="icon" type="image/png" />
<link href="https://example.com/res/styles.css" media="all"
      rel="stylesheet" type="text/css" />
<link href="https://ext.org/styles.css" media="all"
      rel="stylesheet" type="text/css" />
<script src="https://example.com/res/script.min.js"></script>

Debugging

To prevent webresource generating links to the compressed versions of declared resources, development flag of the config singletion needs to be set:

wr.config.development = True

Changelog

1.0b2 (2021-08-06)

  • Add missing docs/source/overview.rst to release.

1.0b1 (2021-08-06)

  • Initial release.

License

Copyright (c) 2021, Cone Contributors All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

webresource-1.0b2.tar.gz (12.5 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page