sfftkrw.schema.base¶
This API specifies several base classes from which all other classes are built upon:
SFFAttribute
descriptor class¶
-
class
sfftkrw.schema.base.
SFFAttribute
(name, sff_type=None, required=False, default=None, help="")¶ Bases:
object
Descriptor for
SFFType
subclass attributesThe adapter classes specify class attributes as accessors of values in the
generateDS
API. These are accomplished using this class toget
,set
anddelete
values taking into account translation between the adapter and thegenerateDS
API.This is done by referencing the
obj._local
variable which is the proxy for the underlying objects.Please see the
api
module for how this is applied.Parameters: - name (bytes or unicode) – which
emdb_sff
attribute to get the data from - sff_type (SFFType) – class of attribute (default: None - standard Python types like int, str, float)
- required (bool) – whether or not this is a required (mandatory) attribute; default is False
- default – default value that this attribute takes; can be anything
- help (bytes or unicode) – help text associated with the attribute
- name (bytes or unicode) – which
SFFType
base class¶
-
class
sfftkrw.schema.base.
SFFType
(*args, **kwargs)¶ Bases:
object
Base class for all EMDB-SFF adapter classes
This class reads and configures any subclass using the subclass’s definition.
Subclasses of
SFFType
should define class attributes from the following list depending on whether the subclass defines a container or not. Containers typically have List in the class name signifying that they are a list of objects of some type. For example, theSFFSegmentList
objects are a list ofSFFSegment
objects.-
as_hff
(parent_group, name=None, args=None)¶ Returns the current object as a group in an HDF5 file with the given name
For instances which are subclasses of
base.SFFIndexType
name will be a string version of the index (id). If id is None then we will generate a unique one so as to write the object to file. Therefore, the process of writing to HDF5 could end up looking slightly different from the original if the original had missing indexes for some objects.Parameters: - parent_group (
Group
) – an HDF5 Group that will contain the objects in this object - args (
argparse.Namespace
) – command line arguments - name (str or None) – the name to be given to this object in the object hierarchy (default: None)
Returns: the populated parent group
Return type: Group
- parent_group (
-
as_json
(args=None)¶ For all contained classes this method returns a dictionary which will be serialised into JSON. Only at the top level (SFFSegmentation) will the final serialisation be done.
Parameters: args ( argparse.Namespace
) – command line argumentsReturns: a set of nested dictionaries Return type: dict
-
eq_attrs
= []¶ A list of attributes used to test equality
-
export
(fn, args=None, *_args, **_kwargs)¶ Export to a file on disc
Parameters: fn (str or io.TextIOWrapper or io.RawIOBase or io.BufferedIOBase or file) – filename to export to; the output format is determined by the extension: Return int status: exit code from os
library.sff
- XML.hff
- HDF5.json
- JSON
-
classmethod
from_gds_type
(inst=None)¶ Create an
SFFType
subclass directly from a gds_type objectNotice that we ignore do not pass *args, **kwargs as we assume the inst is complete.
-
classmethod
from_hff
(parent_group, name=None, args=None)¶ Convert HDF5 objects into EMDB-SFF objects It should either return a valid object or raise an
SFFValueError
due to failed validationParameters: - parent_group (
Group
) – an HDF5 Group that will contain the objects in this object - args (
argparse.Namespace
) – command line arguments - name (str or None) – the name to be given to this object in the object hierarchy (default: None)
Returns: the corresponding SFF* object
Return type: base.SFFType
subclass- parent_group (
-
classmethod
from_json
(data, args=None)¶ Deserialise the given json object into an EMDB-SFF object
Parameters: - data (dict) – the data to be converted into SFF* objects
- args (
argparse.Namespace
) – command line arguments
Returns: the corresponding SFF* object
Return type: base.SFFType
subclass
-
gds_tag_name
= None¶ The literal tag name in XML output. Should only changed in cases where several types are an extension of a single type in which case all types appear in the XML with the name of their parent. Most classes will not need this set.
-
gds_type
= None¶ The
generateDS
class adapted by this SFFType subclass
-
repr_args
= ()¶ The arguments of the string representation, if any.
A tuple of strings each of which is an attribute that can be referenced for a value to put into the repr_string
For example to have the representational string “SFFSegment(id=33)” we set repr_string=”SFFSegment(id={}) and repr_args=(‘id’, )
Some special repr_args values are:
len()
fills the{}
with the length;list()
fills the{}
with a list of contained objects.data[:100]
applied to thesfftkrw.SFFLattice
class where only the first 100 bytes are displayed
-
repr_string
= ''¶ A string representation for objects of the subclass that can be formatted. This string will be produced for calls to the
print()
function. Formatting is accomplished by included empty format delimiters ({}
) which will be populated with values from therepr_args
specified below otherwise literal braces will be displayed.
-
SFFIndexType
base class¶
-
class
sfftkrw.schema.base.
SFFIndexType
(*args, **kwargs)¶ Bases:
sfftkrw.schema.base.SFFType
Subclass to handle objects with indexes (IDs)
-
classmethod
from_gds_type
(inst=None)¶ Create an
SFFType
subclass directly from a gds_type objectNotice that we ignore do not pass *args, **kwargs as we assume the inst is complete.
-
increment_by
= 1¶ by default we increment by 1
-
index_attr
= ''¶ the name of the attribute on the class which will be treated as the ID
-
index_in_super
= False¶ when an index is applied to a set of subclasses we set index_in_super to True
-
classmethod
reset_id
()¶ Reset the index_attr attribute to its starting value
-
start_at
= 0¶ used when resetting index_attr attribute
-
classmethod
SFFListType
base class¶
-
class
sfftkrw.schema.base.
SFFListType
(*args, **kwargs)¶ Bases:
sfftkrw.schema.base.SFFType
Subclass to confer list-like behaviour
-
append
(item)¶ Append to the list
-
clear
()¶ Remove all items
-
copy
()¶ Create a shallow copy
-
extend
(other)¶ Extend this list using this and other
-
classmethod
from_gds_type
(inst=None)¶ Create an
SFFType
subclass directly from a gds_type objectNotice that we ignore do not pass *args, **kwargs as we assume the inst is complete.
-
get_by_id
(id)¶ A convenience dictionary to retrieve contained objects by ID
Items with no ID will not be found in the dictionary
-
get_ids
()¶ Return a list of IDs of the contained objects
Should only work if the contained objects have IDs i.e. it should not work for SFFComplexes and SFFMacromolecules
-
insert
(index, item)¶ Insert into the list at the given index
-
iter_attr
= None¶ the name of the attribute in the
generateDS
class that we iterate over together with the SFFType subclass to cast each received object toThe iterable attribute of the class. It refers to an attribute of the class pointed to by
gds_type
which is iterable.It should be a two-tuple having the name of the generateDS class and
SFF*
class to adapt it to.Only one attribute per class can be specified.
For example, consider the following class definition for some fictional
SFFTest
class that adapts a class calledtest
that was generated by generateDS.import emdb_sff class SFFTest(SFFType): gds_type = emdb_sff.test repr_str = "SFFTest object with {} SFFItem objects inside" repr_args = ("len()",) iter_attr = ('i', SFFItem) # attributes items = SFFAttribute('items', sff_type=SFFItem)
In this sample:
- the generateDS API is located in the module called
emdb_sff
; test
is a class in theemdb_sff
module;i
is an iterable attribute oftest
;i
is adapted by theSFFItem
class (which should have itsgds_type
set to the class fori
);
Now consider this class in action:
from sfftkrw.schema import SFFTest T = SFFTest() # ... # populate T with some valid data # ... # now we can iterate over the data for i in T: # because it has an iter_attr specified # i is an SFFItem object print(i) # prints 'SFFTest object with 37 SFFItem objects inside'
In addition to being iterable, the iterable attribute enable the following operations on objects of the subclass:
length i.e. len(obj);
len(T) # 37
indexing e.g.
obj[<int>]
;T[15]
- the generateDS API is located in the module called
-
pop
(index=-1)¶ Remove and return the indexed (default: last) item
-
remove
(item)¶ Removes the first occurrence of item
-
reverse
()¶ Reverses the items in place
-
sibling_classes
= []¶ a list of pairs of classes which are all subclasses of some convenience class
For example:
SFFShape
is the parent ofSFFCone
,SFFCuboid
,SFFCylinder
andSFFEllipsoid
. This is because theSFFShape
class manages a continuous set of IDs for the different shapes. However, when we iterate over a SFFShapePrimitiveList we can’t get a generic shape; we need individual subclasses. Therefore, this class variable defines how we return individual subclass instances from a SFFShapePrimitiveList.
-