.import:: Any, boolean, int, CommonSet, iterable, notnegative, string, callable
..from: kindnames

.import:: boolean+, int+, positive+, NodeGraph+, Any+
..from: kindnames

.import:: EquivalenceRelation, Helper,

IdentitySet, IdentitySetNotEmpty, IdentitySetSingleton,
Kind, KindOfSizeFamily, KindOfInViaFamily,
KindOfRetClaSetFamily,
KindOfTypeFamily, KindWithAlt,
MappingProxy,
MorePrinter,
Partition, Paths, ReferencePattern,

Stat, UniSet, UniSetAvantGarde, Use

..from: heapykinds

.import:: IdentitySet+, EquivalenceRelation+, UniSet+
..from: heapykinds

.import:: AltOperator+, writeable_filename_or_file+, writing_mode_string+
..from: heapykinds

.import:: ImmNodeSet
..from: kindnames

.and: UniSet
..self: x

..fop: bool
...returns: boolean
....d: True if self contains some element, False otherwise.

..fop: str
...d: 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.
...returns: string

..fop: repr
...d: Convert the set to a printable string.
This may be a more formal representation than str().
...returns: string

..fop: ~
...returns: UniSet
...d: Complement: the set of objects that are not in x.

..op: &
...d:
Intersection: the set of objects that are in both x and y.
...arg: y: UniSet+
...returns: UniSet

..op: |
...d:
Union: the set of objects that are in either x or y.
...arg: y: UniSet+
...returns: UniSet

..op: ^
...d:
Symmetric set difference: the set of objects that are in exactly one of x and y.
...arg: y: UniSet+
...returns: UniSet

..op: -
...d:
Set difference: the set of objects that are in x but not in y.
...arg: y: UniSet+
...returns: UniSet

..rop: in
...d:
Inclusion test. True if y is a member of x, False otherwise.
...arg: y: Any+
...returns: boolean

..op: ==
...d:
Equal:
    x and y contain the same elements.

...arg: y: UniSet+
...returns: boolean

..op: !=
...d:
Not equal:
             x and y do not contain the same elements.

...arg: y: UniSet+
...returns: boolean

..op: <=
...d:
Subset, non-strict:
             all elements in x are also in y.
...arg: y: UniSet+
...returns: boolean

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

...arg: y: UniSet+
...returns: boolean

..op: >=
...d:
Superset, non-strict:
             all elements in y are also in x.

...arg: y: UniSet+
...returns: boolean

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

...arg: y: UniSet+
...returns: boolean

..attr:: biper
...kind of: EquivalenceRelation

...d: A bipartitioning equivalence relation based on x.
This may be used to partition or classify sets into two equivalence
classes:
....dl
.....dt: x.biper(0) == x
.....dd: The set of elements that are in x.
......c: [This is really the same
as x, but the system doesn't really understand this right now wrt
the equality operator etc. XXX/BUG/TODO]
.....dt: x.biper(1) == ~x
.....dd: The set of elements that are not in x.
......c: XXX [ But see above ]

..attr:: brief
...kind of: string
...d
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.)

..attr:: dictof
...kind of: UniSet
...d: 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).
....c: XXX [Even if x was an IdentitySet should this change?]

..method:: disjoint
...arg: y: UniSet+

...returns: boolean
....d: True if x and y are disjoint sets, False otherwise. This
is equivalent to calculating
.....p: not (x & y)
.....p: but may be implemented more efficiently in some cases.


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

..method:: get_render
...returns: callable
....d: a function that may be used to render the representation
of the elements of self.

...d: 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.


.and:: UniSetAvantGarde
..d: Experimental features.
These may not work at all or well right now
but I let this be the place to put tentative
documentation about them.

..subkind of: UniSet

..op: *
...d:
Cartesian product: the set of pairs of objects that are in x and y,
respectively.
...arg: y: UniSet+
...returns: UniSet+

..op: <<
...d: Mapping constructor

..method:: get_examples

...d: Return an iterable object or an iterator, which provides
some examples of the elements of x.  (A minimum of 2 examples should
normally be provided, but it may depend on some test configuration
options.)

....p: This is used for automatic test generation from specifications.
The env argument is according to specification of TestEnv in Spec.py,

..method:: test_contains



.and: Kind
..subkind of: UniSet

..d: 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
...ref: .myfile.IdentitySet
...t: 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.


.and: KindWithAlt
..subkind of: Kind

..d: 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.

..method:: alt

...d: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.

...arg: operator: AltOperator+
...returns: Kind

.and: KindOfTypeFamily
..subkind of: KindWithAlt

..d: 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.

..d: The kind returned by the alt method depends on its operator argument
in the following way.
...table
....tr
.....th: Operator
.....th: Returned kind in terms of original type
....tr
.....td: <
.....td: strict subtype
....tr
.....td: <=
.....td: subtype
....tr
.....td: >=
.....td: supertype
....tr
.....td: >
.....td: strict supertype

