pyramid.path

CALLER_PACKAGE

A constant used by the constructor of pyramid.path.DottedNameResolver and pyramid.path.AssetResolver (see their docstrings for more info).

class DottedNameResolver(package=pyramid.path.CALLER_PACKAGE)[source]

A class used to resolve a dotted Python name to a package or module object.

Note

This API is new as of Pyramid 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 the resolve() method. A dotted name which has a . (dot) or : (colon) as its first character is treated as relative.

If the value None is supplied as the package, the resolver will only be able to resolve fully qualified (not relative) names. Any attempt to resolve a relative name when the package is None will result in an ValueError exception.

If the value pyramid.path.CALLER_PACKAGE is supplied as the package, the resolver will treat relative dotted names as relative to the caller of the resolve() method.

If a module or module name (as opposed to a package or package name) is supplied as package, 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 the package argument to this type was passed the string xml.dom.expatbuilder, and .mindom is supplied to the resolve() method, the resulting import would be for xml.minidom, because xml.dom.expatbuilder is a module object, not a package object.

If a package or package name (as opposed to a module or module name) is supplied as package, this package will be used to relative compute dotted names. For example, if the package argument to this type was passed the string xml.dom, and .minidom is supplied to the resolve() method, the resulting import would be for xml.minidom.

maybe_resolve(dotted)[source]

This method behaves just like resolve(), except if the dotted 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), the pkg_resources resolution mechanism will be chosen, otherwise the zope.dottedname resolution mechanism will be chosen.

If the dotted argument passed to this method is not a string, a ValueError 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.

Note

This API is new as of Pyramid 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 the resolve() method. An asset specification without a colon in it is treated as relative.

If the value None is supplied as the package, the resolver will only be able to resolve fully qualified (not relative) asset specifications. Any attempt to resolve a relative asset specification when the package is None will result in an ValueError exception.

If the value pyramid.path.CALLER_PACKAGE is supplied as the package, the resolver will treat relative asset specifications as relative to the caller of the resolve() method.

If a module or module name (as opposed to a package or package name) is supplied as package, 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 the package argument to this type was passed the string xml.dom.expatbuilder, and template.pt is supplied to the resolve() method, the resulting absolute asset spec would be xml.minidom:template.pt, because xml.dom.expatbuilder is a module object, not a package object.

If a package or package name (as opposed to a module or module name) is supplied as package, this package will be used to compute relative asset specifications. For example, if the package argument to this type was passed the string xml.dom, and template.pt is supplied to the resolve() method, the resulting absolute asset spec would be xml.minidom:template.pt.

resolve(spec)[source]

Resolve the asset spec named as spec to an object that has the attributes and methods described in pyramid.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 the package passed to this class’ constructor.

If spec is a relative asset specification (an asset specification without a : in it, e.g. templates/foo.pt), the package argument of the constructor is used as the 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 of None, and a relative asset specification is passed to resolve, an ValueError exception is raised.