.tgt.heapykinds.UniSet

Name

UniSet

Synopsis

For any object x of kind UniSet:

Methods
x.disjoint(y: UniSet+) -> boolean
x.get_ckc()
x.get_render() -> callable
Operators
bool(x) -> boolean
str(x) -> string
repr(x) -> string
~(x) -> UniSet
# x & y: UniSet+ -> UniSet
# x | y: UniSet+ -> UniSet
# x ^ y: UniSet+ -> UniSet
# x - y: UniSet+ -> UniSet
# y: Any+ in x -> boolean
# x == y: UniSet+ -> boolean
# x != y: UniSet+ -> boolean
# x <= y: UniSet+ -> boolean
# x < y: UniSet+ -> boolean
# x >= y: UniSet+ -> boolean
# x > y: UniSet+ -> boolean
Attributes
x.biper: EquivalenceRelation
x.brief: string
x.dictof: UniSet

Methods

x.disjoint(y: UniSet+) -> boolean
Returns True if x and y are disjoint sets, False otherwise. This is equivalent to calculating

not (x & y)

but may be implemented more efficiently in some cases.

x.get_ckc()
Get low-level classification information, where available. Returns a tuple (classifier, kind, comparator).
x.get_render() -> callable
Returns a function that may be used to render the representation of the elements of self.
This is mainly intended for internal representation support. The function returned depends on the kind of elements x contains. The rendering function is choosen so that it will be appropriate, and can be used safely, for all objects of that kind. For the most general kind of objects, the rendering function will only return an address representation. For more specialized kinds, the function may provide more information, and can be equivalent to the builtin repr() when the kind is narrow enough that it would work for all elements of that kind without exception.

Operators

bool(x) -> boolean
Returns True if self contains some element, False otherwise.
str(x) -> string
Convert the set to a printable string. The string is usually the same as the .brief attribute, but a major exception is the IdentitySet class.
repr(x) -> string
Convert the set to a printable string. This may be a more formal representation than str().
~(x) -> UniSet
Complement: the set of objects that are not in x.
x & y: UniSet+ -> UniSet
Intersection: the set of objects that are in both x and y.
x | y: UniSet+ -> UniSet
Union: the set of objects that are in either x or y.
x ^ y: UniSet+ -> UniSet
Symmetric set difference: the set of objects that are in exactly one of x and y.
x - y: UniSet+ -> UniSet
Set difference: the set of objects that are in x but not in y.
y: Any+ in x -> boolean
Inclusion test. True if y is a member of x, False otherwise.
x == y: UniSet+ -> boolean
Equal: x and y contain the same elements.
x != y: UniSet+ -> boolean
Not equal: x and y do not contain the same elements.
x <= y: UniSet+ -> boolean
Subset, non-strict: all elements in x are also in y.
x < y: UniSet+ -> boolean
Subset, strict: all elements in x are also in y, and y contains some element not in x.
x >= y: UniSet+ -> boolean
Superset, non-strict: all elements in y are also in x.
x > y: UniSet+ -> boolean
Superset, strict: all elements in y are also in x, and x contains some element not in y.

Attributes

x.biper: EquivalenceRelation
A bipartitioning equivalence relation based on x. This may be used to partition or classify sets into two equivalence classes:
x.biper(0) == x
The set of elements that are in x.
x.biper(1) == ~x
The set of elements that are not in x.
x.brief: string
A string representation of self, which is brief relative to the representation returned by str() and repr(). (In many cases it is the same - both are then brief - but for IdentitySet objects the brief representation is typically much shorter than the non-brief one.)
x.dictof: UniSet
If x represents a kind of objects with a builtin __dict__ attribute, x.dictof is the kind representing the set of all those dict objects. In effect, x.dictof maps lambda e:getattr(e, '__dict__') for all objects e in x. But it is symbolically evaluated to generate a new symbolic set (a Kind).

.tgt.heapykinds.Kind

Name

Kind

Synopsis

Subkind of: UniSet

Description

These are symbolic sets that contain no actual countable elements but only has a mechanism to determine if elements are contained in them or not. When combined with other symbolic sets via set operations (intersection, union etc) the result may be a new symbolic set or an IdentitySet depending on the sets and operations involved. For example, when intersected with IdentitySet, a new IdentitySet will be returned that contains only those element from the IdentitySet that were actually in the symbolic set.

