aiatools package¶

AIA Tools provides a set of Python classes to interface with application sources exported from App Inventor.

Submodules¶

aiatools.aia module¶

The aiatools.aia package provides the AIAFile class for reading App Inventor (.aia) projects.

class aiatools.aia.AIAAsset(zipfile, name)[source]¶

Bases: object

AIAAsset provides an interface for reading the contents of assets from an App Inventor project.

open(mode='r')[source]¶

Opens the asset. mode is an optional file access mode.

Parameters: mode (basestring) – The access mode to use when accessing the asset. Must be one of ‘r’, ‘rU’, or ‘U’.
Returns: A file-like for accessing the contents of the asset.
Return type: zipfile.ZipExtFile

class aiatools.aia.AIAFile(filename, strict=False)[source]¶

Bases: object

AIAFile encapsulates an App Inventor project (AIA) file.

Opens an App Inventor project (AIA) with the given filename. filename can be any file-like object that is acceptable to ZipFile’s constructor, or a path to a directory containing an unzipped project.

Parameters

filename (basestring | file) – A string or file-like containing the contents of an App Inventor project.
strict (bool, optional) – Process the AIAFile in strict mode, i.e., if a blocks file is missing then it is an error. Default: false

assets = None¶

A list of assets contained in the project.

Type: list[aiatools.aia.AIAAsset]

blocks = None¶

A Selector over the blocks of all screen defined in the project.

For example, if you want to know how many blocks are in a project run:

>>> with AIAFile('test_aias/LondonCholeraMap.aia') as aia:
...     len(aia.blocks())
23

Type: aiatools.selectors.Selector[aiatools.common.Block]

close()[source]¶

components = None¶

A Selector over the component instances of all screens defined in the project.

For example, if you want to know how many component instances are in a project run:

>>> with AIAFile('test_aias/LondonCholeraMap.aia') as aia:
...     len(aia.components())  # Form, Map, Marker, Button
4

Type: aiatools.selectors.Selector[aiatools.common.Component]

filename = None¶

The filename or file-like that is the source of the project.

Type: basestring or file

properties = None¶

The contents of the project.properties file.

Type: Properties

screens = None¶

A Selector over the components of type Screen in the project.

For example, if you want to know how many screens are in a project run:

>>> with AIAFile('test_aias/LondonCholeraMap.aia') as aia:
...     len(aia.screens)
1

Type: aiatools.selectors.Selector[aiatools.component_types.Screen]

aiatools.algebra module¶

aiatools.algebra defines the expressions and evaluation rules for querying the contents of AIA files.

class aiatools.algebra.AndExpression(left, right)[source]¶: Bases: aiatools.algebra.BinaryExpression

class aiatools.algebra.Atom[source]¶

Bases: aiatools.algebra.Expression

Atom represents an entity in the grammar, such as a specific component type (Button) or block type (component_set_get). Atoms cannot be modified and evaluate to themselves.

class aiatools.algebra.BinaryExpression(left, right)[source]¶

Bases: aiatools.algebra.Expression

Abstract base class for an Expression taking two clauses.

Concrete implementations of this class must provide an implementation of the __call__ special method to evaluate the truth value of the left and right hand sides.

Parameters

left (Expression) – The left hand side of the binary expression.
right (Expression) – The right hand side of the binary expression.

class aiatools.algebra.Collection(collection)[source]¶

Bases: aiatools.algebra.Atom

Collection is an Atom wrapping a collection, such as a list or tuple, of entities. Calls to the Collection will filter the collection given an Expression.

Parameters: collection (collections.Iterable[aiatools.common.Component|aiatools.common.Block]) – The Python collection of entities to be wrapped into the new atomic collection.

class aiatools.algebra.ComputedAttribute(functor)[source]¶

Bases: aiatools.algebra.Functor

ComputedAttribute is a Functor that wraps a Python function or lambda expression. This allows for arbitrary computations to be used in evaluating entities in a project.

Parameters: functor (callback) – The functor that should be applied to the entity when the ComputedAttribute needs to be computed. Note that the return value is not memoized, so the given functor should be time efficient as possible when computing its value.

equals(other)[source]¶

class aiatools.algebra.EquivalenceExpression(left, right)[source]¶

Bases: aiatools.algebra.BinaryExpression

EquivalenceExpression compares the output of two expressions for equivalent values, however == is defined on those values. An EquivalenceExpression is typically constructed by using the == operator on an existing pair of expressions, for example:

>>> from aiatools.attributes import name
>>> name == 'Button1'
NamedAttributeTuple(('name', 'instance_name')) == 'Button1'

class aiatools.algebra.Expression[source]¶

Bases: object

Base interface for constructing expressions over App Inventor projects.

Expressions by default support the following operations:

