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 attributes

The adapter classes specify class attributes as accessors of values in the generateDS API. These are accomplished using this class to get, set and delete values taking into account translation between the adapter and the generateDS 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

`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, the SFFSegmentList objects are a list of SFFSegment 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`

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 arguments
Returns:	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

Return int status:
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:
	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 object

Notice 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 validation

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 corresponding SFF* object
Return type:	`base.SFFType` subclass

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 the sfftkrw.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 the repr_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 object

Notice 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

static update_index(cls, obj, current, **kwargs)¶

Set the index value in obj and return the next value

Parameters:	cls – the class of obj current (int) – the current value of the index obj – the instance kwargs – keyword arguments
Return next:	the next value of the index
Rtype nex:	int

`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 object

Notice 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 to

The 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 called test 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 the emdb_sff module;
i is an iterable attribute of test;
i is adapted by the SFFItem class (which should have its gds_type set to the class for i);

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]
```

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 of SFFCone, SFFCuboid, SFFCylinder and SFFEllipsoid. This is because the SFFShape 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.