Subkind of: UniSet

.tgt.heapykinds.KindWithAlt

Name

KindWithAlt

Synopsis

Subkind of: Kind
Method
alt(operator: AltOperator+) -> Kind

Description

These are symbolic sets (subkind of Kind) that have an alt method. The alt method works differently for different families of Kinds, but rather than specifying these separately, I have put the common part of the specification here for brevity.

Subkind of: Kind

Method

alt(operator: AltOperator+) -> Kind
Make a new kind that is modified according to an operator. If the operator is '==', the method is a no-op and just returns the original kind. If it is '!=', it returns the complement of the original kind, so it is a synonym for ~x. Otherwise the operator may be one of <, <=, >=, and >. The actual modification depends on the family of the original kind. See the particular kind family.

.tgt.heapykinds.KindOfTypeFamily

Name

KindOfTypeFamily

Synopsis

Subkind of: KindWithAlt

Description

A kind of this family includes all objects of one particular 'type', where the type is, in user terms, what is returned by the type() builtin and is implemented as the value of the ob_type field in C.
The kind returned by the alt method depends on its operator argument in the following way.
Operator Returned kind in terms of original type
< strict subtype
<= subtype
>= supertype
> strict supertype

Subkind of: KindWithAlt

.tgt.heapykinds.KindOfClassFamily

Name

KindOfClassFamily

Synopsis

Subkind of: KindWithAlt

Description

A kind of this family includes all objects of one particular 'class', where the class is the value of the builtin __class__ attribute. This is equal to type() unless the object is of an 'old-fashioned' class; then type() is <type 'instance'>.
The kind returned by the alt method depends on its operator argument in the following way.
Operator Returned kind in terms of original class
< strict subclass
<= subclass
>= superclass
> strict superclass

Subkind of: KindWithAlt

.tgt.heapykinds.KindOfSizeFamily

Name

KindOfSizeFamily

Synopsis

Subkind of: KindWithAlt

Description

The kind returned by the alt method depends on its operator argument in the following way.
Operator Returned kind in terms of original
< size < original
<= size <= original
>= size >= original
> size > original

Subkind of: KindWithAlt

.tgt.heapykinds.KindOfRetClaSetFamily

Name

KindOfRetClaSetFamily

Synopsis

Subkind of: KindWithAlt

Description

The kind returned by the alt method depends on its operator argument in the following way.
Operator Returned kind in terms of original
< referred by less than the original set of kinds
<= referred by at most the original set of kinds
>= referred by at least the original set of kinds
> referred by more than the original set of kinds

Subkind of: KindWithAlt

.tgt.heapykinds.KindOfInViaFamily

Name

KindOfInViaFamily

Synopsis

Subkind of: KindWithAlt

Description

The kind returned by the alt method depends on its operator argument in the following way.
Operator Returned kind in terms of original
< referred via less than the original set of relations
<= referred via at most the original set of relations
>= referred via at least the original set of relations
> referred via more than the original set of relations

Subkind of: KindWithAlt

.tgt.heapykinds.IdentitySet

Name

IdentitySet

Synopsis

Subkind of: UniSet

For any object x of kind IdentitySet:

Methods
x.by(er: EquivalenceRelation) -> IdentitySet
x.diff(y: IdentitySet) -> Stat
x.dump(fn: writeable_filename_or_file+ [mode = writing_mode_string+])
x.get_rp( draw:[depth = positive+ , er = EquivalenceRelation+ , imdom = boolean+ , bf = boolean+ , src = IdentitySet+ , stopkind = UniSet+ , nocyc = boolean+]) -> ReferencePattern
x.get_shpaths( draw:[src = IdentitySet+ , avoid_nodes = IdentitySet+ , avoid_edges = NodeGraph+]) -> Paths
Operators
hash(x) -> int
len(x) -> notnegative
Attributes
x.byclass: IdentitySet
x.byclodo: IdentitySet
x.byid: IdentitySet
x.bymodule: IdentitySet
x.byrcs: IdentitySet
x.bysize: IdentitySet
x.bytype: IdentitySet
x.byunity: IdentitySet
x.byvia: IdentitySet
x.count: notnegative
x.dominos: IdentitySet
x.domisize: notnegative
x.er: EquivalenceRelation
x.imdom: IdentitySet
x.indisize: notnegative
x.kind: Kind
x.maprox: MappingProxy
x.more: MorePrinter
x.nodes: ImmNodeSet
x.owners: IdentitySet
x.partition: Partition
x.parts: iterable
x.pathsin: Paths
x.pathsout: Paths
x.referents: IdentitySet
x.referrers: IdentitySet
x.rp: ReferencePattern
x.shpaths: Paths
x.size: notnegative
x.sp: Paths
x.stat: Stat

Subkind of: UniSet

Methods

x.by(er: EquivalenceRelation) -> IdentitySet
Returns a copy of x, but using a different equivalence relation for partitioning. That is, the er attribute of the copy will be set to the er argument.
See also
partition
x.diff(y: IdentitySet) -> Stat
Returns a statistics object that is the difference of the statistics of x and y, i.e. it is a shorthand for " x.stat - y.by(x.er).stat".
See also
stat
x.dump(fn: writeable_filename_or_file+ [mode = writing_mode_string+])
Dump statistical data to a file.
A shorthand for x.stat.dump.
Arguments
fn: writeable_filename_or_file+
A file name or open file to dump to.
mode = writing_mode_string+
The mode to open the file with, if not already open.
Default: 'a'
Per default, the file is opened in append mode.
See also
stat
x.get_rp( draw:[depth = positive+ , er = EquivalenceRelation+ , imdom = boolean+ , bf = boolean+ , src = IdentitySet+ , stopkind = UniSet+ , nocyc = boolean+]) -> ReferencePattern
Returns An object containing the pattern of references to the objects in x, including references to those referrers in turn. It has a string representation in the form of a tree of a certain maximum depth, with cycle patterns marked.
Arguments
depth = positive+
The depth to which the pattern will be generated.
Default: The depth attribute of the RefPat module glue.
er = EquivalenceRelation+
The equivalence relation to partition the referrers.
The default is to use the Use.Clodo equivalence relation
imdom = boolean+
If true, the immediate dominators will be used instead of the referrers. This will take longer time to calculate, but may be useful to reduce the complexity of the reference pattern.
Default: False
bf = boolean+
If true, the pattern will be printed in breadth-first order instead of depth-first. (Experimental.)
Default: False
src = IdentitySet+
An alternative reference source.
Default: The default heapy root.
stopkind = UniSet+
The referrers of objects of kind stopkind will not be followed.
The default is a kind representing a union of all modules, classes, types and their dicts; and also all code and frame objects. Actually, it is made by code like this:
stopkind = (
	    hp.Type.Module |
	    hp.Type.Class |
	    hp.Type.Type |
	    hp.Type.Module.dictof |
	    hp.Type.Class.dictof |
	    hp.Type.Type.dictof |
	    hp.Type.Code |
	    hp.Type.Frame
	    )
nocyc = boolean+
When True, certain cycles will not be followed.
Default: False
See also
rp, shpaths
x.get_shpaths( draw:[src = IdentitySet+ , avoid_nodes = IdentitySet+ , avoid_edges = NodeGraph+]) -> Paths
Returns an object containing the shortest paths to objects in x.
Arguments
src = IdentitySet+
An alternative source set of objects.
Default: The default heapy root.
avoid_nodes = IdentitySet+
Nodes to avoid
Default: No nodes are avoided, except those that
must be avoided to hide the data in the heapy system itself.
avoid_edges = NodeGraph+
Edges to avoid
Default: No edges are avoided.
See also
shpaths

Operators

hash(x) -> int
Hashing
Returns a hash value based on the addresses of the elements.
len(x) -> notnegative
Returns the number of different sets in the partitioning of x, as determined by its equivalence relation ( er ) attribute.
See also
partition

Attributes