left == right: Accepts an entity if and only if left(entity) == right(entity)
left != right: Accepts an entity if and only if left(entity) != right(entity)
left < right: Accepts an entity if and only if left(entity) < right(entity)
left > right: Accepts an entity if and only if left(entity) > right(entity)
left <= right: Accepts an entity if and only if left(entity) <= right(entity)
left >= righ: Accepts an entity if and only if left(entity >= right(entity)
left & right: Accepts an entity if and only if left(entity) and right(entity) is True.
left | right: Accepts an entity if and only if left(entity) or right(entity) is True.
~expr: Accepts an entity if and only if not expr(entity) is True

class aiatools.algebra.FunctionComposition(*args)[source]¶

Bases: aiatools.algebra.Functor

ComposedAttribute is a Functor that wraps other Functors, Python functions, or lambda expressions. Functions are evaluated from left to right.

>>> from aiatools import *
>>> isinstance(root_block(declaration), FunctionComposition)
True
>>> proctest = AIAFile('test_aias/ProcedureTest2.aia')
>>> proctest.blocks(is_procedure).callers(root_block(declaration)).map(fields.PROCNAME)
['i_am_called']

Parameters: *args – Functions to compose into a new function

class aiatools.algebra.Functor[source]¶

Bases: aiatools.algebra.Expression

Functor is an abstract base class that serves as the root of the class tree of classes that apply functions to entities. Unlike most expressions, these typically compute non-Boolean values that may then undergo further computation.

class aiatools.algebra.GreaterThanExpression(left, right)[source]¶

Bases: aiatools.algebra.BinaryExpression

GreaterThanExpression compares the output of two expressions and returns True if the value of the left handl side of the expression is greater than the value of the right hand expression, for the definition of the greater than operation on the two values. A GreaterThanExpression is typically constructed by using the > operator on an existing pair of expressions, for example:

>>> from aiatools.attributes import version
>>> version > 5
NamedAttribute('version') > 5

class aiatools.algebra.GreaterThanOrEqualExpression(left, right)[source]¶: Bases: aiatools.algebra.BinaryExpression

class aiatools.algebra.LessThanExpression(left, right)[source]¶

Bases: aiatools.algebra.BinaryExpression

LessThanExpression compares the output of two expressions and returns True if the value of the left hand side of the expression is less than the value of the right hand expression, for the definition of the less than operation on the two values. A LessThanExpression is typically constructed by using the < operator on an existing pair of expressions, for example:

>>> from aiatools.attributes import version
>>> version < 5
NamedAttribute('version') < 5

class aiatools.algebra.LessThanOrEqualExpression(left, right)[source]¶: Bases: aiatools.algebra.BinaryExpression

class aiatools.algebra.NonequivalenceExpression(left, right)[source]¶

Bases: aiatools.algebra.BinaryExpression

NonequivalenceExpression compares the output of two expressions for nonequivalent values, however != is defined on those values. A NonequivalenceExpression is typically constructed by using the != operator on an existing pair of expressions, for example:

>>> from aiatools.attributes import name
>>> name != 'Button1'
NamedAttributeTuple(('name', 'instance_name')) != 'Button1'

class aiatools.algebra.NotExpression(expr)[source]¶

Bases: aiatools.algebra.Expression

NotExpression is a unary expression that logically negates the output of the expression it encapsulates. NotExpressions are typically instantiated by using the unary prefix operator ~ to invert the expression. Note that ~ binds tightly, so most expressions, unless they are Atom, must be wrapped in parentheses.

Note

NotExpression will optimize its own inversion so that two operators will cancel one another out. For example:

>>> from aiatools.attributes import disabled
>>> ~disabled
~NamedAttribute('disabled')
>>> ~~disabled
NamedAttribute('disabled')

Parameters: expr (Expression) – The expression to negate.

class aiatools.algebra.OrExpression(left, right)[source]¶: Bases: aiatools.algebra.BinaryExpression

aiatools.algebra.and_¶: alias of aiatools.algebra.AndExpression

aiatools.algebra.identity(x)[source]¶

Helper function that returns its input.

>>> identity("string")
'string'
>>> identity(True)
True
>>> identity(None)

Parameters: x – any value
Returns: x

aiatools.algebra.needs_eval(x)[source]¶

Tests whether its input needs ot be evaluated.

>>> needs_eval(Expression())
True
>>> needs_eval(Atom())
False

Parameters: x (Expression|callable) – the input expression
Returns

aiatools.algebra.not_¶: alias of aiatools.algebra.NotExpression

aiatools.algebra.or_¶: alias of aiatools.algebra.OrExpression

aiatools.attributes module¶

The aiatools.attributes module provides Functor for querying App Inventor projects.

class aiatools.attributes.DepthAttribute[source]¶

Bases: aiatools.algebra.Functor

DepthAttribute class is used to memoize the depths of entities in the forest representing an App Inventor project. Use aiatools.attributes.depth to benefit from the memoization feature.

Example

Get the depth of all leaves in the project.

>>> project.blocks(leaf).map(depth)
[2, 2, 4, 4, 4, 6, 5, 5, 5, 5, 5]

class aiatools.attributes.HeightAttribute[source]¶

Bases: aiatools.algebra.Functor

HeightAttribute class is used to memoize the heights of the forest representing an App Inventor project. Use aiatools.attributes.height to benefit from the memoization feature.

Example

Get the heights of the block stacks in the project.

>>> project.blocks(top_level).map(height)
[2, 6]

class aiatools.attributes.NamedAttribute(name)[source]¶

Bases: aiatools.algebra.Functor

The NamedAttribute is a Functor that retrieves the value of a specific field on entities in an App Inventor project.

Example

Retrieve any Form entities in the project:

>>> project.components(NamedAttribute('type') == Form)
[Screen('Screen1')]

Parameters: name (basestring) – The name of the attribute to be retrieved.

class aiatools.attributes.NamedAttributeTuple(names)[source]¶

Bases: aiatools.algebra.Functor

The NamedAttributeTuple is a Functor that retrieves the value of a field on entities in an App Inventor project. Unlike NamedAttribute, it can take more than one name as a tuple. The given field names are searched in order until one is found. This is useful for presenting a single Functor over synonyms, for example, 'name' gives the name of a Component whereas 'component_name' gives the name of a block’s component (if any).

Parameters: names ((str, unicode)) – The name(s) of the attribute(s) to be retrieved. Giving a 1-tuple is less efficient than defining and using the equivalent NamedAttribute instance.

aiatools.attributes.category = NamedAttributeTuple(('category', 'category_string'))¶: Returns the category for the entity.

aiatools.attributes.declaration = NamedAttributeTuple(('type', 'component_type')) == 'component_event' | NamedAttributeTuple(('type', 'component_type')) == 'global_declaration' | NamedAttributeTuple(('type', 'component_type')) == 'procedures_defreturn' | NamedAttributeTuple(('type', 'component_type')) == 'procedures_defnoreturn'¶

aiatools.attributes.depth = <aiatools.attributes.DepthAttribute object>¶

Computes the depth of the entity with its tree. For components, this will be the number of containers from the Screen. For blocks, this will be the number of logical ancestors to the top-most block of the block stack.

>>> project.components(type == Marker).avg(depth)
2.0

aiatools.attributes.disabled = NamedAttribute('disabled')¶: Tests whether the entity is disabled.

aiatools.attributes.enabled = NamedAttribute('Enabled') | ~NamedAttribute('disabled')¶: Tests whether the entity is enabled.

aiatools.attributes.external = NamedAttribute('external')¶: Returns true if the component is an extension.

aiatools.attributes.fields¶

fields is a generator for Functor to retrieve the values of fields in a block. For example:

>>> project.blocks(logic_compare).map(fields.OP)
['EQ']

aiatools.attributes.generic = NamedAttribute('generic')¶: Tests whether the block is a generic component block.

aiatools.attributes.has_ancestor(target=None)[source]¶

Constructs a new ComputedAttribute that accepts an entity if and only if the entity has an ancestor that matches the given target clause.

Example

Count the number of text blocks with an ancestor that is a logic_compare block.

>>> project.blocks((type == text) & has_ancestor(type == logic_compare)).count()
1

Parameters: target (Expression) – An Expression to use for testing ancestors.
Returns: A new ComputedAttribute that will walk the entity graph using the parent field and test whether any parent matches target.
Return type: ComputedAttribute

aiatools.attributes.has_descendant(target=None)[source]¶

Constructs a new ComputedAttribute that accepts an entity if and only if the entity has a descendant that matches the given target clause.

Example

Count the number of top-level blocks that have control_if blocks as descendants.

>>> project.blocks(top_level & has_descendant(type == controls_if)).count()
1

Parameters: target (Expression) – An Expression to use for testing descendants.
Returns: A new ComputedAttribute that will walk the entity graph using the children field and test whether any descendant in the subgraph matches target.
Return type: ComputedAttribute

aiatools.attributes.height = <aiatools.attributes.HeightAttribute object>¶

Computes the height of the tree from the given entity. This will be the longest path from the node to one of its children. For leaf nodes, the height is 0.

>>> project.blocks(top_level).avg(height)
4.0

aiatools.attributes.help_string = NamedAttribute('help_string')¶: Returns the help string for the entity.

aiatools.attributes.icon_name = NamedAttribute('iconName')¶: Returns the icon for the component.

aiatools.attributes.is_called = ComputedAttribute(<function <lambda>>)¶: Returns True if the entity in question is called by some other block in the code.

Todo

Add a mechanism for describing the call graph internal to components so that, for example, project.blocks(mutation.event_name == 'GotText').callers() should be non-empty for any Get method call blocks in the screen for the same instance_name.

aiatools.attributes.is_procedure = NamedAttributeTuple(('type', 'component_type')) == 'procedures_defreturn' | NamedAttributeTuple(('type', 'component_type')) == 'procedures_defnoreturn'¶

Returns True if the type of a block is a procedure definition block, either procedures_defreturn or procedures_defnoreturn

>>> with AIAFile('test_aias/ProcedureTest.aia') as proc_project:
...    proc_project.blocks(is_procedure).count()
7

aiatools.attributes.kind = NamedAttribute('kind')¶: Returns the kind of the entity.

aiatools.attributes.leaf = ComputedAttribute(<function <lambda>>)¶

Returns True if the entity is a leaf in the tree (i.e., it has no children).

>>> project.blocks(leaf).count(group_by=type)
{'text': 3, 'lexical_variable_get': 6, 'color_blue': 2}

aiatools.attributes.logically_disabled = NamedAttribute('logically_disabled')¶: Tests whether the block is logically disabled, either because it is explicitly disabled or is contained within a disabled subtree.

aiatools.attributes.logically_enabled = ~NamedAttribute('logically_disabled')¶: Tests whether the block is logically enabled.

aiatools.attributes.mutation¶

Tests whether a block has a mutation specified. One can also use mutation to obtain accessors for specific mutation fields, for example:

>>> project.blocks(mutation.component_type == Button)
[...]

will retrieve all blocks that have a mutation where the component_type key is the Button type.

aiatools.attributes.name = NamedAttributeTuple(('name', 'instance_name'))¶: Returns the name of the entity.

aiatools.attributes.non_visible = ~NamedAttribute('visible')¶: Returns true if the entity is nonvisible.

aiatools.attributes.parent = NamedAttribute('parent')¶: Gets the parent of the entity.

aiatools.attributes.return_type = NamedAttribute('return_type')¶: Gets the return type of the block.

aiatools.attributes.show_on_palette = NamedAttribute('show_on_palette')¶: Returns true if the entity is shown in the palette.

aiatools.attributes.statement = NamedAttribute('kind') == <BlockKind.STATEMENT: 2>¶

aiatools.attributes.top_level = ComputedAttribute(<function <lambda>>)¶: Tests whether the block is at the top level.

aiatools.attributes.type = NamedAttributeTuple(('type', 'component_type'))¶: Returns the type of the entity.

aiatools.attributes.value = NamedAttribute('kind') == <BlockKind.VALUE: 3>¶

aiatools.attributes.version = NamedAttribute('version')¶: Returns the version number for the entity.

aiatools.attributes.visible = NamedAttribute('visible')¶: Returns true if the entity is visible.

aiatools.block_types module¶

aiatools.block_types.define_block_type(name, category, kind)[source]¶

aiatools.common module¶

The aiatools.common module defines the core data model that is used throughout the aiatools project. In most cases, users will not construct these objects directly but rather through use of the AIAFile class.

class aiatools.common.Block(id, type)[source]¶

Bases: object

children()[source]¶

classmethod from_xml(screen, xml, lang_ver, siblings=None, parent=None, connection_type=None)[source]¶

property generic¶

True if the block is a generic component block (getter, setter, or method call), otherwise False.

Type: bool

property kind¶

property return_type¶

class aiatools.common.BlockCategory(name)[source]¶

Bases: aiatools.algebra.Atom

add_type(block_type)[source]¶

Parameters: block_type (BlockType) –

class aiatools.common.BlockKind[source]¶

Bases: aiatools.algebra.Atom, enum.Enum

An enumeration.

DECLARATION = 1¶

MUTATION = 4¶

STATEMENT = 2¶

VALUE = 3¶

class aiatools.common.BlockType(name, category, kind)[source]¶: Bases: aiatools.algebra.Atom

class aiatools.common.Component(parent, uuid, type, name, version, properties=None)[source]¶

Bases: object

TYPES = {'AccelerometerSensor': aiatools.component_types.AccelerometerSensor, 'ActivityStarter': aiatools.component_types.ActivityStarter, 'Ball': aiatools.component_types.Ball, 'BarcodeScanner': aiatools.component_types.BarcodeScanner, 'Barometer': aiatools.component_types.Barometer, 'BluetoothClient': aiatools.component_types.BluetoothClient, 'BluetoothServer': aiatools.component_types.BluetoothServer, 'Button': aiatools.component_types.Button, 'Camcorder': aiatools.component_types.Camcorder, 'Camera': aiatools.component_types.Camera, 'Canvas': aiatools.component_types.Canvas, 'CheckBox': aiatools.component_types.CheckBox, 'Circle': aiatools.component_types.Circle, 'Clock': aiatools.component_types.Clock, 'CloudDB': aiatools.component_types.CloudDB, 'ContactPicker': aiatools.component_types.ContactPicker, 'DatePicker': aiatools.component_types.DatePicker, 'EmailPicker': aiatools.component_types.EmailPicker, 'Ev3ColorSensor': aiatools.component_types.Ev3ColorSensor, 'Ev3Commands': aiatools.component_types.Ev3Commands, 'Ev3GyroSensor': aiatools.component_types.Ev3GyroSensor, 'Ev3Motors': aiatools.component_types.Ev3Motors, 'Ev3Sound': aiatools.component_types.Ev3Sound, 'Ev3TouchSensor': aiatools.component_types.Ev3TouchSensor, 'Ev3UI': aiatools.component_types.Ev3UI, 'Ev3UltrasonicSensor': aiatools.component_types.Ev3UltrasonicSensor, 'FeatureCollection': aiatools.component_types.FeatureCollection, 'File': aiatools.component_types.File, 'FirebaseDB': aiatools.component_types.FirebaseDB, 'Form': aiatools.component_types.Form, 'FusiontablesControl': aiatools.component_types.FusiontablesControl, 'GameClient': aiatools.component_types.GameClient, 'GyroscopeSensor': aiatools.component_types.GyroscopeSensor, 'HorizontalArrangement': aiatools.component_types.HorizontalArrangement, 'HorizontalScrollArrangement': aiatools.component_types.HorizontalScrollArrangement, 'Hygrometer': aiatools.component_types.Hygrometer, 'Image': aiatools.component_types.Image, 'ImagePicker': aiatools.component_types.ImagePicker, 'ImageSprite': aiatools.component_types.ImageSprite, 'Label': aiatools.component_types.Label, 'LightSensor': aiatools.component_types.LightSensor, 'LineString': aiatools.component_types.LineString, 'ListPicker': aiatools.component_types.ListPicker, 'ListView': aiatools.component_types.ListView, 'LocationSensor': aiatools.component_types.LocationSensor, 'Look': aiatools.component_types.Look, 'Map': aiatools.component_types.Map, 'Marker': aiatools.component_types.Marker, 'MediaStore': aiatools.component_types.MediaStore, 'NearField': aiatools.component_types.NearField, 'Notifier': aiatools.component_types.Notifier, 'NxtColorSensor': aiatools.component_types.NxtColorSensor, 'NxtDirectCommands': aiatools.component_types.NxtDirectCommands, 'NxtDrive': aiatools.component_types.NxtDrive, 'NxtLightSensor': aiatools.component_types.NxtLightSensor, 'NxtSoundSensor': aiatools.component_types.NxtSoundSensor, 'NxtTouchSensor': aiatools.component_types.NxtTouchSensor, 'NxtUltrasonicSensor': aiatools.component_types.NxtUltrasonicSensor, 'OrientationSensor': aiatools.component_types.OrientationSensor, 'PasswordTextBox': aiatools.component_types.PasswordTextBox, 'Pedometer': aiatools.component_types.Pedometer, 'PhoneCall': aiatools.component_types.PhoneCall, 'PhoneNumberPicker': aiatools.component_types.PhoneNumberPicker, 'PhoneStatus': aiatools.component_types.PhoneStatus, 'Player': aiatools.component_types.Player, 'Polygon': aiatools.component_types.Polygon, 'ProximitySensor': aiatools.component_types.ProximitySensor, 'Rectangle': aiatools.component_types.Rectangle, 'Sharing': aiatools.component_types.Sharing, 'Slider': aiatools.component_types.Slider, 'Sound': aiatools.component_types.Sound, 'SoundRecorder': aiatools.component_types.SoundRecorder, 'SpeechRecognizer': aiatools.component_types.SpeechRecognizer, 'Spinner': aiatools.component_types.Spinner, 'Switch': aiatools.component_types.Switch, 'TableArrangement': aiatools.component_types.TableArrangement, 'TextBox': aiatools.component_types.TextBox, 'TextToSpeech': aiatools.component_types.TextToSpeech, 'Texting': aiatools.component_types.Texting, 'Thermometer': aiatools.component_types.Thermometer, 'TimePicker': aiatools.component_types.TimePicker, 'TinyDB': aiatools.component_types.TinyDB, 'TinyWebDB': aiatools.component_types.TinyWebDB, 'Twitter': aiatools.component_types.Twitter, 'VerticalArrangement': aiatools.component_types.VerticalArrangement, 'VerticalScrollArrangement': aiatools.component_types.VerticalScrollArrangement, 'VideoPlayer': aiatools.component_types.VideoPlayer, 'Voting': aiatools.component_types.Voting, 'Web': aiatools.component_types.Web, 'WebViewer': aiatools.component_types.WebViewer, 'YandexTranslate': aiatools.component_types.YandexTranslate}¶

children()[source]¶

classmethod from_json(parent, json_repr)[source]¶

class aiatools.common.ComponentType(name, methods=None, events=None, properties=None)[source]¶: Bases: aiatools.algebra.Atom

class aiatools.common.Event(name, description, deprecated, params)[source]¶: Bases: aiatools.algebra.Atom

class aiatools.common.Extension(*args, **kwargs)[source]¶: Bases: aiatools.common.ComponentType

class aiatools.common.FilterableDict[source]¶

Bases: dict

clear() → None. Remove all items from D.¶

copy() → a shallow copy of D¶

filter(rule)[source]¶

fromkeys()¶: Create a new dictionary with keys from iterable and values set to value.

get()¶: Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items¶

keys() → a set-like object providing a view on D's keys¶

pop(k[, d]) → v, remove specified key and return the corresponding value.¶: If key is not found, d is returned if given, otherwise KeyError is raised

popitem()¶

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault()¶

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from dict/iterable E and F.¶: If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values¶

class aiatools.common.Method(name, description, deprecated, params, returnType=None)[source]¶: Bases: aiatools.algebra.Atom

class aiatools.common.Parameter(name, type)[source]¶: Bases: aiatools.algebra.Atom

class aiatools.common.Property(name, editorType=None, defaultValue=None, description=None, type=None, rw=None, deprecated=False, editorArgs=None, alwaysSend=False)[source]¶: Bases: aiatools.algebra.Atom

class aiatools.common.RecursiveIterator(container, order='breadth', test=None, skip=None)[source]¶: Bases: object

aiatools.component_types module¶

The aiatools.component_types module defines the components for App Inventor. Component types are programmatically constructed during module compilation from the simple_components.json used to populate App Inventor’s online development environment.

class aiatools.component_types.ComponentContainer(parent, uuid, type, name, version, properties=None, components=None)[source]¶

Bases: aiatools.common.Component, aiatools.selectors.Selectors

ComponentContainer models the App Inventor ComponentContainer class.

Parameters

parent (ComponentContainer, optional) – The parent of the container. May be None for Screen.
uuid (basestring) – The UUID for the component container.
type (str) – The type of the component container.
name (basestring) – The name of the component container.
version (str) – The version number of the component container’s type at the time the project was last saved.
properties (dict[basestring, T], optional) – The properties of the component as a dictionary. The values are dependent on the key (property).
components (list[Component], optional) – A list of components contained by the container.

TYPES = {'AccelerometerSensor': aiatools.component_types.AccelerometerSensor, 'ActivityStarter': aiatools.component_types.ActivityStarter, 'Ball': aiatools.component_types.Ball, 'BarcodeScanner': aiatools.component_types.BarcodeScanner, 'Barometer': aiatools.component_types.Barometer, 'BluetoothClient': aiatools.component_types.BluetoothClient, 'BluetoothServer': aiatools.component_types.BluetoothServer, 'Button': aiatools.component_types.Button, 'Camcorder': aiatools.component_types.Camcorder, 'Camera': aiatools.component_types.Camera, 'Canvas': aiatools.component_types.Canvas, 'CheckBox': aiatools.component_types.CheckBox, 'Circle': aiatools.component_types.Circle, 'Clock': aiatools.component_types.Clock, 'CloudDB': aiatools.component_types.CloudDB, 'ContactPicker': aiatools.component_types.ContactPicker, 'DatePicker': aiatools.component_types.DatePicker, 'EmailPicker': aiatools.component_types.EmailPicker, 'Ev3ColorSensor': aiatools.component_types.Ev3ColorSensor, 'Ev3Commands': aiatools.component_types.Ev3Commands, 'Ev3GyroSensor': aiatools.component_types.Ev3GyroSensor, 'Ev3Motors': aiatools.component_types.Ev3Motors, 'Ev3Sound': aiatools.component_types.Ev3Sound, 'Ev3TouchSensor': aiatools.component_types.Ev3TouchSensor, 'Ev3UI': aiatools.component_types.Ev3UI, 'Ev3UltrasonicSensor': aiatools.component_types.Ev3UltrasonicSensor, 'FeatureCollection': aiatools.component_types.FeatureCollection, 'File': aiatools.component_types.File, 'FirebaseDB': aiatools.component_types.FirebaseDB, 'Form': aiatools.component_types.Form, 'FusiontablesControl': aiatools.component_types.FusiontablesControl, 'GameClient': aiatools.component_types.GameClient, 'GyroscopeSensor': aiatools.component_types.GyroscopeSensor, 'HorizontalArrangement': aiatools.component_types.HorizontalArrangement, 'HorizontalScrollArrangement': aiatools.component_types.HorizontalScrollArrangement, 'Hygrometer': aiatools.component_types.Hygrometer, 'Image': aiatools.component_types.Image, 'ImagePicker': aiatools.component_types.ImagePicker, 'ImageSprite': aiatools.component_types.ImageSprite, 'Label': aiatools.component_types.Label, 'LightSensor': aiatools.component_types.LightSensor, 'LineString': aiatools.component_types.LineString, 'ListPicker': aiatools.component_types.ListPicker, 'ListView': aiatools.component_types.ListView, 'LocationSensor': aiatools.component_types.LocationSensor, 'Look': aiatools.component_types.Look, 'Map': aiatools.component_types.Map, 'Marker': aiatools.component_types.Marker, 'MediaStore': aiatools.component_types.MediaStore, 'NearField': aiatools.component_types.NearField, 'Notifier': aiatools.component_types.Notifier, 'NxtColorSensor': aiatools.component_types.NxtColorSensor, 'NxtDirectCommands': aiatools.component_types.NxtDirectCommands, 'NxtDrive': aiatools.component_types.NxtDrive, 'NxtLightSensor': aiatools.component_types.NxtLightSensor, 'NxtSoundSensor': aiatools.component_types.NxtSoundSensor, 'NxtTouchSensor': aiatools.component_types.NxtTouchSensor, 'NxtUltrasonicSensor': aiatools.component_types.NxtUltrasonicSensor, 'OrientationSensor': aiatools.component_types.OrientationSensor, 'PasswordTextBox': aiatools.component_types.PasswordTextBox, 'Pedometer': aiatools.component_types.Pedometer, 'PhoneCall': aiatools.component_types.PhoneCall, 'PhoneNumberPicker': aiatools.component_types.PhoneNumberPicker, 'PhoneStatus': aiatools.component_types.PhoneStatus, 'Player': aiatools.component_types.Player, 'Polygon': aiatools.component_types.Polygon, 'ProximitySensor': aiatools.component_types.ProximitySensor, 'Rectangle': aiatools.component_types.Rectangle, 'Sharing': aiatools.component_types.Sharing, 'Slider': aiatools.component_types.Slider, 'Sound': aiatools.component_types.Sound, 'SoundRecorder': aiatools.component_types.SoundRecorder, 'SpeechRecognizer': aiatools.component_types.SpeechRecognizer, 'Spinner': aiatools.component_types.Spinner, 'Switch': aiatools.component_types.Switch, 'TableArrangement': aiatools.component_types.TableArrangement, 'TextBox': aiatools.component_types.TextBox, 'TextToSpeech': aiatools.component_types.TextToSpeech, 'Texting': aiatools.component_types.Texting, 'Thermometer': aiatools.component_types.Thermometer, 'TimePicker': aiatools.component_types.TimePicker, 'TinyDB': aiatools.component_types.TinyDB, 'TinyWebDB': aiatools.component_types.TinyWebDB, 'Twitter': aiatools.component_types.Twitter, 'VerticalArrangement': aiatools.component_types.VerticalArrangement, 'VerticalScrollArrangement': aiatools.component_types.VerticalScrollArrangement, 'VideoPlayer': aiatools.component_types.VideoPlayer, 'Voting': aiatools.component_types.Voting, 'Web': aiatools.component_types.Web, 'WebViewer': aiatools.component_types.WebViewer, 'YandexTranslate': aiatools.component_types.YandexTranslate}¶

blocks(test=None, *args)¶

Select blocks under the current node. The following filters can be applied:

Returns: A selector for further selection of entities. The selector will only contain Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on blocks.

branch(branch_id)¶

Retrieve

Parameters: branch_id (int) – Retrieve the __branch_id__th branch of any blocks in this collection that have a statement input. This can be used to walk an if-elseif-else block, for example.

Todo

(ewpatton) Implementation

callees(*args, **kwargs)¶

Select procedure definition blocks (if any) that are called by the procedure call blocks in the collection.

Note

Only operates on procedures at this time. See TODO about adding support for components.

Returns: A selector over the callees (if any) of the caller blocks contained in the collection. The selector will only container Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on the blocks
(ewpatton) Add call graph so that component method/event blocks can be included

callers(*args)¶

Select any blocks that result in a call to any callable blocks in the selection.

Note

Only operates on procedures at this time. See TODO about adding support for components.

Returns: A selector over the callers (if any) of the callable blocks contained in the collection. The selector will only contain Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on the blocks
(ewpatton) Add call graph so that component method/event blocks can be included

children()[source]¶

Iterate over the child components in the container

Returns: An iterator over the components in the container.
Return type: collections.Iterable[Component]

New in version 0.1.

property components¶

Returns a Selector over the components in the container.

Type: Selector[Component]

descendants(test=None, order='natural', skip_failures=False)¶

Selects all of the descendants of the entities in the current selection.

Parameters

test (callable) – An optional test used to filter out items from the iteration. Default: None
order (str) – The order of iteration. Options are ‘natural’, ‘breadth’, or ‘depth’. Default: ‘natural’
skip_failures (bool) – If skip_failures is true and test is provided but fails for an element, the subtree starting at the element is pruned.

Returns

The descendants of the entities in the current selection, if any.

Return type

Selector[T]

classmethod from_json(parent, json_repr)[source]¶

Constructs a ComponentContainer

Parameters

parent (ComponentContainer) – The parent container of the new container.
json_repr (dict[str, T]) – The JSON representation of the component from the Screen definition.

Returns

A newly constructed ComponentContainer from the JSON representation.

Return type

ComponentContainer

itervalues()[source]¶

Iterate over the values of this container. For ComponentContainer, the values are the children of the container.

Returns: Iterator over the container’s children.
Return type: collections.Iterable[Component]

map(functor)¶

Applies functor to the entities in the selection.

Parameters: functor (callable) –
Returns: A list in the value space of functor.
Return type: list

screens(test=None, *args)¶

Select the screens containing the elements in the collection.

Returns: A selector over the screens containing the entities in the collection.
Return type: Selector[Screen]

Todo

(ewpatton) Implement subset selection on screens

select(selector)¶

Selects a subset of the entities in the selection for which selector(item) is True.

Parameters: selector (Expression) – The expression to be applied to filter the current selection.
Returns: The subset of the selection. The exact contents of the subset depends on the type of content of the current selection.
Return type: Selector[T]

class aiatools.component_types.Screen(name=None, components=None, form=None, blocks=None)[source]¶

Bases: aiatools.component_types.ComponentContainer

The Screen class provides a Python representation of an App Inventor Screen.

The Screen object encapsulates both its descendant components and the blocks code prescribing the behavior of the Screen’s contents.

Parameters

name (basestring, optional) – The name of the screen.
components (list[Component], optional) – A list of immediate components that are the children of the screen.
form (string | file, optional) – A pathanme, string, or file-like that contains a Screen’s Scheme (.scm) file.
blocks (string | file, optional) – A pathname, string, or file-like that contains a Screen’s Blocks (.bky) file.

TYPES = {'AccelerometerSensor': aiatools.component_types.AccelerometerSensor, 'ActivityStarter': aiatools.component_types.ActivityStarter, 'Ball': aiatools.component_types.Ball, 'BarcodeScanner': aiatools.component_types.BarcodeScanner, 'Barometer': aiatools.component_types.Barometer, 'BluetoothClient': aiatools.component_types.BluetoothClient, 'BluetoothServer': aiatools.component_types.BluetoothServer, 'Button': aiatools.component_types.Button, 'Camcorder': aiatools.component_types.Camcorder, 'Camera': aiatools.component_types.Camera, 'Canvas': aiatools.component_types.Canvas, 'CheckBox': aiatools.component_types.CheckBox, 'Circle': aiatools.component_types.Circle, 'Clock': aiatools.component_types.Clock, 'CloudDB': aiatools.component_types.CloudDB, 'ContactPicker': aiatools.component_types.ContactPicker, 'DatePicker': aiatools.component_types.DatePicker, 'EmailPicker': aiatools.component_types.EmailPicker, 'Ev3ColorSensor': aiatools.component_types.Ev3ColorSensor, 'Ev3Commands': aiatools.component_types.Ev3Commands, 'Ev3GyroSensor': aiatools.component_types.Ev3GyroSensor, 'Ev3Motors': aiatools.component_types.Ev3Motors, 'Ev3Sound': aiatools.component_types.Ev3Sound, 'Ev3TouchSensor': aiatools.component_types.Ev3TouchSensor, 'Ev3UI': aiatools.component_types.Ev3UI, 'Ev3UltrasonicSensor': aiatools.component_types.Ev3UltrasonicSensor, 'FeatureCollection': aiatools.component_types.FeatureCollection, 'File': aiatools.component_types.File, 'FirebaseDB': aiatools.component_types.FirebaseDB, 'Form': aiatools.component_types.Form, 'FusiontablesControl': aiatools.component_types.FusiontablesControl, 'GameClient': aiatools.component_types.GameClient, 'GyroscopeSensor': aiatools.component_types.GyroscopeSensor, 'HorizontalArrangement': aiatools.component_types.HorizontalArrangement, 'HorizontalScrollArrangement': aiatools.component_types.HorizontalScrollArrangement, 'Hygrometer': aiatools.component_types.Hygrometer, 'Image': aiatools.component_types.Image, 'ImagePicker': aiatools.component_types.ImagePicker, 'ImageSprite': aiatools.component_types.ImageSprite, 'Label': aiatools.component_types.Label, 'LightSensor': aiatools.component_types.LightSensor, 'LineString': aiatools.component_types.LineString, 'ListPicker': aiatools.component_types.ListPicker, 'ListView': aiatools.component_types.ListView, 'LocationSensor': aiatools.component_types.LocationSensor, 'Look': aiatools.component_types.Look, 'Map': aiatools.component_types.Map, 'Marker': aiatools.component_types.Marker, 'MediaStore': aiatools.component_types.MediaStore, 'NearField': aiatools.component_types.NearField, 'Notifier': aiatools.component_types.Notifier, 'NxtColorSensor': aiatools.component_types.NxtColorSensor, 'NxtDirectCommands': aiatools.component_types.NxtDirectCommands, 'NxtDrive': aiatools.component_types.NxtDrive, 'NxtLightSensor': aiatools.component_types.NxtLightSensor, 'NxtSoundSensor': aiatools.component_types.NxtSoundSensor, 'NxtTouchSensor': aiatools.component_types.NxtTouchSensor, 'NxtUltrasonicSensor': aiatools.component_types.NxtUltrasonicSensor, 'OrientationSensor': aiatools.component_types.OrientationSensor, 'PasswordTextBox': aiatools.component_types.PasswordTextBox, 'Pedometer': aiatools.component_types.Pedometer, 'PhoneCall': aiatools.component_types.PhoneCall, 'PhoneNumberPicker': aiatools.component_types.PhoneNumberPicker, 'PhoneStatus': aiatools.component_types.PhoneStatus, 'Player': aiatools.component_types.Player, 'Polygon': aiatools.component_types.Polygon, 'ProximitySensor': aiatools.component_types.ProximitySensor, 'Rectangle': aiatools.component_types.Rectangle, 'Sharing': aiatools.component_types.Sharing, 'Slider': aiatools.component_types.Slider, 'Sound': aiatools.component_types.Sound, 'SoundRecorder': aiatools.component_types.SoundRecorder, 'SpeechRecognizer': aiatools.component_types.SpeechRecognizer, 'Spinner': aiatools.component_types.Spinner, 'Switch': aiatools.component_types.Switch, 'TableArrangement': aiatools.component_types.TableArrangement, 'TextBox': aiatools.component_types.TextBox, 'TextToSpeech': aiatools.component_types.TextToSpeech, 'Texting': aiatools.component_types.Texting, 'Thermometer': aiatools.component_types.Thermometer, 'TimePicker': aiatools.component_types.TimePicker, 'TinyDB': aiatools.component_types.TinyDB, 'TinyWebDB': aiatools.component_types.TinyWebDB, 'Twitter': aiatools.component_types.Twitter, 'VerticalArrangement': aiatools.component_types.VerticalArrangement, 'VerticalScrollArrangement': aiatools.component_types.VerticalScrollArrangement, 'VideoPlayer': aiatools.component_types.VideoPlayer, 'Voting': aiatools.component_types.Voting, 'Web': aiatools.component_types.Web, 'WebViewer': aiatools.component_types.WebViewer, 'YandexTranslate': aiatools.component_types.YandexTranslate}¶

blocks(test=None, *args)¶

Select blocks under the current node. The following filters can be applied:

Returns: A selector for further selection of entities. The selector will only contain Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on blocks.

branch(branch_id)¶

Retrieve

Parameters: branch_id (int) – Retrieve the __branch_id__th branch of any blocks in this collection that have a statement input. This can be used to walk an if-elseif-else block, for example.

Todo

(ewpatton) Implementation

callees(*args, **kwargs)¶

Select procedure definition blocks (if any) that are called by the procedure call blocks in the collection.

Note

Only operates on procedures at this time. See TODO about adding support for components.

Returns: A selector over the callees (if any) of the caller blocks contained in the collection. The selector will only container Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on the blocks
(ewpatton) Add call graph so that component method/event blocks can be included

callers(*args)¶

Select any blocks that result in a call to any callable blocks in the selection.

Note

Only operates on procedures at this time. See TODO about adding support for components.

Returns: A selector over the callers (if any) of the callable blocks contained in the collection. The selector will only contain Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on the blocks
(ewpatton) Add call graph so that component method/event blocks can be included

children()¶

Iterate over the child components in the container

Returns: An iterator over the components in the container.
Return type: collections.Iterable[Component]

New in version 0.1.

property components¶

Returns a Selector over the components in the container.

Type: Selector[Component]

descendants(test=None, order='natural', skip_failures=False)¶

Selects all of the descendants of the entities in the current selection.

Parameters

test (callable) – An optional test used to filter out items from the iteration. Default: None
order (str) – The order of iteration. Options are ‘natural’, ‘breadth’, or ‘depth’. Default: ‘natural’
skip_failures (bool) – If skip_failures is true and test is provided but fails for an element, the subtree starting at the element is pruned.

Returns

The descendants of the entities in the current selection, if any.

Return type

Selector[T]

classmethod from_json(parent, json_repr)¶

Constructs a ComponentContainer

Parameters

parent (ComponentContainer) – The parent container of the new container.
json_repr (dict[str, T]) – The JSON representation of the component from the Screen definition.

Returns

A newly constructed ComponentContainer from the JSON representation.

Return type

ComponentContainer

itervalues()¶

Iterate over the values of this container. For ComponentContainer, the values are the children of the container.

Returns: Iterator over the container’s children.
Return type: collections.Iterable[Component]

map(functor)¶

Applies functor to the entities in the selection.

Parameters: functor (callable) –
Returns: A list in the value space of functor.
Return type: list

screens(test=None, *args)¶

Select the screens containing the elements in the collection.

Returns: A selector over the screens containing the entities in the collection.
Return type: Selector[Screen]

Todo

(ewpatton) Implement subset selection on screens

select(selector)¶

Selects a subset of the entities in the selection for which selector(item) is True.

Parameters: selector (Expression) – The expression to be applied to filter the current selection.
Returns: The subset of the selection. The exact contents of the subset depends on the type of content of the current selection.
Return type: Selector[T]

aiatools.component_types.list_to_dict(iterable, key='name')[source]¶

aiatools.selectors module¶

The aiatools.selectors modules provides high level selection and aggregation operations that can be executed over a project.

class aiatools.selectors.AggregateOperations[source]¶

Bases: object

AggregateOptions is a mixin class that provides functionality for aggregation operations on selections.

avg(func, group_by=None)[source]¶

Averages the values of func applied to the collection, optionally grouping by the group_by argument. group_by will be called on each element in the collection.

>>> project.blocks(top_level).avg(height)
4.0
>>> project.blocks().avg(depth)
3.347826086956522

Parameters

func (aiatools.algebra.Functor or callable) – The function to apply to the entities in the collection for which the average will be computed.
group_by (tuple[aiatools.algebra.Functor or callable] or aiatools.algebra.Functor or callable or None) – If given, a :py:class`~aiatools.algebra.Functor` or tuple thereof, the value(s) of which will be used to group the entities in the collection for averaging.

Returns

The average of the values of func applied to the entities of the collection or a dictionary mapping the value(s) of group_by applied to the entities to the average of func applied to the entities in the subset identified by the dictionary key.

Return type

int or dict[(Atom, str) or Atom or str, int]

count(group_by=None)[source]¶

Counts the number of entities in a collection, optionally grouping by the group_by argument. group_by will be called each element in the collection.

>>> project.components().count()
4
>>> project.blocks(top_level).count(group_by=type)
{'component_event': 2}
>>> project.blocks().count(group_by=(type, mutation.component_type))
{('component_event', 'Button'): 1, ('component_method', 'Map'): 2, ('component_event', 'Map'): 1, ('component_set_get', 'Marker'): 4}

Parameters: group_by (tuple[aiatools.algebra.Functor or callable] or aiatools.algebra.Functor or callable or None) – If given, a Functor or tuple thereof, the value(s) of which will be used to group the entities in the collection for counting.
Returns: The count of the number of entities or a dictionary mapping unique group_by values to counts.
Return type: int or dict[(Atom, str) or Atom or str, int]

empty()[source]¶

Tests whether the result of the selector chains up to and including the current selection is empty.

>>> project.components(type == Voting).empty()
True
>>> project.components(type == Button).empty()
False

Returns: True if the selection is empty, otherwise False.
Return type: bool

max(func, group_by=None)[source]¶

Obtains the maximum value of func applied to the collection, optionally grouping by the group_by argument. group_by will be called on each element in the collection.

>>> project.blocks(type == component_event).max(height)
6

Parameters

func (aiatools.algebra.Functor or callable) – The function to apply to the entities in the collection for which the maximum will be computed.
group_by – If given, a Functor or tuple thereof, the value(s) of which will be used to group the entities in the collection for determining the maximum.

Returns

The maximum of the values of func applied to the entities of the collection or a dictionary mapping the value(s) of group_by applied to the entities to the maximum of func applied to the entities in the subset identified by the dictionary key.

Return type

int or dict[(Atom, str) or Atom or str, int]

min(func, group_by=None)[source]¶

Obtains the minimum value of func applied to the collection, optionally grouping by the group_by argument. group_by will be called on each element in the collection.

>>> project.blocks(type == component_event).min(height)
2
>>> project.blocks(category == Components).min(height, group_by=type)
{'component_event': 2, 'component_method': 1, 'component_set_get': 1}
>>> project.blocks().min(height, group_by=(type, mutation.component_type))
{('component_event', 'Button'): 2, ('component_method', 'Map'): 1, ('component_event', 'Map'): 6, ('component_set_get', 'Marker'): 1}

Parameters

func (aiatools.algebra.Functor or callable) – The function to apply to the enetities in the collection for which the minimum will be computed.
group_by (tuple[aiatools.) – If given, a Functor or tuple thereof, the value(s) of which will be used to group the entities in the collection determining the minimum.

Returns

The minimum of the values of func applied to the entities of the collection or a dictionary mapping the value(s) of group_by applied to the entities to the minimum of func applied to the entities in the subset identified by the dictionary key.

Return type

int or dict[(Atom, str) or Atom or str, int]

class aiatools.selectors.NamedCollection[source]¶

Bases: dict, aiatools.selectors.AggregateOperations, aiatools.selectors.Selectors

avg(func, group_by=None)¶

Averages the values of func applied to the collection, optionally grouping by the group_by argument. group_by will be called on each element in the collection.

>>> project.blocks(top_level).avg(height)
4.0
>>> project.blocks().avg(depth)
3.347826086956522

Parameters

func (aiatools.algebra.Functor or callable) – The function to apply to the entities in the collection for which the average will be computed.
group_by (tuple[aiatools.algebra.Functor or callable] or aiatools.algebra.Functor or callable or None) – If given, a :py:class`~aiatools.algebra.Functor` or tuple thereof, the value(s) of which will be used to group the entities in the collection for averaging.

Returns

The average of the values of func applied to the entities of the collection or a dictionary mapping the value(s) of group_by applied to the entities to the average of func applied to the entities in the subset identified by the dictionary key.

Return type

int or dict[(Atom, str) or Atom or str, int]

blocks(test=None, *args)¶

Select blocks under the current node. The following filters can be applied:

Returns: A selector for further selection of entities. The selector will only contain Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on blocks.

branch(branch_id)¶

Retrieve

Parameters: branch_id (int) – Retrieve the __branch_id__th branch of any blocks in this collection that have a statement input. This can be used to walk an if-elseif-else block, for example.

Todo

(ewpatton) Implementation

callees(*args, **kwargs)¶

Select procedure definition blocks (if any) that are called by the procedure call blocks in the collection.

Note

Only operates on procedures at this time. See TODO about adding support for components.

Returns: A selector over the callees (if any) of the caller blocks contained in the collection. The selector will only container Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on the blocks
(ewpatton) Add call graph so that component method/event blocks can be included

callers(*args)¶

Select any blocks that result in a call to any callable blocks in the selection.

Note

Only operates on procedures at this time. See TODO about adding support for components.

Returns: A selector over the callers (if any) of the callable blocks contained in the collection. The selector will only contain Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on the blocks
(ewpatton) Add call graph so that component method/event blocks can be included

clear() → None. Remove all items from D.¶

components(test=None, *args)¶

Select the subset of entities in the current selection that are Component.

Returns: A selector for further selection of entities. The selector will only contain Component.
Return type: Selector[Component]

Todo

(ewpatton) Implement subset selection on components

copy() → a shallow copy of D¶

count(group_by=None)¶

Counts the number of entities in a collection, optionally grouping by the group_by argument. group_by will be called each element in the collection.

>>> project.components().count()
4
>>> project.blocks(top_level).count(group_by=type)
{'component_event': 2}
>>> project.blocks().count(group_by=(type, mutation.component_type))
{('component_event', 'Button'): 1, ('component_method', 'Map'): 2, ('component_event', 'Map'): 1, ('component_set_get', 'Marker'): 4}

Parameters: group_by (tuple[aiatools.algebra.Functor or callable] or aiatools.algebra.Functor or callable or None) – If given, a Functor or tuple thereof, the value(s) of which will be used to group the entities in the collection for counting.
Returns: The count of the number of entities or a dictionary mapping unique group_by values to counts.
Return type: int or dict[(Atom, str) or Atom or str, int]

descendants(test=None, order='natural', skip_failures=False)¶

Selects all of the descendants of the entities in the current selection.

Parameters

test (callable) – An optional test used to filter out items from the iteration. Default: None
order (str) – The order of iteration. Options are ‘natural’, ‘breadth’, or ‘depth’. Default: ‘natural’
skip_failures (bool) – If skip_failures is true and test is provided but fails for an element, the subtree starting at the element is pruned.

Returns

The descendants of the entities in the current selection, if any.

Return type

Selector[T]

empty()¶

Tests whether the result of the selector chains up to and including the current selection is empty.

>>> project.components(type == Voting).empty()
True
>>> project.components(type == Button).empty()
False

Returns: True if the selection is empty, otherwise False.
Return type: bool

fromkeys()¶: Create a new dictionary with keys from iterable and values set to value.

get()¶: Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items¶

keys() → a set-like object providing a view on D's keys¶

map(functor)¶

Applies functor to the entities in the selection.

Parameters: functor (callable) –
Returns: A list in the value space of functor.
Return type: list

max(func, group_by=None)¶

Obtains the maximum value of func applied to the collection, optionally grouping by the group_by argument. group_by will be called on each element in the collection.

>>> project.blocks(type == component_event).max(height)
6

Parameters

func (aiatools.algebra.Functor or callable) – The function to apply to the entities in the collection for which the maximum will be computed.
group_by – If given, a Functor or tuple thereof, the value(s) of which will be used to group the entities in the collection for determining the maximum.

Returns

The maximum of the values of func applied to the entities of the collection or a dictionary mapping the value(s) of group_by applied to the entities to the maximum of func applied to the entities in the subset identified by the dictionary key.

Return type

int or dict[(Atom, str) or Atom or str, int]

min(func, group_by=None)¶

Obtains the minimum value of func applied to the collection, optionally grouping by the group_by argument. group_by will be called on each element in the collection.

>>> project.blocks(type == component_event).min(height)
2
>>> project.blocks(category == Components).min(height, group_by=type)
{'component_event': 2, 'component_method': 1, 'component_set_get': 1}
>>> project.blocks().min(height, group_by=(type, mutation.component_type))
{('component_event', 'Button'): 2, ('component_method', 'Map'): 1, ('component_event', 'Map'): 6, ('component_set_get', 'Marker'): 1}

Parameters

func (aiatools.algebra.Functor or callable) – The function to apply to the enetities in the collection for which the minimum will be computed.
group_by (tuple[aiatools.) – If given, a Functor or tuple thereof, the value(s) of which will be used to group the entities in the collection determining the minimum.

Returns

The minimum of the values of func applied to the entities of the collection or a dictionary mapping the value(s) of group_by applied to the entities to the minimum of func applied to the entities in the subset identified by the dictionary key.

Return type

int or dict[(Atom, str) or Atom or str, int]

pop(k[, d]) → v, remove specified key and return the corresponding value.¶: If key is not found, d is returned if given, otherwise KeyError is raised

popitem()¶

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

screens(test=None, *args)¶

Select the screens containing the elements in the collection.

Returns: A selector over the screens containing the entities in the collection.
Return type: Selector[Screen]

Todo

(ewpatton) Implement subset selection on screens

select(selector)¶

Selects a subset of the entities in the selection for which selector(item) is True.

Parameters: selector (Expression) – The expression to be applied to filter the current selection.
Returns: The subset of the selection. The exact contents of the subset depends on the type of content of the current selection.
Return type: Selector[T]

setdefault()¶

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from dict/iterable E and F.¶: If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values¶

class aiatools.selectors.NamedCollectionView(parent, functor)[source]¶

Bases: aiatools.selectors.AggregateOperations, aiatools.selectors.Selectors

avg(func, group_by=None)¶

Averages the values of func applied to the collection, optionally grouping by the group_by argument. group_by will be called on each element in the collection.

>>> project.blocks(top_level).avg(height)
4.0
>>> project.blocks().avg(depth)
3.347826086956522

Parameters

func (aiatools.algebra.Functor or callable) – The function to apply to the entities in the collection for which the average will be computed.
group_by (tuple[aiatools.algebra.Functor or callable] or aiatools.algebra.Functor or callable or None) – If given, a :py:class`~aiatools.algebra.Functor` or tuple thereof, the value(s) of which will be used to group the entities in the collection for averaging.

Returns

The average of the values of func applied to the entities of the collection or a dictionary mapping the value(s) of group_by applied to the entities to the average of func applied to the entities in the subset identified by the dictionary key.

Return type

int or dict[(Atom, str) or Atom or str, int]

blocks(test=None, *args)¶

Select blocks under the current node. The following filters can be applied:

Returns: A selector for further selection of entities. The selector will only contain Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on blocks.

branch(branch_id)¶

Retrieve

Parameters: branch_id (int) – Retrieve the __branch_id__th branch of any blocks in this collection that have a statement input. This can be used to walk an if-elseif-else block, for example.

Todo

(ewpatton) Implementation

callees(*args, **kwargs)¶

Select procedure definition blocks (if any) that are called by the procedure call blocks in the collection.

Note

Only operates on procedures at this time. See TODO about adding support for components.

Returns: A selector over the callees (if any) of the caller blocks contained in the collection. The selector will only container Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on the blocks
(ewpatton) Add call graph so that component method/event blocks can be included

callers(*args)¶

Select any blocks that result in a call to any callable blocks in the selection.

Note

Only operates on procedures at this time. See TODO about adding support for components.

Returns: A selector over the callers (if any) of the callable blocks contained in the collection. The selector will only contain Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on the blocks
(ewpatton) Add call graph so that component method/event blocks can be included

components(test=None, *args)¶

Select the subset of entities in the current selection that are Component.

Returns: A selector for further selection of entities. The selector will only contain Component.
Return type: Selector[Component]

Todo

(ewpatton) Implement subset selection on components

count(group_by=None)¶

Counts the number of entities in a collection, optionally grouping by the group_by argument. group_by will be called each element in the collection.

>>> project.components().count()
4
>>> project.blocks(top_level).count(group_by=type)
{'component_event': 2}
>>> project.blocks().count(group_by=(type, mutation.component_type))
{('component_event', 'Button'): 1, ('component_method', 'Map'): 2, ('component_event', 'Map'): 1, ('component_set_get', 'Marker'): 4}

Parameters: group_by (tuple[aiatools.algebra.Functor or callable] or aiatools.algebra.Functor or callable or None) – If given, a Functor or tuple thereof, the value(s) of which will be used to group the entities in the collection for counting.
Returns: The count of the number of entities or a dictionary mapping unique group_by values to counts.
Return type: int or dict[(Atom, str) or Atom or str, int]

descendants(test=None, order='natural', skip_failures=False)¶

Selects all of the descendants of the entities in the current selection.

Parameters

test (callable) – An optional test used to filter out items from the iteration. Default: None
order (str) – The order of iteration. Options are ‘natural’, ‘breadth’, or ‘depth’. Default: ‘natural’
skip_failures (bool) – If skip_failures is true and test is provided but fails for an element, the subtree starting at the element is pruned.

Returns

The descendants of the entities in the current selection, if any.

Return type

Selector[T]

empty()¶

Tests whether the result of the selector chains up to and including the current selection is empty.

>>> project.components(type == Voting).empty()
True
>>> project.components(type == Button).empty()
False

Returns: True if the selection is empty, otherwise False.
Return type: bool

filter(rule)[source]¶

iteritems()[source]¶

map(functor)¶

Applies functor to the entities in the selection.

Parameters: functor (callable) –
Returns: A list in the value space of functor.
Return type: list

max(func, group_by=None)¶

Obtains the maximum value of func applied to the collection, optionally grouping by the group_by argument. group_by will be called on each element in the collection.

>>> project.blocks(type == component_event).max(height)
6

Parameters

func (aiatools.algebra.Functor or callable) – The function to apply to the entities in the collection for which the maximum will be computed.
group_by – If given, a Functor or tuple thereof, the value(s) of which will be used to group the entities in the collection for determining the maximum.

Returns

The maximum of the values of func applied to the entities of the collection or a dictionary mapping the value(s) of group_by applied to the entities to the maximum of func applied to the entities in the subset identified by the dictionary key.

Return type

int or dict[(Atom, str) or Atom or str, int]

min(func, group_by=None)¶

Obtains the minimum value of func applied to the collection, optionally grouping by the group_by argument. group_by will be called on each element in the collection.

>>> project.blocks(type == component_event).min(height)
2
>>> project.blocks(category == Components).min(height, group_by=type)
{'component_event': 2, 'component_method': 1, 'component_set_get': 1}
>>> project.blocks().min(height, group_by=(type, mutation.component_type))
{('component_event', 'Button'): 2, ('component_method', 'Map'): 1, ('component_event', 'Map'): 6, ('component_set_get', 'Marker'): 1}

Parameters

func (aiatools.algebra.Functor or callable) – The function to apply to the enetities in the collection for which the minimum will be computed.
group_by (tuple[aiatools.) – If given, a Functor or tuple thereof, the value(s) of which will be used to group the entities in the collection determining the minimum.

Returns

The minimum of the values of func applied to the entities of the collection or a dictionary mapping the value(s) of group_by applied to the entities to the minimum of func applied to the entities in the subset identified by the dictionary key.

Return type

int or dict[(Atom, str) or Atom or str, int]

screens(test=None, *args)¶

Select the screens containing the elements in the collection.

Returns: A selector over the screens containing the entities in the collection.
Return type: Selector[Screen]

Todo

(ewpatton) Implement subset selection on screens

select(selector)¶

Selects a subset of the entities in the selection for which selector(item) is True.

Parameters: selector (Expression) – The expression to be applied to filter the current selection.
Returns: The subset of the selection. The exact contents of the subset depends on the type of content of the current selection.
Return type: Selector[T]

class aiatools.selectors.PrefixedSelector(prefix, collection)[source]¶

Bases: aiatools.selectors.Selector

avg(func, group_by=None)¶

Averages the values of func applied to the collection, optionally grouping by the group_by argument. group_by will be called on each element in the collection.

>>> project.blocks(top_level).avg(height)
4.0
>>> project.blocks().avg(depth)
3.347826086956522

Parameters

func (aiatools.algebra.Functor or callable) – The function to apply to the entities in the collection for which the average will be computed.
group_by (tuple[aiatools.algebra.Functor or callable] or aiatools.algebra.Functor or callable or None) – If given, a :py:class`~aiatools.algebra.Functor` or tuple thereof, the value(s) of which will be used to group the entities in the collection for averaging.

Returns

The average of the values of func applied to the entities of the collection or a dictionary mapping the value(s) of group_by applied to the entities to the average of func applied to the entities in the subset identified by the dictionary key.

Return type

int or dict[(Atom, str) or Atom or str, int]

blocks(test=None, *args)¶

Select blocks under the current node. The following filters can be applied:

Returns: A selector for further selection of entities. The selector will only contain Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on blocks.

branch(branch_id)¶

Retrieve

Parameters: branch_id (int) – Retrieve the __branch_id__th branch of any blocks in this collection that have a statement input. This can be used to walk an if-elseif-else block, for example.

Todo

(ewpatton) Implementation

callees(*args, **kwargs)¶

Select procedure definition blocks (if any) that are called by the procedure call blocks in the collection.

Note

Only operates on procedures at this time. See TODO about adding support for components.

Returns: A selector over the callees (if any) of the caller blocks contained in the collection. The selector will only container Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on the blocks
(ewpatton) Add call graph so that component method/event blocks can be included

callers(*args)¶

Select any blocks that result in a call to any callable blocks in the selection.

Note

Only operates on procedures at this time. See TODO about adding support for components.

Returns: A selector over the callers (if any) of the callable blocks contained in the collection. The selector will only contain Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on the blocks
(ewpatton) Add call graph so that component method/event blocks can be included

components(test=None, *args)¶

Select the subset of entities in the current selection that are Component.

Returns: A selector for further selection of entities. The selector will only contain Component.
Return type: Selector[Component]

Todo

(ewpatton) Implement subset selection on components

count(group_by=None)¶

Counts the number of entities in a collection, optionally grouping by the group_by argument. group_by will be called each element in the collection.

>>> project.components().count()
4
>>> project.blocks(top_level).count(group_by=type)
{'component_event': 2}
>>> project.blocks().count(group_by=(type, mutation.component_type))
{('component_event', 'Button'): 1, ('component_method', 'Map'): 2, ('component_event', 'Map'): 1, ('component_set_get', 'Marker'): 4}

Parameters: group_by (tuple[aiatools.algebra.Functor or callable] or aiatools.algebra.Functor or callable or None) – If given, a Functor or tuple thereof, the value(s) of which will be used to group the entities in the collection for counting.
Returns: The count of the number of entities or a dictionary mapping unique group_by values to counts.
Return type: int or dict[(Atom, str) or Atom or str, int]

descendants(test=None, order='natural', skip_failures=False)¶

Selects all of the descendants of the entities in the current selection.

Parameters

test (callable) – An optional test used to filter out items from the iteration. Default: None
order (str) – The order of iteration. Options are ‘natural’, ‘breadth’, or ‘depth’. Default: ‘natural’
skip_failures (bool) – If skip_failures is true and test is provided but fails for an element, the subtree starting at the element is pruned.

Returns

The descendants of the entities in the current selection, if any.

Return type

Selector[T]

empty()¶

Tests whether the result of the selector chains up to and including the current selection is empty.

>>> project.components(type == Voting).empty()
True
>>> project.components(type == Button).empty()
False

Returns: True if the selection is empty, otherwise False.
Return type: bool

items()¶

iteritems()[source]¶

itervalues()[source]¶

map(functor)¶

Applies functor to the entities in the selection.

Parameters: functor (callable) –
Returns: A list in the value space of functor.
Return type: list

max(func, group_by=None)¶

Obtains the maximum value of func applied to the collection, optionally grouping by the group_by argument. group_by will be called on each element in the collection.

>>> project.blocks(type == component_event).max(height)
6

Parameters

func (aiatools.algebra.Functor or callable) – The function to apply to the entities in the collection for which the maximum will be computed.
group_by – If given, a Functor or tuple thereof, the value(s) of which will be used to group the entities in the collection for determining the maximum.

Returns

The maximum of the values of func applied to the entities of the collection or a dictionary mapping the value(s) of group_by applied to the entities to the maximum of func applied to the entities in the subset identified by the dictionary key.

Return type

int or dict[(Atom, str) or Atom or str, int]

min(func, group_by=None)¶

Obtains the minimum value of func applied to the collection, optionally grouping by the group_by argument. group_by will be called on each element in the collection.

>>> project.blocks(type == component_event).min(height)
2
>>> project.blocks(category == Components).min(height, group_by=type)
{'component_event': 2, 'component_method': 1, 'component_set_get': 1}
>>> project.blocks().min(height, group_by=(type, mutation.component_type))
{('component_event', 'Button'): 2, ('component_method', 'Map'): 1, ('component_event', 'Map'): 6, ('component_set_get', 'Marker'): 1}

Parameters

func (aiatools.algebra.Functor or callable) – The function to apply to the enetities in the collection for which the minimum will be computed.
group_by (tuple[aiatools.) – If given, a Functor or tuple thereof, the value(s) of which will be used to group the entities in the collection determining the minimum.

Returns

The minimum of the values of func applied to the entities of the collection or a dictionary mapping the value(s) of group_by applied to the entities to the minimum of func applied to the entities in the subset identified by the dictionary key.

Return type

int or dict[(Atom, str) or Atom or str, int]

screens(test=None, *args)¶

Select the screens containing the elements in the collection.

Returns: A selector over the screens containing the entities in the collection.
Return type: Selector[Screen]

Todo

(ewpatton) Implement subset selection on screens

select(selector)¶

Selects a subset of the entities in the selection for which selector(item) is True.

Parameters: selector (Expression) – The expression to be applied to filter the current selection.
Returns: The subset of the selection. The exact contents of the subset depends on the type of content of the current selection.
Return type: Selector[T]

values()¶

class aiatools.selectors.Selector(collection)[source]¶

Bases: aiatools.selectors.AggregateOperations, aiatools.selectors.Selectors

Selector provides a lazily computed application of an expression over a collection. Items in the underlying collection can be accessed in three ways:

Through use of an iterable. Selector is an iterable, and iterating over it yields its values. There is also iteritems(), which iterates over key, value pairs in the collection similar to how the iteritems method in dict works.
Through an identifier/key. For example, accessing the Component called Button1 can be done with selection['Button1'].
Through an index. For example, if children is a Selector, ``children[5]` will give the 6th element in the selection. This is not random access, but linear in n, so if accessing elements in sequence is required using the iteration method is recommended.

Selectors can also be called, in which case they will return a new Selector whose elements are given by applying the first argument of the function call to each element in the underlying collection.

Parameters: collection (collections.Iterable[{id}] or dict[{id}]) – A collection of objects

avg(func, group_by=None)¶

Averages the values of func applied to the collection, optionally grouping by the group_by argument. group_by will be called on each element in the collection.

>>> project.blocks(top_level).avg(height)
4.0
>>> project.blocks().avg(depth)
3.347826086956522

Parameters

func (aiatools.algebra.Functor or callable) – The function to apply to the entities in the collection for which the average will be computed.
group_by (tuple[aiatools.algebra.Functor or callable] or aiatools.algebra.Functor or callable or None) – If given, a :py:class`~aiatools.algebra.Functor` or tuple thereof, the value(s) of which will be used to group the entities in the collection for averaging.

Returns

The average of the values of func applied to the entities of the collection or a dictionary mapping the value(s) of group_by applied to the entities to the average of func applied to the entities in the subset identified by the dictionary key.

Return type

int or dict[(Atom, str) or Atom or str, int]

blocks(test=None, *args)¶

Select blocks under the current node. The following filters can be applied:

Returns: A selector for further selection of entities. The selector will only contain Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on blocks.

branch(branch_id)¶

Retrieve

Parameters: branch_id (int) – Retrieve the __branch_id__th branch of any blocks in this collection that have a statement input. This can be used to walk an if-elseif-else block, for example.

Todo

(ewpatton) Implementation

callees(*args, **kwargs)¶

Select procedure definition blocks (if any) that are called by the procedure call blocks in the collection.

Note

Only operates on procedures at this time. See TODO about adding support for components.

Returns: A selector over the callees (if any) of the caller blocks contained in the collection. The selector will only container Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on the blocks
(ewpatton) Add call graph so that component method/event blocks can be included

callers(*args)¶

Select any blocks that result in a call to any callable blocks in the selection.

Note

Only operates on procedures at this time. See TODO about adding support for components.

Returns: A selector over the callers (if any) of the callable blocks contained in the collection. The selector will only contain Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on the blocks
(ewpatton) Add call graph so that component method/event blocks can be included

components(test=None, *args)¶

Select the subset of entities in the current selection that are Component.

Returns: A selector for further selection of entities. The selector will only contain Component.
Return type: Selector[Component]

Todo

(ewpatton) Implement subset selection on components

count(group_by=None)¶

Counts the number of entities in a collection, optionally grouping by the group_by argument. group_by will be called each element in the collection.

>>> project.components().count()
4
>>> project.blocks(top_level).count(group_by=type)
{'component_event': 2}
>>> project.blocks().count(group_by=(type, mutation.component_type))
{('component_event', 'Button'): 1, ('component_method', 'Map'): 2, ('component_event', 'Map'): 1, ('component_set_get', 'Marker'): 4}

Parameters: group_by (tuple[aiatools.algebra.Functor or callable] or aiatools.algebra.Functor or callable or None) – If given, a Functor or tuple thereof, the value(s) of which will be used to group the entities in the collection for counting.
Returns: The count of the number of entities or a dictionary mapping unique group_by values to counts.
Return type: int or dict[(Atom, str) or Atom or str, int]

descendants(test=None, order='natural', skip_failures=False)¶

Selects all of the descendants of the entities in the current selection.

Parameters

test (callable) – An optional test used to filter out items from the iteration. Default: None
order (str) – The order of iteration. Options are ‘natural’, ‘breadth’, or ‘depth’. Default: ‘natural’
skip_failures (bool) – If skip_failures is true and test is provided but fails for an element, the subtree starting at the element is pruned.

Returns

The descendants of the entities in the current selection, if any.

Return type

Selector[T]

empty()¶

Tests whether the result of the selector chains up to and including the current selection is empty.

>>> project.components(type == Voting).empty()
True
>>> project.components(type == Button).empty()
False

Returns: True if the selection is empty, otherwise False.
Return type: bool

items()[source]¶

map(functor)¶

Applies functor to the entities in the selection.

Parameters: functor (callable) –
Returns: A list in the value space of functor.
Return type: list

max(func, group_by=None)¶

Obtains the maximum value of func applied to the collection, optionally grouping by the group_by argument. group_by will be called on each element in the collection.

>>> project.blocks(type == component_event).max(height)
6

Parameters

func (aiatools.algebra.Functor or callable) – The function to apply to the entities in the collection for which the maximum will be computed.
group_by – If given, a Functor or tuple thereof, the value(s) of which will be used to group the entities in the collection for determining the maximum.

Returns

The maximum of the values of func applied to the entities of the collection or a dictionary mapping the value(s) of group_by applied to the entities to the maximum of func applied to the entities in the subset identified by the dictionary key.

Return type

int or dict[(Atom, str) or Atom or str, int]

min(func, group_by=None)¶

Obtains the minimum value of func applied to the collection, optionally grouping by the group_by argument. group_by will be called on each element in the collection.

>>> project.blocks(type == component_event).min(height)
2
>>> project.blocks(category == Components).min(height, group_by=type)
{'component_event': 2, 'component_method': 1, 'component_set_get': 1}
>>> project.blocks().min(height, group_by=(type, mutation.component_type))
{('component_event', 'Button'): 2, ('component_method', 'Map'): 1, ('component_event', 'Map'): 6, ('component_set_get', 'Marker'): 1}

Parameters

func (aiatools.algebra.Functor or callable) – The function to apply to the enetities in the collection for which the minimum will be computed.
group_by (tuple[aiatools.) – If given, a Functor or tuple thereof, the value(s) of which will be used to group the entities in the collection determining the minimum.

Returns

The minimum of the values of func applied to the entities of the collection or a dictionary mapping the value(s) of group_by applied to the entities to the minimum of func applied to the entities in the subset identified by the dictionary key.

Return type

int or dict[(Atom, str) or Atom or str, int]

screens(test=None, *args)¶

Select the screens containing the elements in the collection.

Returns: A selector over the screens containing the entities in the collection.
Return type: Selector[Screen]

Todo

(ewpatton) Implement subset selection on screens

select(selector)¶

Selects a subset of the entities in the selection for which selector(item) is True.

Parameters: selector (Expression) – The expression to be applied to filter the current selection.
Returns: The subset of the selection. The exact contents of the subset depends on the type of content of the current selection.
Return type: Selector[T]

values()[source]¶

class aiatools.selectors.Selectors(*args)[source]¶

Bases: object

Selectors is a mixin class for collections that enables selecting entities related to entities in the collection.

blocks(test=None, *args)[source]¶

Select blocks under the current node. The following filters can be applied:

Returns: A selector for further selection of entities. The selector will only contain Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on blocks.

branch(branch_id)[source]¶

Retrieve

Parameters: branch_id (int) – Retrieve the __branch_id__th branch of any blocks in this collection that have a statement input. This can be used to walk an if-elseif-else block, for example.

Todo

(ewpatton) Implementation

callees(*args, **kwargs)[source]¶

Select procedure definition blocks (if any) that are called by the procedure call blocks in the collection.

Note

Only operates on procedures at this time. See TODO about adding support for components.

Returns: A selector over the callees (if any) of the caller blocks contained in the collection. The selector will only container Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on the blocks
(ewpatton) Add call graph so that component method/event blocks can be included

callers(*args)[source]¶

Select any blocks that result in a call to any callable blocks in the selection.

Note

Only operates on procedures at this time. See TODO about adding support for components.

Returns: A selector over the callers (if any) of the callable blocks contained in the collection. The selector will only contain Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on the blocks
(ewpatton) Add call graph so that component method/event blocks can be included

components(test=None, *args)[source]¶

Select the subset of entities in the current selection that are Component.

Returns: A selector for further selection of entities. The selector will only contain Component.
Return type: Selector[Component]

Todo

(ewpatton) Implement subset selection on components

descendants(test=None, order='natural', skip_failures=False)[source]¶

Selects all of the descendants of the entities in the current selection.

Parameters

test (callable) – An optional test used to filter out items from the iteration. Default: None
order (str) – The order of iteration. Options are ‘natural’, ‘breadth’, or ‘depth’. Default: ‘natural’
skip_failures (bool) – If skip_failures is true and test is provided but fails for an element, the subtree starting at the element is pruned.

Returns

The descendants of the entities in the current selection, if any.

Return type

Selector[T]

map(functor)[source]¶

Applies functor to the entities in the selection.

Parameters: functor (callable) –
Returns: A list in the value space of functor.
Return type: list

screens(test=None, *args)[source]¶

Select the screens containing the elements in the collection.

Returns: A selector over the screens containing the entities in the collection.
Return type: Selector[Screen]

Todo

(ewpatton) Implement subset selection on screens

select(selector)[source]¶

Selects a subset of the entities in the selection for which selector(item) is True.

Parameters: selector (Expression) – The expression to be applied to filter the current selection.
Returns: The subset of the selection. The exact contents of the subset depends on the type of content of the current selection.
Return type: Selector[T]

class aiatools.selectors.UnionSelector(collection, field)[source]¶

Bases: aiatools.selectors.AggregateOperations, aiatools.selectors.Selectors

avg(func, group_by=None)¶

Averages the values of func applied to the collection, optionally grouping by the group_by argument. group_by will be called on each element in the collection.

>>> project.blocks(top_level).avg(height)
4.0
>>> project.blocks().avg(depth)
3.347826086956522

Parameters

func (aiatools.algebra.Functor or callable) – The function to apply to the entities in the collection for which the average will be computed.
group_by (tuple[aiatools.algebra.Functor or callable] or aiatools.algebra.Functor or callable or None) – If given, a :py:class`~aiatools.algebra.Functor` or tuple thereof, the value(s) of which will be used to group the entities in the collection for averaging.

Returns

The average of the values of func applied to the entities of the collection or a dictionary mapping the value(s) of group_by applied to the entities to the average of func applied to the entities in the subset identified by the dictionary key.

Return type

int or dict[(Atom, str) or Atom or str, int]

blocks(test=None, *args)¶

Select blocks under the current node. The following filters can be applied:

Returns: A selector for further selection of entities. The selector will only contain Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on blocks.

branch(branch_id)¶

Retrieve

Parameters: branch_id (int) – Retrieve the __branch_id__th branch of any blocks in this collection that have a statement input. This can be used to walk an if-elseif-else block, for example.

Todo

(ewpatton) Implementation

callees(*args, **kwargs)¶

Select procedure definition blocks (if any) that are called by the procedure call blocks in the collection.

Note

Only operates on procedures at this time. See TODO about adding support for components.

Returns: A selector over the callees (if any) of the caller blocks contained in the collection. The selector will only container Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on the blocks
(ewpatton) Add call graph so that component method/event blocks can be included

callers(*args)¶

Select any blocks that result in a call to any callable blocks in the selection.

Note

Only operates on procedures at this time. See TODO about adding support for components.

Returns: A selector over the callers (if any) of the callable blocks contained in the collection. The selector will only contain Block.
Return type: Selector[Block]

Todo

(ewpatton) Implement subset selection on the blocks
(ewpatton) Add call graph so that component method/event blocks can be included

components(test=None, *args)¶

Select the subset of entities in the current selection that are Component.

Returns: A selector for further selection of entities. The selector will only contain Component.
Return type: Selector[Component]

Todo

(ewpatton) Implement subset selection on components

count(group_by=None)¶

Counts the number of entities in a collection, optionally grouping by the group_by argument. group_by will be called each element in the collection.

>>> project.components().count()
4
>>> project.blocks(top_level).count(group_by=type)
{'component_event': 2}
>>> project.blocks().count(group_by=(type, mutation.component_type))
{('component_event', 'Button'): 1, ('component_method', 'Map'): 2, ('component_event', 'Map'): 1, ('component_set_get', 'Marker'): 4}

Parameters: group_by (tuple[aiatools.algebra.Functor or callable] or aiatools.algebra.Functor or callable or None) – If given, a Functor or tuple thereof, the value(s) of which will be used to group the entities in the collection for counting.
Returns: The count of the number of entities or a dictionary mapping unique group_by values to counts.
Return type: int or dict[(Atom, str) or Atom or str, int]

descendants(test=None, order='natural', skip_failures=False)¶

Selects all of the descendants of the entities in the current selection.

Parameters

test (callable) – An optional test used to filter out items from the iteration. Default: None
order (str) – The order of iteration. Options are ‘natural’, ‘breadth’, or ‘depth’. Default: ‘natural’
skip_failures (bool) – If skip_failures is true and test is provided but fails for an element, the subtree starting at the element is pruned.

Returns

The descendants of the entities in the current selection, if any.

Return type

Selector[T]

empty()¶

Tests whether the result of the selector chains up to and including the current selection is empty.

>>> project.components(type == Voting).empty()
True
>>> project.components(type == Button).empty()
False

Returns: True if the selection is empty, otherwise False.
Return type: bool

iteritems()[source]¶

itervalues()[source]¶

map(functor)¶

Applies functor to the entities in the selection.

Parameters: functor (callable) –
Returns: A list in the value space of functor.
Return type: list

max(func, group_by=None)¶

Obtains the maximum value of func applied to the collection, optionally grouping by the group_by argument. group_by will be called on each element in the collection.

>>> project.blocks(type == component_event).max(height)
6

Parameters

func (aiatools.algebra.Functor or callable) – The function to apply to the entities in the collection for which the maximum will be computed.
group_by – If given, a Functor or tuple thereof, the value(s) of which will be used to group the entities in the collection for determining the maximum.

Returns

The maximum of the values of func applied to the entities of the collection or a dictionary mapping the value(s) of group_by applied to the entities to the maximum of func applied to the entities in the subset identified by the dictionary key.

Return type

int or dict[(Atom, str) or Atom or str, int]

min(func, group_by=None)¶

Obtains the minimum value of func applied to the collection, optionally grouping by the group_by argument. group_by will be called on each element in the collection.

>>> project.blocks(type == component_event).min(height)
2
>>> project.blocks(category == Components).min(height, group_by=type)
{'component_event': 2, 'component_method': 1, 'component_set_get': 1}
>>> project.blocks().min(height, group_by=(type, mutation.component_type))
{('component_event', 'Button'): 2, ('component_method', 'Map'): 1, ('component_event', 'Map'): 6, ('component_set_get', 'Marker'): 1}

Parameters

func (aiatools.algebra.Functor or callable) – The function to apply to the enetities in the collection for which the minimum will be computed.
group_by (tuple[aiatools.) – If given, a Functor or tuple thereof, the value(s) of which will be used to group the entities in the collection determining the minimum.

Returns

The minimum of the values of func applied to the entities of the collection or a dictionary mapping the value(s) of group_by applied to the entities to the minimum of func applied to the entities in the subset identified by the dictionary key.

Return type

int or dict[(Atom, str) or Atom or str, int]

screens(test=None, *args)¶

Select the screens containing the elements in the collection.

Returns: A selector over the screens containing the entities in the collection.
Return type: Selector[Screen]

Todo

(ewpatton) Implement subset selection on screens

select(selector)¶

Selects a subset of the entities in the selection for which selector(item) is True.

Parameters: selector (Expression) – The expression to be applied to filter the current selection.
Returns: The subset of the selection. The exact contents of the subset depends on the type of content of the current selection.
Return type: Selector[T]

aiatools.selectors.select(item)[source]¶: select() is a convenience method for creating a selection out of a single item. This allows one to select a specific component for further exploration :param item: :return: