parcon.static
index
/home/jcp/github/parcon/parcon/static.py

A static typing library for Python. That may sound at first as if this module
was designed to simply decorate methods specifying the type of objects that
must be passed to them, and it can definitely do that. However, it's quite a
bit more powerful than that. It has a collection of constructs that allow
constructing type patterns, objects that allow a form of pattern matching
against Python objects. For example, And(Type(list), All(Type(int))) is a type
pattern that matches all objects that are instances of list and whose values
are all ints. All(Type(int)) would match any iterable object, not just a list,
whose values are ints, while Or(Not(Iterable()), All(Type(int))) would
additionally match objects that are not iterable, and Type(int) would simply
match objects of type int.
 
A short notation can be used to represent some of the type constructs. These
must be passed to the compile function to convert them to type patterns for
actual use. Any Python type is a type pattern matching objects of that type.
A list containing one item, a type pattern (short or otherwise), is a type
pattern matching objects that are iterable and whose values are all of that
type and a tuple containing one or more items is a type pattern that matches
any object that matches at least one of its contained types. In that way,
Python types are converted to instances of Type, lists are converted to
instances of All, and tuples are converted to instances of Or.
 
Type patterns have two methods, matches and check_matches. Both take a single
argument, the value to match against. matches returns true if the specified
value matches the type pattern on which the matches function was called.
check_matches calls matches and throws a StaticTypeError if it returned false.
 
Each of the type pattern constructs clearly defines what fields it creates,
which allows for metatyping: creating type patterns that match type patterns
themselves. Such a thing is used in JPath's query optimizer, where the
optimizer uses metatyping to determine if the type pattern that an optimizer
will be called for makes any definitive assertions as to what type of compiler
production it operates on, which allows the compiler to significantly decrease
the time it takes to look up the set of optimizations to be applied to a
particular compiler production.

 
Classes
       
__builtin__.object
StaticType
All
And
Any
Everything
Field
Is
Iterable
Not
Or
Positional
Sequence
Type
exceptions.Exception(exceptions.BaseException)
InternalError
StaticTypeError
TypeFormatError

 
class All(StaticType)
    A static type that matches a value if that particular value is iterable
and all of its values match the component type with which this All
instance was created. The type is stored in a field named component_type.
 
 
Method resolution order:
All
StaticType
__builtin__.object

Methods defined here:
__init__(self, component_type)
__str__(self)
matches(self, value)

Methods inherited from StaticType:
__repr__(self)
check_matches(self, value)
Calls matches(value). If the reslt is false, a StaticTypeError is
raised. If the result is true, this method simply returns.

Data descriptors inherited from StaticType:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class And(StaticType)
    A static type that matches a value if all of its constructs match that
particular value. The constructs are stored in a field named constructs.
 
 
Method resolution order:
And
StaticType
__builtin__.object

Methods defined here:
__init__(self, *constructs)
__str__(self)
matches(self, value)

Methods inherited from StaticType:
__repr__(self)
check_matches(self, value)
Calls matches(value). If the reslt is false, a StaticTypeError is
raised. If the result is true, this method simply returns.

Data descriptors inherited from StaticType:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Any(StaticType)
    A static type that matches a value if that particular value is iterable
and any of its values match the component type with which this All
instance was created. The type is stored in a field named component_type.
 
 
Method resolution order:
Any
StaticType
__builtin__.object

Methods defined here:
__init__(self, component_type)
__str__(self)
matches(self, value)

Methods inherited from StaticType:
__repr__(self)
check_matches(self, value)
Calls matches(value). If the reslt is false, a StaticTypeError is
raised. If the result is true, this method simply returns.

Data descriptors inherited from StaticType:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Everything(StaticType)
    A static type that matches all values.
 
 
Method resolution order:
Everything
StaticType
__builtin__.object

Methods defined here:
__init__(self)
__str__(self)
matches(self, value)

Methods inherited from StaticType:
__repr__(self)
check_matches(self, value)
Calls matches(value). If the reslt is false, a StaticTypeError is
raised. If the result is true, this method simply returns.

Data descriptors inherited from StaticType:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Field(StaticType)
    A static type that matches a value if that particular value has all of the
fields named when constructing this Field instance and they are all match
the type specified when constructing this Field instance. The field type
is stored in a field named field_type and the field names are stored in a
field named field_names.
 
 
Method resolution order:
Field
StaticType
__builtin__.object

