pyramid.path
¶
- CALLER_PACKAGE¶
A constant used by the constructor of
pyramid.path.DottedNameResolver
andpyramid.path.AssetResolver
.
- class DottedNameResolver(package=pyramid.path.CALLER_PACKAGE)[source]¶
A class used to resolve a dotted Python name to a package or module object.
New in version 1.3.
The constructor accepts a single argument named
package
which may be any of:A fully qualified (not relative) dotted name to a module or package
a Python module or package object
The value
None
The constant value
pyramid.path.CALLER_PACKAGE
.
The default value is
pyramid.path.CALLER_PACKAGE
.The
package
is used when a relative dotted name is supplied to theresolve()
method. A dotted name which has a.
(dot) or:
(colon) as its first character is treated as relative.If
package
isNone
, the resolver will only be able to resolve fully qualified (not relative) names. Any attempt to resolve a relative name will result in anValueError
exception.If
package
ispyramid.path.CALLER_PACKAGE
, the resolver will treat relative dotted names as relative to the caller of theresolve()
method.If
package
is a module or module name (as opposed to a package or package name), its containing package is computed and this package used to derive the package name (all names are resolved relative to packages, never to modules). For example, if thepackage
argument to this type was passed the stringxml.dom.expatbuilder
, and.mindom
is supplied to theresolve()
method, the resulting import would be forxml.minidom
, becausexml.dom.expatbuilder
is a module object, not a package object.If
package
is a package or package name (as opposed to a module or module name), this package will be used to relative compute dotted names. For example, if thepackage
argument to this type was passed the stringxml.dom
, and.minidom
is supplied to theresolve()
method, the resulting import would be forxml.minidom
.- maybe_resolve(dotted)[source]¶
This method behaves just like
resolve()
, except if thedotted
value passed is not a string, it is simply returned. For example:import xml r = DottedNameResolver() v = r.maybe_resolve(xml) # v is the xml module; no exception raised
- resolve(dotted)[source]¶
This method resolves a dotted name reference to a global Python object (an object which can be imported) to the object itself.
Two dotted name styles are supported:
pkg_resources
-style dotted names where non-module attributes of a package are separated from the rest of the path using a:
e.g.package.module:attr
.zope.dottedname
-style dotted names where non-module attributes of a package are separated from the rest of the path using a.
e.g.package.module.attr
.
These styles can be used interchangeably. If the supplied name contains a
:
(colon), thepkg_resources
resolution mechanism will be chosen, otherwise thezope.dottedname
resolution mechanism will be chosen.If the
dotted
argument passed to this method is not a string, aValueError
will be raised.When a dotted name cannot be resolved, a
ValueError
error is raised.Example:
r = DottedNameResolver() v = r.resolve('xml') # v is the xml module
- class AssetResolver(package=pyramid.path.CALLER_PACKAGE)[source]¶
A class used to resolve an asset specification to an asset descriptor.
New in version 1.3.
The constructor accepts a single argument named
package
which may be any of:A fully qualified (not relative) dotted name to a module or package
a Python module or package object
The value
None
The constant value
pyramid.path.CALLER_PACKAGE
.
The default value is
pyramid.path.CALLER_PACKAGE
.The
package
is used when a relative asset specification is supplied to theresolve()
method. An asset specification without a colon in it is treated as relative.If
package
isNone
, the resolver will only be able to resolve fully qualified (not relative) asset specifications. Any attempt to resolve a relative asset specification will result in anValueError
exception.If
package
ispyramid.path.CALLER_PACKAGE
, the resolver will treat relative asset specifications as relative to the caller of theresolve()
method.If
package
is a module or module name (as opposed to a package or package name), its containing package is computed and this package is used to derive the package name (all names are resolved relative to packages, never to modules). For example, if thepackage
argument to this type was passed the stringxml.dom.expatbuilder
, andtemplate.pt
is supplied to theresolve()
method, the resulting absolute asset spec would bexml.minidom:template.pt
, becausexml.dom.expatbuilder
is a module object, not a package object.If
package
is a package or package name (as opposed to a module or module name), this package will be used to compute relative asset specifications. For example, if thepackage
argument to this type was passed the stringxml.dom
, andtemplate.pt
is supplied to theresolve()
method, the resulting absolute asset spec would bexml.minidom:template.pt
.- resolve(spec)[source]¶
Resolve the asset spec named as
spec
to an object that has the attributes and methods described inpyramid.interfaces.IAssetDescriptor
.If
spec
is an absolute filename (e.g./path/to/myproject/templates/foo.pt
) or an absolute asset spec (e.g.myproject:templates.foo.pt
), an asset descriptor is returned without taking into account thepackage
passed to this class' constructor.If
spec
is a relative asset specification (an asset specification without a:
in it, e.g.templates/foo.pt
), thepackage
argument of the constructor is used as the package portion of the asset spec. For example:a = AssetResolver('myproject') resolver = a.resolve('templates/foo.pt') print(resolver.abspath()) # -> /path/to/myproject/templates/foo.pt
If the AssetResolver is constructed without a
package
argument ofNone
, and a relative asset specification is passed toresolve
, anValueError
exception is raised.