trac.resource

class trac.resource.Resource

Bases: object

Resource identifier.

This specifies as precisely as possible which resource from a Trac environment is manipulated.

A resource is identified by:
  • a realm (a string like 'wiki' or 'ticket')
  • an id, which uniquely identifies a resource within its realm. If the id information is not set, then the resource represents the realm as a whole.
  • an optional version information. If version is None, this refers by convention to the latest version of the resource.

Some generic and commonly used rendering methods are associated as well to the Resource object. Those properties and methods actually delegate the real work to the Resource’s manager.

Create a new Resource object from a specification.

Parameters:
  • resource_or_realm – this can be either: - a Resource, which is then used as a base for making a copy - a basestring, used to specify a realm
  • id – the resource identifier
  • version – the version or None for indicating the latest version
 
>>> main = Resource('wiki', 'WikiStart')
>>> repr(main)
"<Resource u'wiki:WikiStart'>"

>>> Resource(main) is main
True

>>> main3 = Resource(main, version=3)
>>> repr(main3)
"<Resource u'wiki:WikiStart@3'>"

>>> main0 = main3(version=0)
>>> repr(main0)
"<Resource u'wiki:WikiStart@0'>"

In a copy, if id is overridden, then the original version value will not be reused.

>>> repr(Resource(main3, id="WikiEnd"))
"<Resource u'wiki:WikiEnd'>"

>>> repr(Resource(None))
"<Resource ''>"
child(realm, id=False, version=False)

Retrieve a child resource for a secondary realm.

Same as __call__, except that this one sets the parent to self.

>>> repr(Resource(None).child('attachment', 'file.txt'))
"<Resource u', attachment:file.txt'>"
exception trac.resource.ResourceExistsError(message, title=None, show_traceback=False)

Bases: trac.core.TracError

Thrown when attempting to insert an existing resource.

If message is an Element object, everything up to the first <p> will be displayed in the red box, and everything after will be displayed below the red box. If title is given, it will be displayed as the large header above the error message.

exception trac.resource.ResourceNotFound(message, title=None, show_traceback=False)

Bases: trac.core.TracError

Thrown when a non-existent resource is requested

If message is an Element object, everything up to the first <p> will be displayed in the red box, and everything after will be displayed below the red box. If title is given, it will be displayed as the large header above the error message.

class trac.resource.ResourceSystem

Bases: trac.core.Component

Resource identification and description manager.

This component makes the link between Resource identifiers and their corresponding manager Component.

get_known_realms()

Return a list of all the realm names of resource managers.

get_resource_manager(realm)

Return the component responsible for resources in the given realm

Parameters:realm – the realm name
Returns:a Component implementing IResourceManager or None
resource_managers

List of components that implement IResourceManager

trac.resource.get_relative_resource(resource, path='')

Build a Resource relative to a reference resource.

Parameters:path – path leading to another resource within the same realm.
trac.resource.get_relative_url(env, resource, href, path='', **kwargs)

Build an URL relative to a resource given as reference.

Parameters:path – path leading to another resource within the same realm. 
>>> 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'
trac.resource.get_resource_description(env, resource, format='default', **kwargs)

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.

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

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'
trac.resource.get_resource_url(env, resource, href, **kwargs)

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.

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

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'

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.

trac.resource.resource_exists(env, resource)

Checks for resource existence without actually instantiating a model.

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). 
>>> 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