Methods defined here:
__init__(self, field_type, *field_names)
__str__(self)
matches(self, value)

Methods inherited from StaticType:
__repr__(self)
check_matches(self, value)
Calls matches(value). If the reslt is false, a StaticTypeError is
raised. If the result is true, this method simply returns.

Data descriptors inherited from StaticType:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class InternalError(exceptions.Exception)
    An exception thrown when an internal problem occurs with the static type
library. This usually indicates a bug in this library.
 
 
Method resolution order:
InternalError
exceptions.Exception
exceptions.BaseException
__builtin__.object

Data descriptors defined here:
__weakref__
list of weak references to the object (if defined)

Methods inherited from exceptions.Exception:
__init__(...)
x.__init__(...) initializes x; see help(type(x)) for signature

Data and other attributes inherited from exceptions.Exception:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

Methods inherited from exceptions.BaseException:
__delattr__(...)
x.__delattr__('name') <==> del x.name
__getattribute__(...)
x.__getattribute__('name') <==> x.name
__getitem__(...)
x.__getitem__(y) <==> x[y]
__getslice__(...)
x.__getslice__(i, j) <==> x[i:j]
 
Use of negative indices is not supported.
__reduce__(...)
__repr__(...)
x.__repr__() <==> repr(x)
__setattr__(...)
x.__setattr__('name', value) <==> x.name = value
__setstate__(...)
__str__(...)
x.__str__() <==> str(x)
__unicode__(...)

Data descriptors inherited from exceptions.BaseException:
__dict__
args
message

 
class Is(StaticType)
    A static type that matches a value if the value is equal, as determined by
the == operator, to a specified value.
 
 
Method resolution order:
Is
StaticType
__builtin__.object

Methods defined here:
__init__(self, value)
matches(self, value)

Methods inherited from StaticType:
__repr__(self)
__str__(self)
check_matches(self, value)
Calls matches(value). If the reslt is false, a StaticTypeError is
raised. If the result is true, this method simply returns.

Data descriptors inherited from StaticType:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Iterable(StaticType)
    A static type that matches a value if the value is iterable. A value is
iterable if calling the Python function iter(value) does not raise a
TypeError.
 
 
Method resolution order:
Iterable
StaticType
__builtin__.object

Methods defined here:
__init__(self)
__str__(self)
matches(self, value)

Methods inherited from StaticType:
__repr__(self)
check_matches(self, value)
Calls matches(value). If the reslt is false, a StaticTypeError is
raised. If the result is true, this method simply returns.

Data descriptors inherited from StaticType:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Not(StaticType)
    A static type that matches a value if that particular value does not match
the construct with which this Not instance was created. The construct is
stored in a field named construct.
 
 
Method resolution order:
Not
StaticType
__builtin__.object

Methods defined here:
__init__(self, construct)
__str__(self)
matches(self, value)

Methods inherited from StaticType:
__repr__(self)
check_matches(self, value)
Calls matches(value). If the reslt is false, a StaticTypeError is
raised. If the result is true, this method simply returns.

Data descriptors inherited from StaticType:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Or(StaticType)
    A static type that matches a value if any of its constructs match that
particular value. The constructs are stored in a field named constructs.
 
 
Method resolution order:
Or
StaticType
__builtin__.object

Methods defined here:
__init__(self, *constructs)
__str__(self)
matches(self, value)

Methods inherited from StaticType:
__repr__(self)
check_matches(self, value)
Calls matches(value). If the reslt is false, a StaticTypeError is
raised. If the result is true, this method simply returns.

Data descriptors inherited from StaticType:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Positional(StaticType)
    A static type that matches a value if the value is a sequence, it has
exactly the same number of value as were passed to the Positional instance
when it was created, and each item matches the corresponding static type
passed to the Positional instance when it was created. For example,
Positional(int, str, bool) would match a sequence of length 3 containing
an integer, a string, and a boolean, at each respective position in the
sequence.
 
 
Method resolution order:
Positional
StaticType
__builtin__.object

Methods defined here:
__init__(self, *types)
__str__(self)
matches(self, value)

Methods inherited from StaticType:
__repr__(self)
check_matches(self, value)
Calls matches(value). If the reslt is false, a StaticTypeError is
raised. If the result is true, this method simply returns.

Data descriptors inherited from StaticType:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Sequence(StaticType)
    A static type that matches a value if the value is a sequence. A value is
defined to be a sequence if calling len(value) does not raise a TypeError.
 
 
Method resolution order:
Sequence
StaticType
__builtin__.object

