Commit 4b731d83 authored by Christoph Groth's avatar Christoph Groth
Browse files

clarify the docstring of SiteFamily

parent 02e5798a
...@@ -84,23 +84,27 @@ class Site(tuple): ...@@ -84,23 +84,27 @@ class Site(tuple):
class SiteFamily(object): class SiteFamily(object):
""" """Abstract base class for site families.
Abstract base class for site families.
Site families are the 'type' of `Site` objects. Within a family, individual
sites are uniquely identified by tags. Valid tags must be hashable Python
objects, further details are up to the family.
A site family is a 'type' of sites. Site families must be immutable and Site families must be immutable and fully defined by their initial
fully defined by their initial arguments. They must inherit from this arguments. They must inherit from this abstract base class and call its
abstract base class and call its __init__ function providing it with two __init__ function providing it with two arguments: a canonical
arguments: a canonical representation and a name. The canonical representation and a name. The canonical representation will be returned as
representation will be returned as the objects representation and must the objects representation and must uniquely identify the site family
uniquely identify the site family instance. The name is a string used to instance. The name is a string used to distinguish otherwise identical site
distinguish otherwise identical site families. It may be empty. families. It may be empty.
All site families must define the method `normalize_tag` which brings a tag All site families must define the method `normalize_tag` which brings a tag
to the standard format for this site family. to the standard format for this site family.
Site families which are intended for use with plotting should also provide a Site families that are intended for use with plotting should also provide a
method `pos(tag)`, which returns a vector with real-space coordinates of method `pos(tag)`, which returns a vector with real-space coordinates of the
the site belonging to this family with a given tag. site belonging to this family with a given tag.
""" """
__metaclass__ = abc.ABCMeta __metaclass__ = abc.ABCMeta
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment