UniSet

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

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.

Get low-level classification information, where available. Returns a tuple (classifier, kind, comparator).

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.

Returns True if self contains some element, False otherwise.

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.

Convert the set to a printable string. This may be a more formal representation than str().

Complement: the set of objects that are not in x.

Intersection: the set of objects that are in both x and y.

Union: the set of objects that are in either x or y.

Symmetric set difference: the set of objects that are in exactly one of x and y.

Set difference: the set of objects that are in x but not in y.

Inclusion test. True if y is a member of x, False otherwise.

Equal: x and y contain the same elements.

Not equal: x and y do not contain the same elements.

Subset, non-strict: all elements in x are also in y.

Subset, strict: all elements in x are also in y, and y contains some element not in x.

Superset, non-strict: all elements in y are also in x.

Superset, strict: all elements in y are also in x, and x contains some element not in y.

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.

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.)

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).

Kind

Subkind of: UniSet

KindWithAlt

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.

KindOfProdFamily

Subkind of: KindWithAlt

KindOfTypeFamily

Subkind of: KindWithAlt

KindOfSizeFamily

Subkind of: KindWithAlt

KindOfRetClaSetFamily

Subkind of: KindWithAlt

KindOfInViaFamily

Subkind of: KindWithAlt

IdentitySet

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.byclodo: IdentitySet

x.byid: IdentitySet

x.bymodule: IdentitySet

x.byprod: 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.all: 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

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

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

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

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, 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.Type |
	    hp.Type.Module.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

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

Hashing

Returns a hash value based on the addresses of the elements.

Returns the number of different sets in the partitioning of x, as determined by its equivalence relation ( er ) attribute.

See also

partition

A copy of x, but with Use.Clodo as the equivalence relation.

A copy of x, but with Use.Id as the equivalence relation.

A copy of x, but with Use.Module as the equivalence relation.

A copy of x, but with Use.Prod as the equivalence relation.

A copy of x, but with Use.Rcs as the equivalence relation.

A copy of x, but with Use.Size as the equivalence relation.

A copy of x, but with Use.Type as the equivalence relation.

A copy of x, but with Use.Unity as the equivalence relation.

A copy of x, but with Use.Via as the equivalence relation.

The number of individual objects in x.

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

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

The Equivalence Relation of x, used for partitioning when representing / printing this set.

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.

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

The kind of objects in x. It is the union of the element-wise classifications as determined by the equivalence relation of x, er .

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

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.

An object that can be used to show all lines of the string representation of x.

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.

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.

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 dict owner'. Different equivalence relations can be specified by using 'by_...' attributes of any IdentitySet object.

See also

er, by, parts

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

The paths from the direct referrers of the objects in x.

The paths to the referents of the objects in x.

The set of objects that are directly referred to by any of the objects in x.

The set of objects that directly refer to any of the objects in x.

The current pattern of references to the objects in x.

See also

get_rp

An object containing the shortest paths to objects in x.

Synonym

sp

See also

get_shpaths

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

An object containing the shortest paths to objects in x.

Synonym

shpaths

See also

get_shpaths

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.

IdentitySetNotEmpty

Subkind of: IdentitySet

For any object x of kind IdentitySetNotEmpty:

Operator

# x[index: int+] -> IdentitySetNotEmpty

Returns the subset in the partition of x at index.

See also

partition, parts

IdentitySetSingleton

Subkind of: IdentitySetNotEmpty

For any object x of kind IdentitySetSingleton:

Attributes

x.prod: MorePrinter

x.theone: Any

The traceback for the producer for the one object.

The actual object that the set contains.

EquivalenceRelation

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

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 2 objects. Total size = 305 bytes.
 Index  Count   %     Size   % Cumulative  % Kind (class / dict of class)
     0      1  50      248  81       248  81 dict (no owner)
     1      1  50       57  19       305 100 str
>>>

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.

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 = 296 bytes.
 Index  Count   %     Size   % Cumulative  % Type & Individual Size
     0      1  20       88  30        88  30 list & 88
     1      1  20       80  27       168  57 list & 80
     2      1  20       72  24       240  81 list & 72
     3      2  40       56  19       296 100 int & 28
>>>

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.

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. )

Clodo	Id	Module	Rcs	Size	Type	Unity	Size&Type
							<	Size
<							<	Type
<	<	<	<	<	<		<	Unity

Generated by printrel.py at Nov 21 2005.

Example (outdated)

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.

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 1013 objects. Total size = 529512 bytes.
 Index  Count   %     Size   % Cumulative  % Dict of Individual Size
     0     79   8   139704  26    139704  26 dict of        88
     1    198  20   114712  22    254416  48 dict of       400
     2    167  16    92384  17    346800  65 dict of      1064
     3    172  17    81712  15    428512  81 dict (no owner)
     4     53   5    29304   6    457816  86 dict of       896

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.

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

EquivalenceRelationByDictOwner

Subkind of: EquivalenceRelation

For any object x of kind EquivalenceRelationByDictOwner:

Mapping

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