Name

class lsst.verify.Name(package=None, metric=None, spec=None)

Bases: object

Semantic name of a package, Metric or Specification in the lsst.verify framework.

Name instances are immutable and can be used as keys in mappings.

Parameters:

package : str or Name

Name of the package, either as a string ('validate_drp', for example) or as a Name object (Name(package='validate_drp') for example).

The package field can also be fully specified:

>>> Name(package='validate_drp.PA1.design_gri')
Name('validate_drp', 'PA1', 'design_gri')

Or the package field can be used as the sole positional argument:

>>> Name('validate_drp.PA1.design_gri')
Name('validate_drp', 'PA1', 'design_gri')

metric : str or Name

Name of the metric. The name can be relative ('PA') or fully-specified ('validate_drp.PA1').

spec : str or Name

Name of the specification. The name can be bare ('design_gri'), metric-relative ('PA1.design_gri') or fully-specified ('validate_drp.PA1.design_gri')

Raises:

TypeError

Raised when arguments cannot be parsed or conflict (for example, if two different package names are specified through two different fields).

Notes

Names in the Verification Framework are formatted as:

package.metric.specification

A fully-qualified name is one that has all components included. For example, a fully specified metric name is:

validate_drp.PA1

This means: “the PA1 metric in the validate_drp package.

An example of a fully-specificed specification name:

validate_drp.PA1.design

This means: “the design specification of the PA1 metric in the validate_drp package.

A relative name is one that’s missing a component. For example:

PA1.design

Asserting this is a relative specification name, the package is not known.

Examples

Creation

There are many patterns for creating Name instances. Different patterns are useful in different circumstances.

You can create a metric name from its components:

>>> Name(package='validate_drp', metric='PA1')
Name('validate_drp', 'PA1')

Or a specification name from components:

>>> Name(package='validate_drp', metric='PA1', spec='design')
Name('validate_drp', 'PA1', 'design')

You can equivalently create Names from fully-qualified strings:

>>> Name('validate_drp.PA1')
Name('validate_drp', 'PA1')

>>> Name('validate_drp.PA1.design')
Name('validate_drp', 'PA1', 'design')

You can also use an existing name to specify some components of the name:

>>> metric_name = Name('validate_drp.PA1')
>>> Name(metric=metric_name, spec='design')
Name('validate_drp', 'PA1', 'design')

A TypeError is raised if any components of the input names conflict.

Fully-specified metric names can be mixed with a spec component:

>>> Name(metric='validate_drp.PA1', spec='design')
Name('validate_drp', 'PA1', 'design')

String representation

Converting a Name into a str gives you the canonical string representation, as fully-specified as possible:

>>> str(Name('validate_drp', 'PA1', 'design'))
'validate_drp.PA1.design'

Alternatively, obtain the fully-qualified metric name from the Name.fqn property:

>>> name = Name('validate_drp', 'PA1', 'design')
>>> name.fqn
'validate_drp.PA1.design'

The relative name of a specification omits the package component:

>>> name = Name('validate_drp.PA1.design')
>>> name.relative_name
'PA1.design'

Attributes Summary

fqn	The fully-qualified name (str).
has_metric	True if this object contains a metric name, either
has_package	True if this object contains a package name (bool).
has_relative	True if a relative specification name can be formed from this
has_spec	True if this object contains a specification name, either
is_fq	True if this object is a fully-qualified name of either a
is_metric	True if this object is a metric name, either relative or
is_package	True if this object is a package name (bool).
is_relative	True if this object is a specification name that’s not
is_spec	True if this object is a specification name, either relative or
metric	Metric name (str).
package	Package name (str).
relative_name	The relative specification name (str).
spec	Specification name (str).

Attributes Documentation

fqn

The fully-qualified name (str).

Raises:

AttributeError

If the name is not a fully-qualified name (check is_fq)

Examples

>>> Name('validate_drp', 'PA1').fqn
'validate_drp.PA1'
>>> Name('validate_drp', 'PA1', 'design').fqn
'validate_drp.PA1.design'

has_metric

True if this object contains a metric name, either relative or fully-qualified (bool).

>>> Name('validate_drp.PA1').has_metric
True
>>> Name(spec='design').has_metric
False

has_package

True if this object contains a package name (bool).

>>> Name('validate_drp.PA1').has_package
True
>>> Name(spec='design').has_package
False

has_relative

True if a relative specification name can be formed from this object, i.e., metric and spec attributes are set (bool).

has_spec

True if this object contains a specification name, either relative or fully-qualified (bool).

>>> Name(spec='design').has_spec
True
>>> Name('validate_drp.PA1').has_spec
False

is_fq

True if this object is a fully-qualified name of either a package, metric or specification (bool).

Examples

A fully-qualified package name:

>>> Name('validate_drp').is_fq
True

A fully-qualified metric name:

>>> Name('validate_drp.PA1').is_fq
True

A fully-qualified specification name:

>>> Name('validate_drp.PA1.design_gri').is_fq
True

is_metric

True if this object is a metric name, either relative or fully-qualified (bool).

>>> Name('validate_drp.PA1').is_metric
True
>>> Name('validate_drp.PA1.design').is_metric
False

is_package

True if this object is a package name (bool).

>>> Name('validate_drp').is_package
True
>>> Name('validate_drp.PA1').is_package
False

is_relative

True if this object is a specification name that’s not fully-qualified, but is relative to a metric name (bool). relative to a base name. (bool).

Package and metric names are never relative.

A relative specification name:

>>> Name(spec='PA1.design_gri').is_relative
True

But not:

>>> Name('validate_drp.PA1.design_gri').is_relative
False

is_spec

True if this object is a specification name, either relative or fully-qualified (bool).

>>> Name('validate_drp.PA1').is_spec
False
>>> Name('validate_drp.PA1.design').is_spec
True

metric

Metric name (str).

>>> name = Name('validate_drp.PA1.design')
>>> name.metric
'PA1'

package

Package name (str).

>>> name = Name('validate_drp.PA1.design')
>>> name.package
'validate_drp'

relative_name

The relative specification name (str).

Raises:

AttributeError

If the object does not represent a specification, or if a relative name cannot be formed because the metric is None.

Examples

>>> Name('validate_drp.PA1.design').relative_name
'PA1.design'

spec

Specification name (str).

>>> name = Name('validate_drp.PA1.design')
>>> name.spec
'design'