z3c.versionedresource 0.1.0

The Version Manager

The Version Manager is a central component that provides the version to the system. It is up to the version manager to decide whether the version is for example based on a tag, a revision number, the package version number or a manually entered version.

>>> from z3c.versionedresource import version

This package provides only a simple version manager, since I have found no other good version indicator that is available generically.

>>> manager = version.VersionManager('1.0.0')
>>> manager
<VersionManager '1.0.0'>

The only constructor argument is the version itself. Versions must be ASCII strings. Let’s now register the version manager, so that it is available for later use:

>>> import zope.component
>>> zope.component.provideUtility(manager)

Clearly, there is not much to version managers and they are only interesting within the larger context of this package.

Versioned Resource Traversal

Zope uses a special, empty-named view to traverse resources from a site like this:

<site>/@@/<resource-path>

We would like to support URLs like this now:

<site>/@@/<version>/<resource-path>

That means that we need a custom implementation of the resources view that can handle the version.

>>> from zope.publisher.browser import TestRequest
>>> from z3c.versionedresource import resource

>>> request = TestRequest()
>>> context = object()

>>> resources = resource.Resources(context, request)

The resources object is a browser view:

>>> resources.__parent__ is context
True
>>> resources.__name__

The view is also a browser publisher. But it dows not support a default:

>>> resources.browserDefault(request)
(<function empty at ...>, ())

When traversing to a sub-item, the version can be specified:

>>> resources.publishTraverse(request, '1.0.0')
<zope.app.publisher.browser.resources.Resources ...>

The result of the traversal is the original resources object. When asking for an unknown resource or version, a NotFound is raised:

>>> resources.publishTraverse(request, 'error')
Traceback (most recent call last):
...
NotFound: Object: <z3c.versionedresource.resource.Resources ...>, name: 'error'

Let’s now register a resource, just to show that traversing to it works:

>>> import zope.interface
>>> from zope.app.publisher.browser.resource import Resource

>>> zope.component.provideAdapter(
...     Resource, (TestRequest,), zope.interface.Interface, 'resource.css')

We can now ask the resources object to traverse the resource:

>>> css = resources.publishTraverse(request, 'resource.css')
>>> css
<zope.app.publisher.browser.resource.Resource object at ...>

Calling it will return the URL:

>>> css()
'http://127.0.0.1/@@/resource.css'

Mmmh, so a regular resource does not honor the version element. That’s because it’s __call__() method defines how the URL is constructed, which is ignorant of the version.

So let’s use this package’s implementation of a resource:

>>> zope.component.provideAdapter(
...     resource.Resource,
...     (TestRequest,), zope.interface.Interface, 'resource2.css')

>>> css = resources.publishTraverse(request, 'resource2.css')
>>> css
<z3c.versionedresource.resource.Resource object at ...>
>>> css()
'http://127.0.0.1/@@/1.0.0/resource2.css'

Custom Resource Classes

The zope.app.publisher.browser package defines three major resources. As pointed out above, they have to be adjusted to produce a versioned URL and set the cache header to a long time.

Custom ZCML Directives

To make the new resources easily usable, we also need custom resource directives:

>>> from zope.configuration import xmlconfig
>>> import z3c.versionedresource
>>> context = xmlconfig.file('meta.zcml', z3c.versionedresource)

Let’s register simple versioned resource:

>>> context = xmlconfig.string("""
... <configure
...     xmlns:browser="http://namespaces.zope.org/browser">
...   <browser:versionedResource
...       name="zcml-test.gif"
...       image="%s"
...       />
... </configure>
... """ %os.path.join(filesdir, 'test.gif') , context=context)

Now we can access the resource:

>>> resources.publishTraverse(request, '1.0.0')\
...          .publishTraverse(request, 'zcml-test.gif')()
'http://127.0.0.1/@@/1.0.0/zcml-test.gif'

Let’s now create a directory resource:

>>> context = xmlconfig.string("""
... <configure
...     xmlns:browser="http://namespaces.zope.org/browser">
...   <browser:versionedResourceDirectory
...       name="zcml-subdir"
...       directory="%s"
...       />
... </configure>
... """ %os.path.join(filesdir, 'subdir') , context=context)

And access it:

>>> resources.publishTraverse(request, '1.0.0')\
...          .publishTraverse(request, 'zcml-subdir')()
'http://127.0.0.1/@@/1.0.0/zcml-subdir'

Lsiting All Resources

Finally, there exists a script that will list all resources registered as versioned resources with the system.

>>> from z3c.versionedresource import list
>>> list.main(
...   ['-u', 'http://zope.org',
...    '-l', 'z3c.versionedresource.tests.test_doc.ITestLayer',
...    os.path.join(os.path.dirname(list.__file__), 'tests', 'simple.zcml')])
http://zope.org/@@/1.0.0/real-subdir/test.gif
http://zope.org/@@/1.0.0/real-subdir/subsubdir/subtest.gif
http://zope.org/@@/1.0.0/zcml-subdir/test.gif
http://zope.org/@@/1.0.0/zcml-subdir/subsubdir/subtest.gif
http://zope.org/@@/1.0.0/real-test.gif
http://zope.org/@@/1.0.0/zcml-test.gif