o k`@@sddlTddlmZmZddlmZddlmZGdddeZ GdddeZ Gd d d e Z Gd d d e ZGd ddeZddZd$ddZddZddZddZd%ddZd%ddZd$dd Zd!d"Zd#S)&)*)Fragmenttag)classes)_c@eZdZdZdS)ResourceExistsErrorz6Thrown when attempting to insert an existing resource.N__name__ __module__ __qualname____doc__rr//usr/lib/python3/dist-packages/trac/resource.pyrrc@r)ResourceNotFoundz0Thrown when a non-existent resource is requestedNr rrrrrrrc@s.eZdZddZddZd ddZd d ZdS) IResourceManagercCdS)zZReturn resource realms managed by the component. :rtype: `str` generator Nrrrrrget_resource_realms#z$IResourceManager.get_resource_realmscKr)aoReturn the canonical URL for displaying the given resource. :param resource: a `Resource` :param href: an `Href` used for creating the URL Note that if there's no special rule associated to this realm for creating URLs (i.e. the standard convention of using realm/id applies), then it's OK to not define this method. Nr)resourcehrefkwargsrrrget_resource_url)rz!IResourceManager.get_resource_urldefaultNcKr)a;Return a string representation of the resource, according to the `format`. :param resource: the `Resource` to describe :param format: the kind of description wanted. Typical formats are: `'default'`, `'compact'` or `'summary'`. :param context: an optional rendering context to allow rendering rich output (like markup containing links) :type context: `ResourceContext` Additional keyword arguments can be given as extra information for some formats. For example, the ticket with the id 123 is represented as: - `'#123'` in `'compact'` format, - `'Ticket #123'` for the `default` format. - `'Ticket #123 (closed defect): This is the summary'` for the `'summary'` format Note that it is also OK to not define this method if there's no special way to represent the resource, in which case the standard representations 'realm:id' (in compact mode) or 'Realm id' (in default mode) will be used. Nr)rformatcontextrrrrget_resource_description4rz)IResourceManager.get_resource_descriptioncCr)zCheck whether the given `resource` exists physically. :rtype: bool Attempting to retrieve the model object for a non-existing resource should raise a `ResourceNotFound` exception. (''since 0.11.8'') Nr)rrrrresource_existsOrz IResourceManager.resource_exists)rN)r r r rrrrrrrrr!s  rcsVeZdZdZdZddZddZddZ dfd d Zdd dZ dddZ Z S)ResourceaResource 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. realmidversionparentcCspg}|}|r/|j}|jr|dt|j7}|jdur#|dt|j7}||p(d|j}|sddt|S)N:@z z, )r!r"strr#appendr$joinreversed)selfpathrnamerrr__repr__ps zResource.__repr__cCs0|j|jko|j|jko|j|jko|j|jkSNr )r,otherrrr__eq__}s    zResource.__eq__cCs2d}|}|r||j|j|jf7}|j}|st|S)z7Hash this resource descriptor, including its hierarchy.r)r!r"r#r$hash)r,r-currentrrr__hash__szResource.__hash__NFcs|}t|tr6|dur|dur|dur|S|j}|dur|j}|dur.||jkr,|j}nd}|dur5|j}n|dur>> main = Resource('wiki', 'WikiStart') >>> repr(main) "" >>> Resource(main) is main True >>> main3 = Resource(main, version=3) >>> repr(main3) "" >>> main0 = main3(version=0) >>> repr(main0) "" In a copy, if `id` is overridden, then the original `version` value will not be reused. >>> repr(Resource(main3, id="WikiEnd")) "" >>> repr(Resource(None)) "" FN) isinstancerr!r"r#r$super__new__)clsresource_or_realmr"r#r$r!r __class__rrr9s4"   zResource.__new__cCst|dur|n||||S)zCreate a new Resource using the current resource as a template. Optional keyword arguments can be given to override `id` and `version`. Fr)r,r!r"r#r$rrr__call__szResource.__call__cCst||||S)zRetrieve 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')) "" r>)r,r!r"r#rrrchildszResource.child)NFFF)FFFF)FF) r r r r __slots__r0r3r6r9r?r@ __classcell__rrr<rrZs   ? rc@s0eZdZdZeeZddZddZddZ dS) ResourceSystemzResource identification and description manager. This component makes the link between `Resource` identifiers and their corresponding manager `Component`. cCs d|_dSr1)_resource_managers_map)r,rrr__init__ zResourceSystem.__init__cCsB|jsi}|jD]}|pgD]}|||<qq||_|j|S)zReturn the component responsible for resources in the given `realm` :param realm: the realm name :return: a `Component` implementing `IResourceManager` or `None` )rDresource_managersrget)r,r!mapmanager manager_realmrrrget_resource_managers   z#ResourceSystem.get_resource_managercCs0g}|jD]}|p gD]}||q q|S)z:Return a list of all the realm names of resource managers.)rGrr))r,realmsrJr!rrrget_known_realmss   zResourceSystem.get_known_realmsN) r r r r ExtensionPointrrGrErLrNrrrrrCs  rCcKs\t||j}|rt|dr|j||fi|Sd|ji}||||j|jfi|S)aRetrieve 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. :param env: the `Environment` where `IResourceManager` components live :param resource: the `Resource` object specifying the Trac resource :param 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' rr#)rCrLr!hasattrrr#updater")envrrrrJargsrrrr s #  rrcKs^t||j}|rt|dr|j||fi|Sd|j|jf}|dkr-td||jd}|S)a.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. :param env: the `Environment` where `IResourceManager` components live :param resource: the `Resource` object specifying the Trac resource :param 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) 'generic:Main' >>> get_resource_description(env, main(version=3)) 'generic:Main' >>> get_resource_description(env, main(version=3), format='summary') 'generic:Main at version 3' rz%s:%ssummaryz%(name)s at version %(version)s)r/r#)rCrLr!rPrr"rr#)rRrrrrJr/rrrr5srcCs t||Sr1rrRrrrrget_resource_name\rFrWcC t||dS)NcompactrUrVrrrget_resource_shortname` rZcCrX)NrTrUrVrrrget_resource_summarydr[r\r'cCs|dvr|St|ddkr|jndd}|dD]}|dkr(|r'|q|r3|dkr3||q||r>d|dSddS) zBuild a Resource relative to a reference resource. :param path: path leading to another resource within the same realm. )Nr'.r/r'z..r]N)r")r(r"splitpopr)r*)rr-basecomprrrget_relative_resourcehs   rccKst|t|||fi|S)a/Build an URL relative to a resource given as reference. :param 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' )rrc)rRrrr-rrrrget_relative_urlzs 7rdcCsZt||||d}t|ts+t||du}tj|t|j|dt|||j |r'dndd}|S)aUtility 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. )rF)missingnofollowN)class_rrel) rr7rrrarr!rr)rRrrrlinkrerrrrender_resource_links   rkcCs:t||j}|rt|dr||S|jdurdSdS)a2Checks for resource existence without actually instantiating a model. :return: `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 rNF)rCrLr!rPrr")rRrrJrrrrs   rN)r)r') trac.coretrac.util.htmlrrtrac.util.presentationrtrac.util.translationr TracErrorrr Interfacerobjectr ComponentrCrrrWrZr\rcrdrkrrrrrs&  9 ( +'   ;