.and: KindOfSizeFamily
..subkind of: KindWithAlt
..d: The kind returned by the alt method depends on its operator argument
in the following way.
...table
....tr
.....th: Operator
.....th: Returned kind in terms of original
....tr
.....td: <
.....td: size < original
....tr
.....td: <=
.....td: size <= original
....tr
.....td: >=
.....td: size >= original
....tr
.....td: >
.....td: size > original

.and: KindOfRetClaSetFamily
..subkind of: KindWithAlt
..d: The kind returned by the alt method depends on its operator argument
in the following way.
...table
....tr
.....th: Operator
.....th: Returned kind in terms of original
....tr
.....td: <
.....td: referred by less than the original set of kinds
....tr
.....td: <=
.....td: referred by at most the original set of kinds
....tr
.....td: >=
.....td: referred by at least the original set of kinds
....tr
.....td: >
.....td: referred by more than the original set of kinds

.and: KindOfInViaFamily
..subkind of: KindWithAlt
..d: The kind returned by the alt method depends on its operator argument
in the following way.
...table
....tr
.....th: Operator
.....th: Returned kind in terms of original
....tr
.....td: <
.....td: referred via less than the original set of relations
....tr
.....td: <=
.....td: referred via at most the original set of relations
....tr
.....td: >=
.....td: referred via at least the original set of relations
....tr
.....td: >
.....td: referred via more than the original set of relations


.and: IdentitySet
..self: x
..subkind of: UniSet

..attr:: byclodo
...kind of: IdentitySet

...d: A copy of x, but with
....ref: .myfile.Use.Clodo
....t: as the equivalence relation.

..attr:: byid
...kind of: IdentitySet

...d: A copy of x, but with
....ref: .myfile.Use.Id
....t: as the equivalence relation.

..attr:: bymodule
...kind of: IdentitySet

...d: A copy of x, but with
....ref: .myfile.Use.Module
....t: as the equivalence relation.

..attr:: byrcs
...kind of: IdentitySet

...d: A copy of x, but with
....ref: .myfile.Use.Rcs
....t: as the equivalence relation.

..attr:: bysize
...kind of: IdentitySet

...d: A copy of x, but with
....ref: .myfile.Use.Size
....t: as the equivalence relation.

..attr:: bytype
...kind of: IdentitySet

...d: A copy of x, but with
....ref: .myfile.Use.Type
....t: as the equivalence relation.

..attr:: byunity
...kind of: IdentitySet

...d: A copy of x, but with
....ref: .myfile.Use.Unity
....t: as the equivalence relation.

..attr:: byvia
...kind of: IdentitySet

...d: A copy of x, but with
....ref: .myfile.Use.Via
....t: as the equivalence relation.

..attr:: count
...kind of: notnegative

...d: The number of individual objects in x.

..attr:: dominos
...kind of: IdentitySet

...d: 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.

...dwh: See also
....ref: .mykind.domisize

..attr:: domisize
...kind of: notnegative

...d: 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.

...dwh: See also
....ref: .mykind.dominos
....t:,
....ref: .mykind.size

..attr:: er
...kind of: EquivalenceRelation

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

..c
...attr:: help
....kind of: Helper

....d: Help information for x.

..attr:: imdom
...kind of: IdentitySet

...d: 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.

..attr:: indisize
...kind of: notnegative

...d: 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.

...dwh: Synonym
....ref: .mykind.size
...dwh: See also
....ref: .mykind.domisize

..attr:: kind
...kind of: Kind

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

..attr:: maprox
...kind of: MappingProxy

...d: 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:

....ul
.....li
  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.
.....li
  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.
...dwh: Example
....pre
>>> 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
>>>
...c: end dwh

..attr:: more
...kind of: MorePrinter

...d: 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.

..attr:: nodes
...kind of: ImmNodeSet

...d: 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.

..attr:: owners
...kind of: IdentitySet

...d: 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.

..attr:: partition
...kind of: Partition

...d: 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.

...dwh: See also
....ref: .mykind.er
....t:,
....ref: .mykind.by
....t:,
....ref: .mykind.parts

..attr:: parts
...kind of: iterable
...c: XXX really iterable of IdentitySet
...c: this needs more support to specify & test

...d: 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.

...dwh: See also
....ref: .mykind.partition

..attr:: pathsin
...kind of: Paths

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

..attr:: pathsout
...kind of: Paths

...d: The paths to the referents of the objects in x.

..attr:: referents
...kind of: IdentitySet

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

..attr:: referrers
...kind of: IdentitySet

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

..attr:: rp
...kind of: ReferencePattern