x.byclass: IdentitySet
A copy of x, but with Use.Class as the equivalence relation.
x.byclodo: IdentitySet
A copy of x, but with Use.Clodo as the equivalence relation.
x.byid: IdentitySet
A copy of x, but with Use.Id as the equivalence relation.
x.bymodule: IdentitySet
A copy of x, but with Use.Module as the equivalence relation.
x.byrcs: IdentitySet
A copy of x, but with Use.Rcs as the equivalence relation.
x.bysize: IdentitySet
A copy of x, but with Use.Size as the equivalence relation.
x.bytype: IdentitySet
A copy of x, but with Use.Type as the equivalence relation.
x.byunity: IdentitySet
A copy of x, but with Use.Unity as the equivalence relation.
x.byvia: IdentitySet
A copy of x, but with Use.Via as the equivalence relation.
x.count: notnegative
The number of individual objects in x.
x.dominos: IdentitySet
The set 'dominated' by the set of objects in x. This is the objects that will become deallocated, directly or indirectly, when the objects in x are deallocated.
See also
domisize
x.domisize: notnegative
The dominated size of the set x. The dominated size of x is the total size of memory that will become deallocated, directly or indirectly, when the objects in x are deallocated.
See also
dominos, size
x.er: EquivalenceRelation
The Equivalence Relation of x, used for partitioning when representing / printing this set.
x.imdom: IdentitySet
The immediate dominators of x. The immediate dominators is a subset of the referrers. It includes only those referrers that are reachable directly, avoiding any other referrer.
x.indisize: notnegative
The total 'individual' size of the set of objects. The individual size of an object is the size of memory that is allocated directly in the object, not including any externally visible subobjects.
Synonym
size
See also
domisize
x.kind: Kind
The kind of objects in x. It is the union of the element-wise classifications as determined by the equivalence relation of x, er .
x.maprox: MappingProxy
An object that can be used to map operations to the objects in x, forming a new set of the result. This works as follows:
  • Getting an attribute of the MappingProxy object will get the attribute from each of the objects in the set and form a set of the results. If there was an exception when getting some attribute, it will be ignored.
  • Indexing the MappingProxy object will index into each of the objects in the set and return a set of the results. Exceptions will be ignored.
Example
>>> hp.iso({'a':'b'}, {'a':1}).maprox['a'].byid
Set of 2 <mixed> objects. Total size = 40 bytes.
 Index     Size   %   Cumulative  %   Brief
     0       28  70.0        28  70.0 str: 'b'
     1       12  30.0        40 100.0 int: 1
>>> 
x.more: MorePrinter
An object that can be used to show more lines of the string representation of x. The object returned, a MorePrinter instance, has a string representation that continues after the end of the representation of x.
x.nodes: ImmNodeSet
The actual objects contained in x. These are called nodes because they are treated with equality based on address, and not on the generalized equality that is used by ordinary builtin sets or dicts.
x.owners: IdentitySet
The set of objects that 'own' objects in x. The owner is defined for an object of type dict, as the object (if any) that refers to the object via its special __dict__ attribute.
x.partition: Partition
A partition of the set of objects in x. The set is partitioned into subsets by equal kind, as given by an equivalence relation. Unless otherwise specified, the equivalence relation used is 'byclodo', which means it classifies 'by type or class or dict owner'. Different equivalence relations can be specified by using 'by_...' attributes of any IdentitySet object.
See also
er, by, parts
x.parts: iterable
An iterable object, that can be used to iterate over the 'parts' of x, i.e. the subsets in the partitioning of x. The iteration order is determined by the sorting order of the partition. The partition is normally sorted with the subsets that have the larger total object size first, so the first element of x.parts will then be the subset in the partition of x that uses the most memory.
See also
partition
x.pathsin: Paths
The paths from the direct referrers of the objects in x.
x.pathsout: Paths
The paths to the referents of the objects in x.
x.referents: IdentitySet
The set of objects that are directly referred to by any of the objects in x.
x.referrers: IdentitySet
The set of objects that directly refer to any of the objects in x.
x.rp: ReferencePattern
The current pattern of references to the objects in x.
See also
get_rp
x.shpaths: Paths
An object containing the shortest paths to objects in x.
Synonym
sp
See also
get_shpaths
x.size: notnegative
The total 'individual' size of the set of objects. The individual size of an object is the size of memory that is allocated directly in the object, not including any externally visible subobjects.
Synonym
indisize
See also
domisize
x.sp: Paths
An object containing the shortest paths to objects in x.
Synonym
shpaths
See also
get_shpaths
x.stat: Stat
An object summarizing the statistics of the partitioning of x. This is useful when only the statistics is required, not the objects themselves. The statistics can be dumped to a file, unlike the set of objects itself.

