class ISQLConnection(IManagedConnection):
"""A ManagedConnection that talks SQL"""
def getRowConverter(description,post=None):
"""Get row-convert function for a given DBAPI description (or None)
For the given 'description', which is a DBAPI cursor result description
(i.e. sequence of tuples describing result columns), return a conversion
function which will map the values in a row, to application-specific
datatypes. (The database-type to application-type mapping should be
controlled via the connection's configuration properties.)
The created conversion function will accept a single database result
row, and return a sequence of values. 'post' is an optional
postprocessing function which will be passed the entire sequence of
converted values as a single argument. The return value of 'post' will
then be returned from the conversion function.
Note that if no postprocessing function is supplied, and no columns in
the given description require type conversion, this method may
return 'None', indicating that no conversion of any kind is required.
"""
DRIVER = Attribute(
"""The name of the DBAPI driver module for this connection"""
)
appConfig = Attribute(
"""A config.Namespace() pointing to 'DRIVER.appConfig'"""
)
def setTxnState(outsideTxn):
"""Set the connection's PEAK and DB transaction state to match"""
class ISeededCriterion(ICriterion):
"""A criterion that works with a SeededIndex"""
enumerable = Attribute(
"""Can criterion enumerate its implications via ``parent_seeds()``?""")
leaf_seed = Attribute(
"""If ``enumerable``, this must be the most-specific parent seed""")
def seeds():
"""Return iterable of known-good keys
The keys returned will be used to build outgoing edges in generic
functions' dispatch tables, which will be passed to the
'dispatch_function' for interpretation."""
def __contains__(key):
"""Return true if criterion is true for 'key'
This method will be passed each seed provided by this or any other
criteria with the same 'dispatch_function' that are being applied to
the same expression."""
def matches(table):
"""Return iterable of keys from 'table' that this criterion matches"""
def parent_criteria():
"""Iterable of all the criteria implied by this criterions"""
class IFeatureSPI(Interface):
# SPI calls used for feature-to-feature collaboration and internal
# implementation
implAttr = Attribute(
"""Name of the actual attribute used to store the feature
(Defaults to the same as 'attrName')"""
)
referencedType = Attribute(
"""The 'IType' for 'typeObject', or a name to find it by"""
)
def get(element):
"""Return the value of the feature for 'element'"""
def set(element,value):
"""Set the value of the feature for 'element'"""
def _notifyLink(element,posn=None):
"""Link to element, inserting it at 'posn' in our value"""
def _notifyUnlink(element,posn=None):
"""Unlink from element, removing it from 'posn' in our value"""
def _link(element,posn=None):
"""Link to element without notifying the inverse feature"""
def _unlink(element,posn=None):
"""Unlink from element without notifying the inverse feature"""
class IType(IComponentKey):
"""Conversion/marshalling info for a model type"""
def mdl_fromString(aString):
"""Return an instance of type created based on 'aString'"""
def mdl_toString(instance):
"""Return a str() of 'instance'; defaults to 'str' if not present"""
def mdl_normalize(value):
"""Return 'value' normalized to the type, or raise error if invalid
If a type does not supply this method, features using the type
will accept any value."""
mdl_syntax = Attribute(
"""Syntax rule for parsing/formatting this type, or None"""
)
mdl_defaultValue = Attribute(
"""Default value for attributes of this type, or NOT_GIVEN"""
)
mdl_typeCode = Attribute(
"""CORBA typecode for the type; if not present, 'Any' is assumed"""
)
class IDelta(Interface):
"""A change that can be undone or redone"""
active = Attribute(
"""True until 'finish()' or 'undo()' is called"""
)
undoable = Attribute("""True if this change can potentially be undone""")
key = Attribute(
"""A unique key identifying the subject of this delta, or None"""
)
def undo():
"""Undo the behavior"""
def redo():
"""Reapply the behavior"""
def merge(delta):
"""Incorporate 'delta' into this delta
Raise an error if delta is already checkpointed or undone, or 'delta' is
not of a compatible type.
"""
def finish():
"""Notification that a checkpoint has occurred"""
class IIniParser(Interface):
"""Parser object passed to 'ISettingParser' instances"""
def add_setting(section, name, value, lineInfo):
"""Define a configuration rule for 'section'+'name' = value
Note that when this method is called by the IIniParser itself,
'section' already has the 'prefix' attribute added to it, and it
is already formatted as a property prefix. So, for a section like::
[foo]
bar = baz
and a parser 'prefix' of '"some.prefix."', this method gets called
with '("some.prefix.foo.", "bar", "baz", ...)'."""
def add_global(name, value):
"""Add/update a global variable for rules evaluation
This creates a new 'globalDict' attribute, so that rules
parsed before this global was added, will still be using
the globals that were in effect when the rule was parsed."""
prefix = Attribute("""Prefix that should be added to all property names""")
pMap = Attribute("""'IConfigurable' that the parser is loading""")
globalDict = Attribute("""Globals dictionary used for eval()ing rules""")
class IPolicyInfo(Interface):
"""Standard informational attributes for interaction policy"""
app = Attribute("""The underlying application object""")
log = Attribute("""Default 'logs.ILogger' for interactions""")
resourcePrefix = Attribute("""Name that starts path to resources""")
defaultMethod = Attribute("""Default method name (e.g. 'index_html')""")
class IArrayMetadata(Interface):
"""Array-object providing item-type metadata"""
typecode = Attribute(
"typecode",
"""The typecode character used to create the array""",
)
itemsize = Attribute(
"itemsize",
"""The length in bytes of one array item in the internal representation""",
)
class IActiveDescriptor(Interface):
"""Metadata supplied by active descriptors (e.g. binding.Attribute)"""
offerAs = Attribute(
"""Sequence of config keys that this attribute binding offers""")
uponAssembly = Attribute(
"""Activate this attribute binding when object knows all its parents"""
)
def activateInClass(klass, attrName):
"""Do any necessary installation in 'klass' under name 'attrName'"""
class IDataManager_SPI(Interface):
"""Methods/attrs that must/may be redefined in a QueryDM subclass"""
cache = Attribute("a cache for ghosts and loaded objects")
defaultClass = Attribute("Default class used for '_ghost' method")
def _ghost(oid, state=None):
"""Return a ghost of appropriate class, based on 'oid' and 'state'
Note that 'state' should be loaded into the returned object via its
'__setstate__()' method. If 'state' is 'None', the returned object's
'_p_deactivate()' method will be called instead (by __getitem__)."""
def _load(oid, ob):
"""Load & return the state for 'oid', suitable for '__setstate__()'
class IAddress(IName):
"""URL/Name that supports in-context self-retrieval (URL_KIND)"""
def getAuthorityAndName():
"""Return an 'authority,name' tuple"""
defaultFactory = Attribute(
"""Name of default object factory for this address""")
class IDataManager(IComponent,ITransactionParticipant):
"""Data manager for persistent objects or queries"""
resetStatesAfterTxn = Attribute(
"""Set to false to disable auto-deactivation of objects from cache"""
)
def get(oid, default=None):
"""Retrieve the persistent object designated by 'oid', or 'default'
This immediately retrieves the object and is the method that clients
should normally use to retrieve items from the data manager."""
def __getitem__(oid):
"""Lazily retrieve the persistent object designated by 'oid'
This method is intended for use by other DMs that wish to lazily load
references to other objects; it should not normally be used by clients,
since it does not let you know immediately whether the desired item
exists in underlying storage database."""
def __contains__(ob):
"""Is 'ob' an object stored by this DM (or such an object's oid)?
Note that this method may causes a database access if the object isn't
already in cache.
"""
def preloadState(oid, state):
"""Pre-load 'state' for object designated by 'oid' and return it"""
class IObjectPyDoc(Interface):
"""Object which contains python doc string
"""
__doc__ = Attribute(
"__doc__",
"""Python documentation string for the object""",
)
class IObjectPyDict(Interface):
"""Object with a Python __dict__ attribute
"""
__dict__ = Attribute(
"__dict__",
"""Python object dictionary""",
)
class IStreamClose(Interface):
"""Stream providing a close method to release resources"""
closed = Attribute(
"closed",
"""Boolean displaying the current open/closed status""",
)
def close():
"""flush internal buffers, close the stream, and release resources"""
class IEnumValue(Interface):
"""An enumeration instance"""
name = Attribute("""The name of this enumeration value""")
def __hash__():
"""Hash of the enumeration instance's value"""
def __cmp__():
"""Enumeration instances compare equal to their value"""
class IDOMletElement(IDOMletNode):
"""A component representing an XML/HTML element"""
def addChild(node):
"""Add 'node' (an 'IDOMletNode') to element's direct children"""
def addParameter(name, element):
"""Declare 'element' (an 'IDOMletElement') as part of parameter 'name'
Note that 'element' is not necessarily a direct child of the current
element, and that this method may be called multiple times for the
same 'name', if multiple 'define' nodes use the same name.
It's up to the element to do any validation/restriction of parameter
names/values."""
tagFactory = Attribute(
"""'IDOMletElementFactory' to be used for non-DOMlet child tags""")
textFactory = Attribute(
"""'IDOMletNodeFactory' to be used for plain text child nodes""")
literalFactory = Attribute(
"""'IDOMletNodeFactory' to be used for literals (e.g. comments,
processing instructions, etc.) within this element""")
class IName(IComponentKey):
"""Abstract name object"""
nameKind = Attribute("One of COMPOUND_KIND, COMPOSITE_KIND, or URL_KIND")
def __add__(other):
"""Add 'other' to name, composing a name that is relative to this one"""
def __radd__(other):
"""Add name to 'other', using this name as a relative name to it"""
def __sub__(other):
"""Subtract 'other' from name, returning 'None' if not a prefix"""
def __rsub__(other):
"""Subtract name from 'other', returning 'None' if not a prefix"""
def __hash__():
"""Should be usable as a dictionary key"""
def __eq__():
"""Should be usable as a dictionary key"""
class IICBListener(Interface):
connection = Attribute("Connection we're listening to")
def loginOK(con):
"""Login was successful"""
def publicMessage(con, nick, message):
"""Public message was sent by nick"""
def privateMessage(con, nick, message):
"""Private message was sent to us by nick"""
def Status(con, category, message):
"""Status message in a given category"""
def Error(con, message):
"""Report an error message"""
def importantMessage(con, category, message):
"""Report an important message in category"""
def serverExit(con, self):
"""Server Exiting"""
def commandOutput(con, data):
"""Output resulting (con, maybe) from a command"""
def protocolLevel(con, protover, host, server):
"""Initial protocol information"""
def beepFrom(con, nick):
"""We got beeped by nick"""
def gotPing(con, message):
"""We were pinged by the server"""
def unknownPacket(con, kind, data):
"""We got an unknown packet"""
class ICriterion(Interface):
"""A criterion to be applied to an expression
A criterion comprises a "node type" (that determines how the
criterion will be checked, such as an 'isinstance()' check or range
comparison) and a value or values that the expression must match. Note
that a criterion describes only the check(s) to be performed, not the
expression to be checked."""
node_type = Attribute(
"""The type of object that will actually do the dispatching""")
def __and__(other):
"""Apply multiple criteria of the same node type to the same expr"""
def __hash__():
"""Equal criteria should have equal hashes"""
def __eq__(other):
"""Return true if equal"""
def __ne__(other):
"""Return false if equal"""
def __invert__():
"""Return an inverse version of this criterion (i.e. '~criterion')"""
def implies(other):
"""Return true if truth of this criterion implies truth of 'other'"""
def subscribe(listener):
"""Call 'listener.criterionChanged()' if applicability changes
Multiple calls with the same listener should be treated as a no-op."""
def unsubscribe(listener):
"""Stop calling 'listener.criterionChanged()'
class IFeature(Interface):
lowerBound = Attribute(
"""Lower bound of multiplicity"""
)
upperBound = Attribute(
"""Upper bound of multiplicity; 'None' means "unbounded"""
)
isRequired = Attribute(
"""True if 'lowerBound' is greater than zero"""
)
isOrdered = Attribute(
"True means the feature is an ordered sequence"
)
isChangeable = Attribute(
"True means feature is changeable"
)
isDerived = Attribute(
"""True means feature is derived (implies 'not isChangeable')"""
)
isMany = Attribute(
"""True means 'upperBound > 1'; i.e., this is a "plural" feature"""
)
isReference = Attribute(
"""True if feature references a non-primitive/non-struct object type"""
)
attrName = Attribute(
"""Name of the attribute the feature implements"""
)
typeObject = Attribute(
"""'IType' instance representing the type of the feature"""
)
def fromString(aString):
"""See 'IType.mdl_fromString()'"""
def fromFields(fieldSequence):
"""See 'IType.mdl_fromFields()'"""
def __get__(element,type=None):
"""Retrieve value of the feature for 'element'"""
def __set__(element,value):
"""Set 'value' as the value of the feature for 'element'"""
def __delete__(element):
"""Unset the feature for 'element' (works like __delattr__)"""
def add(element,item):
"""Add the item to the collection/relationship, reject if multiplicity
exceeded"""
def remove(element,item):
"""Remove the item from the collection/relationship, if present"""
def replace(element,oldItem,newItem):
"""Replace oldItem with newItem in the collection; raises ValueError
if oldItem is missing"""
def insertBefore(element,oldItem,newItem):
"""Insert newItem before oldItem in the collection; raises ValueError
if oldItem is missing, TypeError if feature is not ordered"""
referencedEnd = Attribute(
"""Name of the inverse feature on the target class
'None' means this is a unidirectional reference."""
)
class IManagedConnection(IComponent,ITransactionParticipant):
"""Transactable "Connection" object that appears to always be open"""
connection = Attribute(
"""The actual underlying (LDAP, SQL, etc.) connection object
This attribute is primarily for use by subclasses of ManagedConnection.
It is a 'binding.Make()' link to the '_open()' method (see
IManagedConnImpl interface for details)."""
)
txnTime = Attribute(
"""This connection's view of the Unix-format time of this transaction
This attribute should be computed once and stored for the transaction
duration, by something like 'SELECT GETDATE()' in the case of an SQL
connection. If the underlying connection has no notion of the current
time, this can be computed by calling getTimestamp() on the transaction
object. In any event, accessing this attribute should ensure that the
connection joins the current transaction, if it hasn't already"""
)
def closeASAP():
"""Close the connection as soon as it's not in a transaction"""
def close():
"""Close the connection immediately"""
def __call__(*args, **kw):
"""Return a (possibly initialized) ICursor
Creates a new ICursor instance initialized with the passed
keyword arguments. If positional arguments are supplied,
they are passed to the new cursor's 'execute()' method before
it is returned.
This method is the primary way of interacting with a connection;
either you'll pass positional arguments and receive an
initialized and iterable cursor, or you'll call with no arguments
or keywords only to receive a cursor that you can use to perform
more "low-level" interactions with the database.
"""
def registerCursor(ob):
"""Register an object whose 'close()' method must be called"""
def closeCursor():
"""Close all registered cursors which are still active"""
class IStreamName(Interface):
"""Stream having a name attribute"""
name = Attribute(
"name",
"""Filename or data-source description""",
)
class IDOMletNode(IDOMletRenderable):
"""A component of a page template"""
staticText = Attribute(
"""The static XML text that represents this node, or None if
the node contains any dynamic content.""")
class Abstract(AbstractBase):
value = Attribute("testing", "value", i)
class ITraversalContext(Interface):
"""A traversed-to location
Note: this inherits from 'security.IInteraction', so it also supports
the 'user' attribute, 'allows()' method, and so on.
"""
name = Attribute("""Name of 'current'""")
current = Attribute("""Current object location""")
environ = Attribute("""WSGI (PEP 333) 'environ' mapping""")
policy = Attribute("""'IInteractionPolicy' for this hit""")
user = Attribute("""Current user of the application""")
skin = Attribute("""Current 'ISkin' for this hit""")
url = Attribute("""Current object's standard URL""")
rootURL = Attribute("""Application root URL""")
absoluteURL = Attribute("""Absolute canonical URL""")
traversedURL = Attribute("""URL traversed to get to this context""")
viewService = Attribute("""Nearest 'IViewService' for this context""")
def childContext(name, ob):
"""Return a new child context with name 'name' and current->'ob'"""
def peerContext(name, ob):
"""Return a new peer context with name 'name' and current->'ob'"""
def parentContext():
"""Return this context's parent, or self if no parent"""
def traverseName(name, default=NOT_GIVEN):
"""Return a new context obtained by traversing to 'name'"""
def renderHTTP():
"""Equivalent to 'IHTTPHandler(self.current).handle_http()'"""
def getResource(path):
"""Return the named resource"""
def shift():
"""Shift a path component from 'PATH_INFO' to 'SCRIPT_NAME'
This modifies the context's (possibly shared) environment such that
one path component is moved from the beginning of 'PATH_INFO' to the
end of 'SCRIPT_NAME'. The shifted path component is returned, or
'None' if 'PATH_INFO' is empty.
Before the shift, 'PATH_INFO' is normalized to eliminate empty path
components and path components that contain a single dot, so these
should never be returned. Double-dot components, however, *are*
returned, and 'SCRIPT_NAME' is adjusted accordingly (i.e., the trailing
path component of 'SCRIPT_NAME' is stripped, if one is present).
Note that this changes the 'environ' being used by this context and
any parent or child contexts that share it. Thus, it's usually only
safe to use this method from within a 'handle_http()' method, such as
when determining the next object to traverse to, if any.
"""
def clone(**kw):
"""Create a duplicate context, using supplied keyword arguments
Acceptable keyword arguments include: 'name', 'current', 'environ',
'policy', 'skin', 'rootURL', 'user', 'previous', and
'clone_from'. Most of these just set the corresponding attribute on
the new context, but the following names are special:
'clone_from' -- an existing context to clone. If supplied, its
'user', 'skin', 'policy', and 'previous' attributes will
be used as defaults for the corresponding keyword arguments, if
they are not supplied.
'previous' -- an existing context that will be used as the new
context's parent context.
"""
def requireAccess(qname,
subject,
name=None,
permissionNeeded=NOT_GIVEN,
user=NOT_GIVEN):
"""'NotAllowed' unless 'user' has 'permissionNeeded' for 'subject'
'qname' is used only for generating an appropriate error if permission
isn't granted. The other arguments are per the 'allows()' method of
'security.IInteraction'. There is no return value.
"""
def allows(subject, name=None, permissionNeeded=NOT_GIVEN, user=NOT_GIVEN):
"""Return true if 'user' has 'permissionNeeded' for 'subject'
class ITypeInfo(IType):
"""Introspection info for a model type"""
mdl_isAbstract = Attribute(
"""Is this an abstract class? If so, instances can't be created."""
)
mdl_featuresDefined = Attribute(
"""Sorted tuple of feature objects defined/overridden by this class"""
)
mdl_featureNames = Attribute(
"""Names of all features, in monotonic order (see 'mdl_features')"""
)
mdl_sortedFeatures = Attribute(
"""All feature objects of this type, in sorted order"""
)
mdl_compositeFeatures = Attribute(
"""Ordered subset of 'mdl_features' that are composite"""
)
mdl_features = Attribute(
"""All feature objects of this type, in monotonic order
The monotonic order of features is equivalent to the concatenation of
'mdl_featuresDefined' for all classes in the type's MRO, in
reverse MRO order, with duplicates (i.e. overridden features)
eliminated. That is, if a feature named 'x' exists in more than one
class in the MRO, the most specific definition of 'x' will be used
(i.e. the first definition in MRO order), but it will be placed in the
*position* reserved by the *less specific* definition. The idea is
that, once a position has been defined for a feature name, it will
continue to be used by all subclasses, if possible. For example::
class A(model.Type):
class foo(model.Attribute): pass
class B(A):
class foo(model.Attribute): pass
class bar(model.Attribute): pass
would result in 'B' having a 'mdl_features' order of '(foo,bar)',
even though its 'mdl_featuresDefined' would be '(bar,foo)' (because
features without a sort priority define are ordered by name).
The purpose of using a monotonic ordering like this is that it allows
subtypes to use a serialized format that is a linear extension of
their supertype, at least in the case of single inheritance. It may
also be useful for GUI layouts, where it's also desirable to have a
subtype's display look "the same" as a base type's display, except for
those features that it adds to the supertype."""
)
class IStreamMode(Interface):
"""Stream having a mode attribute"""
mode = Attribute(
"mode",
"""The I/O mode for the file""",
)
class IObjectPyName(Interface):
"""Object with a __name__ attribute"""
__name__ = Attribute(
"__name__",
"""Integral name for the object""",
)
class IPlace(Interface):
"""Traversable component with a fixed location"""
place_url = Attribute("Relative URL (no leading '/') from skin")