...d: The current pattern of references to the objects in x.

...dwh: See also
....ref: .mykind.get_rp

..attr:: shpaths
...kind of: Paths

...d: An object containing the shortest paths to objects in x.

...dwh: Synonym
....ref: .mykind.sp

...dwh: See also
....ref: .mykind.get_shpaths

..attr:: size
...kind of: notnegative

...d: 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.

...dwh: Synonym
....ref: .mykind.indisize
...dwh: See also
....ref: .mykind.domisize

..attr:: sp
...kind of: Paths

...d: An object containing the shortest paths to objects in x.

...dwh: Synonym
....ref: .mykind.shpaths

...dwh: See also
....ref: .mykind.get_shpaths

..attr:: stat
...kind of: Stat

...d: 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.

..fop: hash
...d: Hashing
...returns: int
....d: a hash value based on the addresses of the elements.

..fop: len
...returns: notnegative
....d: the number of different sets in the partitioning of x, as determined
by its equivalence relation (
.....ref: .mykind.er
.....t:) attribute.

...dwh: See also
....ref: .mykind.partition

..method:: by
...returns: IdentitySet
....d: a copy of x, but using a different equivalence relation for
partitioning. That is, the
.....ref: .mykind.er
.....t: attribute of the copy will be set to the er argument.
...arg: er: EquivalenceRelation

...dwh: See also
....ref: .mykind.partition

..method:: diff
...returns: Stat
....d: a statistics object that is the difference of the statistics
of x and y, i.e. it is a shorthand for "
.....code: x.stat - y.by(x.er).stat
.....t:".
...arg: y: IdentitySet

...dwh: See also
....ref: .mykind.stat

..method:: dump
...d: Dump statistical data to a file.
...d: A shorthand for x.stat.dump.
...arg: fn: writeable_filename_or_file+
....d: A file name or open file to dump to.
...optionals
....key arg: mode:writing_mode_string+
.....d: The mode to open the file with, if not already open.
.....default: 'a'
......t: Per default, the file is opened in append mode.
...dwh: See also
....ref: .mykind.stat



..method:: get_rp
...returns: ReferencePattern

....d: 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.

...draw
....key arg: depth:positive+
.....d:	The depth to which the pattern will be generated.
.....default: The depth attribute of the RefPat module glue.
.....c: XXX move to Use or add setter?

....key arg: er: EquivalenceRelation+
.....d: The equivalence relation to partition the referrers.
.....d: The default is to use the
......ref: .myfile.Use.Clodo
......t: equivalence relation

....key arg: imdom: boolean+
.....d:	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

....key arg: bf: boolean+
.....d:	If true, the pattern will be printed in breadth-first
	order instead of depth-first. (Experimental.)
.....default: False

....key arg: src: IdentitySet+
.....d:	An alternative reference source.
.....default: The default heapy root.
.....c: XXX reference this

....key arg: stopkind: UniSet+
.....d: The referrers of objects of kind stopkind will not be followed.
.....d: 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:
......pre
stopkind = (
	    hp.Type.Module |
	    hp.Type.Type |
	    hp.Type.Module.dictof |
	    hp.Type.Type.dictof |
	    hp.Type.Code |
	    hp.Type.Frame
	    )
......c: end pre
....key arg: nocyc: boolean+
.....d: When True, certain cycles will not be followed.
......c: XXX expand on this or remove.
.....default: False

...dwh: See also
....ref: .mykind.rp
....t:,
....ref: .mykind.shpaths

..method:: get_shpaths
...returns: Paths
....d: an object containing the shortest paths to objects in x.
...draw
....key arg: src:IdentitySet+
.....d: An alternative source set of objects.
.....default: The default heapy root.
.....c: XXX reference this

....key arg: avoid_nodes:IdentitySet+
.....d: Nodes to avoid
.....default: No nodes are avoided, except those that
must be avoided to hide the data in the heapy system itself.

....key arg: avoid_edges:NodeGraph+
.....d: Edges to avoid
.....default: No edges are avoided.

...dwh: See also
....ref: .mykind.shpaths

.and:: IdentitySetNotEmpty
..self: x
..subkind of: IdentitySet
..d: Sets that contain at least one object.

..getitem
...arg: index:int+
...d: Indexing.
...returns: IdentitySetNotEmpty

....d: the subset in the partition of x at index.
...d: The partition is
normally sorted with the subsets that have the larger total object
size first, so for example
....code: x[0]
....t: will be the subset in the partition of x that uses the most memory.

...dwh: See also
....ref: .mykind.partition
....t:,
....ref: .mykind.parts


.and:: IdentitySetSingleton
..self: x
..subkind of: IdentitySetNotEmpty
..d: Sets that contain exactly one object.
..attr:: theone
...kind of: Any
...d: The actual object that the set contains.
