diff --git a/volatility/framework/interfaces/objects.py b/volatility/framework/interfaces/objects.py index 020fcd366..2237aac7c 100644 --- a/volatility/framework/interfaces/objects.py +++ b/volatility/framework/interfaces/objects.py @@ -109,9 +109,13 @@ class ObjectInterface(validity.ValidityRoutines, metaclass = ABCMeta): object_info = object_info) class VolTemplateProxy(object): - """A container for proxied methods that the ObjectTemplate of this object will call. + """A container for proxied methods that the ObjectTemplate of this object will call. This primarily to keep + methods together for easy organization/management, there is no significant need for it to be a separate class. - They are class methods rather than static methods, to allow for code reuse.""" + The methods of this class *must* be class methods rather than standard methods, to allow for code reuse. + Each method also takes a template since the templates may contain the necessary data about the + yet-to-be-constructed object. It allows objects to control how their templates respond without needing to write + new templates for each and every potental object type.""" @classmethod def size(cls, template): @@ -136,7 +140,24 @@ class ObjectInterface(validity.ValidityRoutines, metaclass = ABCMeta): class Template(validity.ValidityRoutines): """Class for all Factories that take offsets, and data layers and produce objects - This is effectively a class for currying object calls + This is effectively a class for currying object calls. It creates a callable that can be called with the following + parameters: + + :type context: ~volatility.framework.interfaces.context.ContextInterface + :type object_info: ObjectInformation + :param context: The context containing the memory layers and symbols required to construct the object + :param object_info: Basic information about the object, see the ObjectInformation class for more information + + :return: The constructed object + :rtype: ObjectInterface + + The keyword arguments handed to the constructor, along with the type_name are stored for later retrieval. + These will be access as `object.vol.` or `template.vol.` for each object and should contain + as least the basic information that each object will require before it is instantiated (so `offset` and `parent` + are explicitly not recorded here). This dictionary can be updated after construction, but any changes made + after that point will *not* be cloned. This is so that templates such as those for string objects may + contain different length limits, without affecting all other strings using the same template from a SymbolTable, + constructed at resolution time and then cached. """ def __init__(self, type_name, **arguments): @@ -148,14 +169,13 @@ class Template(validity.ValidityRoutines): @property def vol(self): - """Returns a volatility information object, much like the ObjectInterface provides""" + """Returns a volatility information object, much like the :class:`ObjectInterface` provides""" return ReadOnlyMapping(self._vol) @property def children(self): - """A function that returns a list of child templates of a template - - This is used to traverse the template tree + """The children of this template (such as member types, subtypes and base_types where they are relevant). + Used to traverse the template tree. """ return [] @@ -166,14 +186,11 @@ class Template(validity.ValidityRoutines): @abstractmethod def relative_child_offset(self, child): - """A function that returns the relative offset of a child from its parent offset - - This may throw exceptions including ChildNotFoundException and NotImplementedError - """ + """Returns the relative offset of the `child` member from its parent offset""" @abstractmethod def replace_child(self, old_child, new_child): - """A function for replacing one child with another""" + """Replaces `old_child` with `new_child` in the list of children""" def clone(self): """Returns a copy of the original Template as constructed (without update_vol having been called)""" @@ -192,12 +209,4 @@ class Template(validity.ValidityRoutines): raise AttributeError("{} object has no attribute {}".format(self.__class__.__name__, attr)) def __call__(self, context, object_info): - """Constructs the object - - :type context: framework.interfaces.context.ContextInterface - :type object_info: ObjectInformation - :param context: - :param object_info: - - :return O Returns: an object adhering to the Object interface - """ + """Constructs the object""" diff --git a/volatility/framework/objects/templates.py b/volatility/framework/objects/templates.py index 6cde8f405..e53ca7aab 100644 --- a/volatility/framework/objects/templates.py +++ b/volatility/framework/objects/templates.py @@ -28,26 +28,22 @@ class ObjectTemplate(interfaces.objects.Template, validity.ValidityRoutines): @property def size(self): - """Returns the size of the template""" + """Returns the children of the templated object (see :class:`~volatility.framework.interfaces.objects.ObjectInterface.VolTemplateProxy`)""" return self.vol.object_class.VolTemplateProxy.size(self) @property def children(self): - """A function that returns a list of child templates of a template - - This is used to traverse the template tree + """Returns the children of the templated object (see :class:`~volatility.framework.interfaces.objects.ObjectInterface.VolTemplateProxy`) """ return self.vol.object_class.VolTemplateProxy.children(self) def relative_child_offset(self, child): - """A function that returns the relative offset of a child from its parent offset - - This may throw exceptions including ChildNotFoundException and NotImplementedError + """Returns the relative offset of a child of the templated object (see :class:`~volatility.framework.interfaces.objects.ObjectInterface.VolTemplateProxy`) """ return self.vol.object_class.VolTemplateProxy.relative_child_offset(self, child) def replace_child(self, old_child, new_child): - """A function for replacing one child with another + """Replaces `old_child` for `new_child` in the templated object's child list (see :class:`~volatility.framework.interfaces.objects.ObjectInterface.VolTemplateProxy`) """ return self.vol.object_class.VolTemplateProxy.replace_child(self, old_child, new_child) @@ -67,7 +63,8 @@ class ObjectTemplate(interfaces.objects.Template, validity.ValidityRoutines): class ReferenceTemplate(interfaces.objects.Template): """Factory class that produces objects based on a delayed reference type - It should not return any attributes + Attempts to access any standard attributes of a resolved template will result in a + :class:`~volatility.framework.exceptions.SymbolError`. """ @property diff --git a/volatility/framework/validity.py b/volatility/framework/validity.py index 6b4eabcf2..6f1098759 100644 --- a/volatility/framework/validity.py +++ b/volatility/framework/validity.py @@ -1,12 +1,16 @@ -""" -Created on 4 May 2013 - -@author: mike +"""A set of classes providing consistent type checking and error handling for type/class validity """ class ValidityRoutines(object): - """Class to hold all validation routines, such as type checking""" + """Class to hold all validation routines, such as type checking + + Contains only private class methods, including `_check_type(cls, value, valid_type)` and + `_check_class(cls, klass, valid_class)`. These may eventually be made obsolete by PEP 484 + and appropriate static type verification by software such as mypy. + + These are currently implemented by assertions that will be optimized out of production code. + """ @classmethod def _check_type(cls, value, valid_type):