Methods defined here:
__str__(self)
matches(self, value)

Methods inherited from StaticType:
__repr__(self)
check_matches(self, value)
Calls matches(value). If the reslt is false, a StaticTypeError is
raised. If the result is true, this method simply returns.

Data descriptors inherited from StaticType:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class StaticType(__builtin__.object)
    The class that all static types extend from. It has two useful methods:
matches and check_matches.
 
StaticType cannot itself be instantiated; you can only construct instances
of subclasses of StaticType.
 
  Methods defined here:
__repr__(self)
__str__(self)
check_matches(self, value)
Calls matches(value). If the reslt is false, a StaticTypeError is
raised. If the result is true, this method simply returns.
matches(self, value)
Checks to see if the specified object matches this static type. If it
does, True will be returned, and False will be returned if it doesn't.
Subclasses of StaticType must override this to perform the actual
matching; StaticType's implementation throws an InternalError.

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class StaticTypeError(exceptions.Exception)
    An exception thrown when an object passed to check_matches does not match
the specified static type.
 
 
Method resolution order:
StaticTypeError
exceptions.Exception
exceptions.BaseException
__builtin__.object

Data descriptors defined here:
__weakref__
list of weak references to the object (if defined)

Methods inherited from exceptions.Exception:
__init__(...)
x.__init__(...) initializes x; see help(type(x)) for signature

Data and other attributes inherited from exceptions.Exception:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

Methods inherited from exceptions.BaseException:
__delattr__(...)
x.__delattr__('name') <==> del x.name
__getattribute__(...)
x.__getattribute__('name') <==> x.name
__getitem__(...)
x.__getitem__(y) <==> x[y]
__getslice__(...)
x.__getslice__(i, j) <==> x[i:j]
 
Use of negative indices is not supported.
__reduce__(...)
__repr__(...)
x.__repr__() <==> repr(x)
__setattr__(...)
x.__setattr__('name', value) <==> x.name = value
__setstate__(...)
__str__(...)
x.__str__() <==> str(x)
__unicode__(...)

Data descriptors inherited from exceptions.BaseException:
__dict__
args
message

 
class Type(StaticType)
    A static type that checks to make sure values are instances of a
particular Python type as per Python's bult-in isinstance function.
 
The type is stored in a field named type.
 
 
Method resolution order:
Type
StaticType
__builtin__.object

Methods defined here:
__init__(self, type)
__str__(self)
matches(self, value)

Methods inherited from StaticType:
__repr__(self)
check_matches(self, value)
Calls matches(value). If the reslt is false, a StaticTypeError is
raised. If the result is true, this method simply returns.

Data descriptors inherited from StaticType:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class TypeFormatError(exceptions.Exception)
    An exception thrown when a static type is malformed. This could happen if,
for example, the number 5 was passed to the compile function; 5 is
obviously not a valid static type, so a TypeFormatError would be raised.
 
 
Method resolution order:
TypeFormatError
exceptions.Exception
exceptions.BaseException
__builtin__.object

Data descriptors defined here:
__weakref__
list of weak references to the object (if defined)

Methods inherited from exceptions.Exception:
__init__(...)
x.__init__(...) initializes x; see help(type(x)) for signature

Data and other attributes inherited from exceptions.Exception:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

Methods inherited from exceptions.BaseException:
__delattr__(...)
x.__delattr__('name') <==> del x.name
__getattribute__(...)
x.__getattribute__('name') <==> x.name
__getitem__(...)
x.__getitem__(y) <==> x[y]
__getslice__(...)
x.__getslice__(i, j) <==> x[i:j]
 
Use of negative indices is not supported.
__reduce__(...)
__repr__(...)
x.__repr__() <==> repr(x)
__setattr__(...)
x.__setattr__('name', value) <==> x.name = value
__setstate__(...)
__str__(...)
x.__str__() <==> str(x)
__unicode__(...)

Data descriptors inherited from exceptions.BaseException:
__dict__
args
message

 
Functions
       
check_matches(value, type)
Short for compile(type).check_matches(value).
compile(short_type)
Compiles the specified static type. This involves converting Python classes
to instances of Type, tuples to instances of Or, and lists to instances of
All. Instances of one of StaticType's subclasses are returned as-is, so
this function doesn't need to be called on them.
 
This function is essentially analogous to Parcon and Pargen's promote
functions.
matches(value, type)
Short for compile(type).matches(value).