.tgt.heapykinds.IdentitySetNotEmpty

Name

IdentitySetNotEmpty

Synopsis

Subkind of: IdentitySet

For any object x of kind IdentitySetNotEmpty:

Operator
# x[index: int+] -> IdentitySetNotEmpty

Description

Sets that contain at least one object.

Subkind of: IdentitySet

Operator

x[index: int+] -> IdentitySetNotEmpty
Indexing.
Returns the subset in the partition of x at index.
The partition is normally sorted with the subsets that have the larger total object size first, so for example x[0] will be the subset in the partition of x that uses the most memory.
See also
partition, parts

.tgt.heapykinds.IdentitySetSingleton

Name

IdentitySetSingleton

Synopsis

Subkind of: IdentitySetNotEmpty

For any object x of kind IdentitySetSingleton:

Attribute
x.theone: Any

Description

Sets that contain exactly one object.

Subkind of: IdentitySetNotEmpty

Attribute

x.theone: Any
The actual object that the set contains.

.tgt.heapykinds.EquivalenceRelation

Name

EquivalenceRelation

Synopsis

Subkind of: UniSet

For any object x of kind EquivalenceRelation:

Method
x.sokind() -> SetOfKind
Operators
# y: UniSet+ in x -> boolean
# x & y: EquivalenceRelation+ -> EquivalenceRelation
# x < y: EquivalenceRelation+ -> boolean
Attributes
x.dictof: EquivalenceRelationByDictOwner
x.refdby: EquivalenceRelation

Subkind of: UniSet

The operations of UniSet are supported by EquivalenceRelation as well, but some have a redefined behaviour which are described here.

Method

x.sokind() -> SetOfKind
Create a set of kinds; a set of equivalence classes of x. The arguments are the same as when calling x itself. One call to x.sokind returns a set of one equivalence class. This set is again callable, with the same kind of arguments. Each call will return a new set with one new equivalence class added to the previous set.
Returns an object that may be used to get at the corresponding referred-by equivalence class via its .refdby attribute.
Example
Show the objects in the heap that are referred from only the dict of __main__.
>>> from guppy import hpy; hp=hpy()
>>> hp.heap() & hp.Module.dictof.sokind(hp.Module('__main__')).refdby
Partition of a set of 1 object. Total size = 32 bytes.
 Index  Count   %     Size   % Cumulative  % Kind (class / dict of class)
     0      1 100       32 100        32 100 str
>>> 

Operators

y: UniSet+ in x -> boolean
Inclusion test. True if y is a member of x, False otherwise.

The members of an equivalence relation in this implementation are defined to be the subsets of its equivalence classes. The inclusion test can be used to see if all elements of a set classify equal according to the classifier of an equivalence relation.

Example
>>> from guppy import hpy; hp=hpy()
>>> hp.iso([],[]) in hp.Size # Equal sizes
True
>>> hp.iso([],range(100)) in hp.Size # Different sizes
False
>>> hp.iso([],range(100)) in hp.Type # Equal types
True
>>> hp.iso([],xrange(100)) in hp.Type # Different types
False
>>> 
>>> hp.Size(56) in hp.Size # An equivalence class of hp.Size
True
>>> hp.Type.Int in hp.Size # Not an equivalence class of hp.Size
False
Note
Mathematically equivalence relations are often modelled as set of pairs of equal elements, I considered to mimic this in the implementation of the inclusion test but found some problems and I think another model is more useful here.
x & y: EquivalenceRelation+ -> EquivalenceRelation
Intersection: the set of objects that are in both x and y.
When y is an equivalence relation, the result will be one of the arguments if that one was mathematically a subset of the other, or otherwise, which is the normally usable case, it will be a new equivalence relation that is a symbolic intersection of the two arguments. This can be used to partition a set based on a combination of classification criteria.
Example

>>> from guppy import hpy; hp=hpy()
>>> hp.iso(1, 10, [], [2], [3,4]).by(hp.Type & hp.Size)
Partition of a set of 5 objects. Total size = 172 bytes.
 Index  Count   %     Size   % Cumulative  % Type & Individual Size
     0      2  40      120  70       120  70 list & 60
     1      1  20       28  16       148  86 list & 28
     2      2  40       24  14       172 100 int & 12
