Metadata-Version: 2.1
Name: webresource
Version: 1.0b7
Summary: A resource registry for web applications.
Home-page: http://github.com/conestack/webresource
Author: Cone Contributors
Author-email: dev@conestack.org
License: Simplified BSD
Description: webresource
        ===========
        
        .. image:: https://img.shields.io/pypi/v/webresource.svg
            :target: https://pypi.python.org/pypi/webresource
            :alt: Latest PyPI version
        
        .. image:: https://img.shields.io/pypi/dm/webresource.svg
            :target: https://pypi.python.org/pypi/webresource
            :alt: Number of PyPI downloads
        
        **A 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.
        
        
        Features
        --------
        
        - Declare web resources via python.
        - Manage dependencies between resources.
        - Grouping of resources.
        - Conditional delivery of resources.
        - Development and a production mode.
        
        
        Detailed Documentation
        ----------------------
        
        The detailed ``webresource`` documentation is available
        `here <https://webresource.readthedocs.io>`_.
        
        
        Source Code
        -----------
        
        The sources are in a GIT DVCS with its main branches at
        `github <http://github.com/conestack/webresource>`_.
        
        
        Copyright
        ---------
        
        - Copyright (c) 2021 Cone Contributors
        
        
        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:
        
        .. code-block:: python
        
            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 in 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:
        
        .. code-block:: python
        
            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:
        
        .. code-block:: python
        
            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:
        
        .. code-block:: python
        
            conditional_js.include = False
        
        Resource URLs can be rendered including a hash of the resource file. This is
        useful in environments with strong caching to make sure changed resources
        get reloaded properly:
        
        .. code-block:: python
        
            cached_js = wr.ScriptResource(
                name='cached_js',
                hash_=True,
                ...
            )
        
        If external resources should be declared, pass ``url`` argument. In this case
        ``path``, ``resource`` and ``compressed`` get ignored:
        
        .. code-block:: python
        
            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:
        
        .. code-block:: python
        
            scripts = wr.ResourceGroup(name='scripts')
        
        Resources can be added to a group at instantiation time if group is known in
        advance.
        
        .. code-block:: python
        
            script = wr.ScriptResource(
                name='script',
                group=scripts
                ...
            )
        
        or an already declared resource can be added to a group:
        
        .. code-block:: python
        
            scripts.add(script)
        
        Groups can be nested:
        
        .. code-block:: python
        
            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 members. The
        group path takes precedence over its members paths:
        
        .. code-block:: python
        
            scripts = wr.ResourceGroup(name='scripts', path='js')
        
        To control whether an entire group should be included, define an ``include``
        callback funtion or flag.
        
        .. code-block:: python
        
            def include_group():
                # Compute whether to include resource group here.
                return True
        
            group = wr.ResourceGroup(
                name='group',
                include=include_group,
                ...
            )
        
        
        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 used to create the markup.
        
        A complete example:
        
        .. code-block:: python
        
            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(
                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://example.com'
            )
        
            rendered = renderer.render()
        
        ``rendered`` results in:
        
        .. code-block:: html
        
            <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 singleton needs to be
        set:
        
        .. code-block:: python
        
            wr.config.development = True
        
        
        Changelog
        =========
        
        1.0b7 (2021-08-16)
        ------------------
        
        - Add auto integrity hash calculation on ``ScriptResource``.
        
        - Add ``hash_`` and ``hash_algorithm`` keyword arguments to ``Resource``,
          ``ScriptResource``, ``LinkResource`` and ``FileResource``.
        
        - Add ``Resource.file_hash`` property.
        
        - Add ``Resource.file_data`` property.
        
        
        1.0b6 (2021-08-10)
        ------------------
        
        - Raise explicit ``ResourceError`` instead of generic ``ValueError``.
        
        
        1.0b5 (2021-08-09)
        ------------------
        
        - Make ``Resource.directory`` a R/W property.
        
        
        1.0b4 (2021-08-08)
        ------------------
        
        - Change ``path`` cascading behavior. Path set on ``ResourceGroup`` always takes
          precedence over its members paths.
        
        - ``include`` property of ``Resource`` and ``ResourceGroup`` can be set from
          outside.
        
        
        1.0b3 (2021-08-06)
        ------------------
        
        - Add remaining missing rst files to release.
        
        
        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.
        
Keywords: web resources dependencies javascript CSS
Platform: UNKNOWN
Classifier: License :: OSI Approved :: BSD License
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Provides-Extra: docs
Provides-Extra: test
