# -*- coding: iso-8859-1 -*-
#-----------------------------------------------------------------------------
# Modeling Framework: an Object-Relational Bridge for python
#
# Copyright (c) 2001-2004 Sbastien Bigaret <sbigaret@users.sourceforge.net>
# All rights reserved.
#
# This file is part of the Modeling Framework.
#
# This code is distributed under a "3-clause BSD"-style license;
# see the LICENSE file for details.
#-----------------------------------------------------------------------------
"""
SchemaGeneration API
This class provides specialized methods producing statements to create or
drop database's elements, such as databases, tables, columns, constraints
and specific support for the generation of primary keys.
Specific AdaptorLayers may provide their own SchemaGeneration class ; in
that case, that class should be derived from SchemaGeneration and it
overrides inherited methods as needed. Specific instructions for overriding
are given along with each method's documentation.
Constants
The following constants are defined, for use by the 'options' dictionary
in methods 'schemaCreationStatementsForEntities()' and
'schemaCreationScriptForEntities()'
- DropDatabaseKey
- CreateDatabaseKey
- DropTablesKey
- CreateTablesKey
- DropPrimaryKeySupportKey
- CreatePrimaryKeySupportKey
- PrimaryKeyConstraintsKey
- ForeignKeyConstraintsKey
- DropForeignKeyConstraintsKey
- DropPrimaryKeyConstraintsKey
CVS information
$Id: SchemaGeneration.py 932 2004-07-20 06:21:57Z sbigaret $
"""
__version__='$Revision: 932 $'[11:-2]
try:
from Interface import Base
except:
class Base:
pass
def defaultOrderingsForSchemaCreation():
"""
Used in method SchemaGeneration.schemaCreationScriptForEntities() to order
the schema creation statements produced
This method is also available as a static method in class SchemaGeneration.
"""
def setDefaultOrderingsForSchemaCreation():
"""
Sets the default ordering. See defaultOrderingsForSchemaCreation() for
details.
This method is also available as a static method in class SchemaGeneration.
"""
class ISchemaGeneration(Base):
"""
... __TBD
Additionnally the class defines the following static methods, none of which
should be overriden by subclasses:
- defaultOrderingsForSchemaCreation
- setDefaultOrderingsForSchemaCreation
"""
def __init__(self, anAdaptor):
"""
Initializes the SchemaGeneration object with the given concrete Adaptor.
"""
def appendExpressionToScript(self, expression, script):
"""
Appends the expression to the StringIO script, prepended with a semi-colon
(';') and a newline if the StringIO is not empty.
Subclasses overrides this method if the underlying database uses a
different syntax.
"""
def createDatabaseStatementsForConnectionDictionary(self, connectionDictionary, administrativeConnectionDictionary):
"""
Default implementation returns an empty list. Subclasses override this
method ... __TBD
"""
def createTableStatementsForEntityGroup(self, entityGroup):
"""
Returns a list of SQLExpressions needed to create the tables defined by
the supplied 'entityGroup', or an empty list if 'entityGroup' is empty.
Default implementation returns a list consisting of one sole SQLExpression
whose statement is of the following form::
CREATE TABLE <TABLE_NAME> ( <COLUMN_CREATE_CLAUSES> )
where <TABLE_NAME> is the externalName of the first entity in
'entityGroup', and <COLUMN_CREATE_CLAUSES> is the list of all create
clauses needed to build the underlying columns
--see SQLExpression.addCreateClauseForAttribute(). That list can be
accessed in the returned SQLExpression object through sending it the
message 'listString()'
Parameter 'entityGroup' is a sequence of entities which share the same
external name.
See also: dropTableStatementsForEntityGroup, Entity.externalName(),
SQLExpression.addCreateClauseForAttribute(),
SQLExpression.listString()
"""
def createTableStatementsForEntityGroups(self, entityGroup):
"""
Invokes createTableStatementsForEntityGroup() for each entityGroup in
'entityGroups', and returns the list of SQLExpressions needed to create
the necessary table. It is guaranteed that all SQLExpressions in the
returned sequence have a different statement (SQLExpression.statement()).
Subclasses should not need to override this method. If they do, they
should comply with the guaranteed nature of the returned sequence, as
stated above.
Parameter:
entityGroups -- a sequence of entityGroups ; an 'entityGroup' is a list
of entities whose externalNames are identical.
"""
def dropDatabaseStatementsForConnectionDictionary(self, connectionDictionary, administrativeConnectionDictionary):
"""
Default implementation returns an empty list.
"""
def dropForeignKeyConstraintStatementsForRelationship(self, relationship):
"""
Default implementation returns an empty list. Subclasses override this
method to return a sequence of SQLExpressions designed to remove the
foreign key constraints built by
foreignKeyConstraintStatementsForRelationship(). Returned value should be
an empty list if 'entityGroup' is empty.
Parameter 'entityGroup' is a list of entities whose externalNames are
identical.
See also:
foreignKeyConstraintStatementsForRelationship()
"""
def dropPrimaryKeyConstraintStatementsForEntityGroup(self, entityGroup):
"""
Default implementation returns an empty list. Subclasses override this
method to return a sequence of SQLExpressions designed to remove the
constraint Primary Key constraints built by
primaryKeyConstraintStatementsForEntityGroup(). Returned value should be
an empty list if 'entityGroup' is empty.
Parameter 'entityGroup' is a list of entities whose externalNames are
identical.
See also:
primaryKeyConstraintStatementsForEntityGroup()
"""
def dropPrimaryKeyConstraintStatementsForEntityGroups(self, entityGroups):
"""
Iterates on each entityGroup in 'entityGroups', sends the message
'dropPrimaryKeyConstraintStatementsForEntityGroup' to each of them,
collects the results and returns them in a sequence. It is guaranteed that
all SQLExpressions in the returned sequence have a different statement
(SQLExpression.statement()).
Subclasses should not need to override this method. If they do, they
should comply with the guaranteed nature of the returned sequence, as
stated above.
Parameter:
entityGroups -- a sequence of entityGroups ; an 'entityGroup' is a list
of entities whose externalNames are identical.
See also: primaryKeyConstraintStatementsForEntityGroups()
"""
def dropPrimaryKeySupportStatementsForEntityGroup(self, entityGroup):
"""
Default implementation returns an empty list. Subclasses override this
method to return a sequence of SQLExpressions designed to remove the
elements supporting the mechanism used to generate primary keys, as they
were created by primaryKeySupportStatementsForEntityGroup(). Returned
value should be an empty list if 'entityGroup' is empty.
Parameter 'entityGroup' is a list of entities whose externalNames are
identical.
See also:
primaryKeySupportStatementsForEntityGroup()
AdaptorContext.primaryKeysForNewRowsWithEntity()
"""
def dropPrimaryKeySupportStatementsForEntityGroups(self, entityGroups):
"""
Iterates on each entityGroup in 'entityGroups', sends the message
'dropPrimaryKeySupportStatementsForEntityGroup()' to each of them,
collects the results and returns them in a sequence. It is guaranteed that
all SQLExpressions in the returned sequence have a different statement
(SQLExpression.statement()).
Subclasses should not need to override this method. If they do, they
should comply with the guaranteed nature of the returned sequence, as
stated above.
Parameter:
entityGroups -- a sequence of entityGroups ; an 'entityGroup' is a list
of entities whose externalNames are identical.
"""
def dropTableStatementsForEntityGroup(self, entityGroup):
"""
Parameter:
entityGroup -- a list of entities whose externalNames are identical.
"""
def dropTableStatementsForEntityGroups(self, entityGroups):
"""
Iterates on each entityGroup in 'entityGroups', sends the message
'dropPrimaryKeySupportStatementsForEntityGroup()' to each of them,
collects the results and returns them in a sequence.
Subclasses should not need to override this method. If they do, they
should comply with the guaranteed nature of the returned sequence, as
stated above.
"""
def foreignKeyConstraintStatementsForRelationship(self, relationship):
"""
Returns a list of SQLExpressions needed to add a constraint statement
for the given relationship. Under specific conditions on 'relationship',
expressed below, that lists consists of a single SQLExpression
statement of the following form::
ALTER TABLE <TABLE> ADD CONSTRAINT <REL_NAME> FOREIGN KEY
(<FKS>) REFERENCES <DESTINATION_TABLE>(<DESTINATION_PK>)
where TABLE is the relationship's entity externalName(),
REL_NAME is the relationship's source attribute columnName(),
FKS is a comma-separated list of the relationship's source
attributes.columnName(),
DESTINATION_PKS is a comma-separated list of the rel.'s
destinationAttributes().columnName(),
DESTINATION_TABLE is the relationship.destinationEntity() 's
externalName()
The conditions under which the statement above is returned are:
- the relationship is a toOne rel. and it is not flattened,
- its inverseRelationship, if any, is a toMany relationship,
- its source and destinationEntity share the same model
If any of these conditions is not fulfilled the method returns an empty
sequence.
"""
def primaryKeyConstraintStatementsForEntityGroup(self, entityGroup):
"""
Default implementation returns an empty list. __TBD
Parameter 'entityGroup' is a list of entities whose externalNames are
identical.
"""
def primaryKeyConstraintStatementsForEntityGroups(self, entityGroups):
"""
Iterates on each entityGroup in 'entityGroups', sends the message
'primaryKeyConstraintStatementsForEntityGroup' to each of them, collects
the results and returns them in a sequence. It is guaranteed that all
SQLExpressions in the returned sequence have a different statement
(SQLExpression.statement()).
Subclasses should not need to override this method. If they do, they
should comply with the guaranteed nature of the returned sequence, as
stated above.
Parameter:
entityGroups -- a sequence of entityGroups ; an 'entityGroup' is a list
of entities whose externalNames are identical.
"""
def primaryKeySupportStatementsForEntityGroup(self, entityGroup):
"""
Default implementation returns an empty list. Subclasses override this
method to return a sequence of SQLExpressions in adequation to the
mechanism used to generate primary keys, or an empty list if
'entityGroup' is empty.
Subclasses overriding this method have no need to call the super
implementation.
Parameter:
entityGroup -- a list of entities whose externalNames are identical.
See also:
dropPrimaryKeySupportStatementsForEntityGroup()
AdaptorContext.primaryKeysForNewRowsWithEntity()
Entity.primaryKeyRootName()
"""
def primaryKeySupportStatementsForEntityGroups(self, entityGroups):
"""
Iterates on each entityGroup in 'entityGroups', sends the message
'primaryKeySupportStatementsForEntityGroup' to each of them, collects the
results and returns them in a sequence. It is guaranteed that all
SQLExpressions in the returned sequence have a different statement
(SQLExpression.statement()).
Subclasses should not need to override this method. If they do, they
should comply with the guaranteed nature of the returned sequence, as
stated above.
Parameter:
entityGroups -- a sequence of entityGroups ; an 'entityGroup' is a list
of entities whose externalNames are identical.
"""
def schemaCreationScriptForEntities(self, allEntities, options,
keyOrdering=()):
"""
__TBD
If parameter 'keyOrdering' is omitted, None or empty it defaults to
'defaultOrderingsForSchemaCreation()'.
See also: schemaCreationStatementsForEntities(), appendExpressionToScript()
defaultOrderingsForSchemaCreation()
"""
def schemaCreationStatementsForEntities(self, allEntities, options):
"""
__TBD doc.
"""
def schemaCreationStatementsForEntitiesByOptions(self, allEntities, options):
"""
__TBD doc.
"""
def tableEntityGroupsForEntities(self, entities):
"""
Returns a list of entityGroups ; each entityGroup consists of the
entities in parameter 'entities' which share the same externalName(), and
wich answered positively to the definesTableColumns() message. Hence, the
set of entities returned in the entityGroups is a (possibly smaller)
subset of the entities supplied in parameter 'entities'
See also: Entity.definesTableColumns()
"""
|