Module resource

Retrieve the canonical URL for the given resource.

This function delegates the work to the resource manager for that resource if it implements a get_resource_url method, otherwise reverts to simple '/realm/identifier' style URLs.

Additional keyword arguments are translated as query parameters in the URL.

>>> from trac.test import EnvironmentStub
>>> from trac.web.href import Href
>>> env = EnvironmentStub()
>>> href = Href('/trac.cgi')
>>> main = Resource('generic', 'Main')
>>> get_resource_url(env, main, href)
'/trac.cgi/generic/Main'

>>> get_resource_url(env, main(version=3), href)
'/trac.cgi/generic/Main?version=3'

>>> get_resource_url(env, main(version=3), href)
'/trac.cgi/generic/Main?version=3'

>>> get_resource_url(env, main(version=3), href, action='diff')
'/trac.cgi/generic/Main?action=diff&version=3'

>>> get_resource_url(env, main(version=3), href, action='diff', version=5)
'/trac.cgi/generic/Main?action=diff&version=5'

Parameters:

• env - the Environment where IResourceManager components live
• resource - the Resource object specifying the Trac resource
• href - an Href object used for building the URL

Retrieve a standardized description for the given resource.

This function delegates the work to the resource manager for that resource if it implements a get_resource_description method, otherwise reverts to simple presentation of the realm and identifier information.

Additional keyword arguments can be provided and will be propagated to resource manager that might make use of them (typically, a context parameter for creating context dependent output).

>>> from trac.test import EnvironmentStub
>>> env = EnvironmentStub()
>>> main = Resource('generic', 'Main')
>>> get_resource_description(env, main)
u'generic:Main'

>>> get_resource_description(env, main(version=3))
u'generic:Main'

>>> get_resource_description(env, main(version=3), format='summary')
u'generic:Main at version 3'

Parameters:

• env - the Environment where IResourceManager components live
• resource - the Resource object specifying the Trac resource
• format - which formats to use for the description

Parameters:

• path - path leading to another resource within the same realm.

Build an URL relative to a resource given as reference.

>>> from trac.test import EnvironmentStub
>>> env = EnvironmentStub()
>>> from trac.web.href import Href
>>> href = Href('/trac.cgi')
>>> main = Resource('wiki', 'Main', version=3)

Without parameters, return the canonical URL for the resource, like get_resource_url does.

>>> get_relative_url(env, main, href)
'/trac.cgi/wiki/Main?version=3'

Paths are relative to the given resource:

>>> get_relative_url(env, main, href, '.')
'/trac.cgi/wiki/Main?version=3'

>>> get_relative_url(env, main, href, './Sub')
'/trac.cgi/wiki/Main/Sub'

>>> get_relative_url(env, main, href, './Sub/Infra')
'/trac.cgi/wiki/Main/Sub/Infra'

>>> get_relative_url(env, main, href, './Sub/')
'/trac.cgi/wiki/Main/Sub'

>>> mainsub = main(id='Main/Sub')
>>> get_relative_url(env, mainsub, href, '..')
'/trac.cgi/wiki/Main'

>>> get_relative_url(env, main, href, '../Other')
'/trac.cgi/wiki/Other'

References always stay within the current resource realm:

>>> get_relative_url(env, mainsub, href, '../..')
'/trac.cgi/wiki'

>>> get_relative_url(env, mainsub, href, '../../..')
'/trac.cgi/wiki'

>>> get_relative_url(env, mainsub, href, '/toplevel')
'/trac.cgi/wiki/toplevel'

Extra keyword arguments are forwarded as query parameters:

>>> get_relative_url(env, main, href, action='diff')
'/trac.cgi/wiki/Main?action=diff&version=3'

Parameters:

• path - path leading to another resource within the same realm.

Utility for generating a link Element to the given resource.

Some component manager may directly use an extra context parameter in order to directly generate rich content. Otherwise, the textual output is wrapped in a link to the resource.

Checks for resource existence without actually instantiating a model.

>>> from trac.test import EnvironmentStub
>>> env = EnvironmentStub()

>>> resource_exists(env, Resource('dummy-realm', 'dummy-id')) is None
True
>>> resource_exists(env, Resource('dummy-realm'))
False

Returns:

True if the resource exists, False if it doesn't and None in case no conclusion could be made (i.e. when IResourceManager.resource_exists is not implemented).