>>> 
Note
When y is not an equivalence relation, the result will be a symbolic intersected UniSet, that is it can not be used for partitioning but may still be used for inclusion tests.
x < y: EquivalenceRelation+ -> boolean
Subset, also called subrelation, strict: all elements in x are also in y, and x and y are not equal.

An EquivalenceRelation can only be a subrelation of another EquivalenceRelation. This is an explicitly defined relationship among the equivalence relations. In most cases the equivalence relations are disjoint, i.e. none is a subrelation of the other. But it is useful to know which ones are actually subrelations. The following table shows for each pair of predefined relations, whether the one at the top of the column is a strict subrelation of the one at the end of the row. ( I have included Size & Type as an example of an intersected equivalence relation. )

Class Clodo Id Module Rcs Size Type Unity Size&Type
< Class
< Size
< < < Type
< < < < < < < < Unity
Generated by printrel.py at Nov 21 2005.
Example
Class is a subrelation of Type, since all objects with the same class also have the same type. On the other hand, Type is not a subrelation of Class, since objects with the same type (InstanceType) may be of different class.

>>> hp.Class < hp.Type
True
>>> hp.Type < hp.Class
False
>>> 
Note
The other relational operators are derived from this one.
Note
Id is currently not defined to be a subrelation of anything else except Unity, due to some subtle considerations.

Attributes

x.dictof: EquivalenceRelationByDictOwner
This attribute, when accessed, will contain a derived equivalence relation. This equivalence relation classifies objects either as not being a dict, or as being a dict owned by a particular kind. The owner, if any, is classified by x.
Example

>>> from guppy import hpy; hp=hpy()
>>> h=hp.heap()&dict
>>> h.by(hp.Size.dictof)
Partition of a set of 1512 objects. Total size = 715008 bytes.
 Index  Count   %     Size   % Cumulative  % Dict of Individual Size
     0    140   9   225056  31    225056  31 dict of        24
     1    336  22   172800  24    397856  56 dict of        44
     2    582  38   152112  21    549968  77 dict (no owner)
     3    347  23    92120  13    642088  90 dict of        32
This shows that there are 140 dicts that are owned by some objects of size 24, 336 dicts that are owned by some objects of size 44, 582 dicts without owner and so on.
x.refdby: EquivalenceRelation
This attribute, when accessed, creates a derived equivalence relation. It will classify objects according to the set of their referrer classification. The referrers are classified by x.

The Use.Rcs equivalence relation is a special case of this construction, where the underlying equivalence relation is Use.Clodo. :


>>> hp.Clodo.refdby == hp.Rcs
True

See also
Use.Rcs

.tgt.heapykinds.EquivalenceRelationByDictOwner

Name

EquivalenceRelationByDictOwner

Synopsis

Subkind of: EquivalenceRelation

For any object x of kind EquivalenceRelationByDictOwner:

Mapping
callable: x( alt:[k: None+ or k: Kind+]) -> Kind

Description

This equivalence relation classifies objects either as not being a dict, or as being a dict owned by a particular kind of objects. The owner, if any, is classified by the equivalence relation used to create x, usually via EquivalenceRelation.dictof .

Subkind of: EquivalenceRelation

Mapping

callable: x( alt:[k: None+ or k: Kind+]) -> Kind
Calling this equivalence relation creates a Kind object representing an equivalence class. The argument specifies if the kind should be about dicts at all, and in that case, the kind of dict owner.
Argument
k: None+
With a None argument, the returned equivalence class will be "all objects except dicts", i.e. ~hp.Type.Dict.
k: Kind+
If not None, the argument must be a Kind object. The returned kind will be the kind representing dicts that are owned by objects of the kind specified in arg. If the argument is Use.Nothing , the returned kind represents dicts with no owner.
Returns an equivalence class.
Note
To make the argument an equivalence class of x, the argument must be an equivalence class of the equivalence relation associated with the owner classification of x, though this is not currently checked.

Generated by GSL-HTML 0.1.5 on Thu Apr 25 17:37:59 2013