[SQL-CVS] r1474 - SQLObject/branches/0.7-bugfix/docs
SQLObject is a Python ORM.
Brought to you by:
ianbicking,
phd
Menu
▾
▴
[SQL-CVS] r1474 - SQLObject/branches/0.7-bugfix/docs
|
From: <sub...@co...> - 2006-01-06 19:41:56
|
Author: phd Date: 2006-01-06 19:41:51 +0000 (Fri, 06 Jan 2006) New Revision: 1474 Modified: SQLObject/branches/0.7-bugfix/docs/Inheritance.txt SQLObject/branches/0.7-bugfix/docs/SQLObject.txt Log: Applied the patch N 1371678 from the SF tracker - Docs update. Modified: SQLObject/branches/0.7-bugfix/docs/Inheritance.txt =================================================================== --- SQLObject/branches/0.7-bugfix/docs/Inheritance.txt 2006-01-05 16:30:37 UTC (rev 1473) +++ SQLObject/branches/0.7-bugfix/docs/Inheritance.txt 2006-01-06 19:41:51 UTC (rev 1474) @@ -304,5 +304,11 @@ is no warranty that this version will work. * Thanks to Ian Bicking for SQLObject; this is a wonderful python module. +* Although all the attributes are inherited, the same does not apply + to sqlmeta data. Don't try to get a parent column via the sqlmeta.columns + dictionary of an inherited InheritableSQLObject: it will raise a KeyError. + The same applies to joins: the sqlmeta.joins list will be empty in an + inherited InheritableSQLObject if a join has been defined in the parent + class, even though the join method will work correctly. * If you have suggestion, bugs, or patch to this patch, you can contact the SQLObject team: <sqlobject-discuss at lists.sourceforge.net> Modified: SQLObject/branches/0.7-bugfix/docs/SQLObject.txt =================================================================== --- SQLObject/branches/0.7-bugfix/docs/SQLObject.txt 2006-01-05 16:30:37 UTC (rev 1473) +++ SQLObject/branches/0.7-bugfix/docs/SQLObject.txt 2006-01-06 19:41:51 UTC (rev 1474) @@ -407,6 +407,11 @@ <Address 1 ...> >>> p.addresses [<Address 1 ...>] + +.. note:: + MultipleJoin, as well as RelatedJoin, returns a list of results. + Would you prefer to get a SelectResults objects, you should use + SQLMultipleJoin and SQLRelated Join. Usage stays immutated. Many-to-Many Relationships -------------------------- @@ -468,6 +473,19 @@ a class, and its rows do not have equivalent Python objects -- this hides some of the nuisance of a many-to-many relationship. +By the way, if you want to create an intermediate table of your own, +maybe with additional columns, be aware that the standard SQLObject +methods add/removesomething may not work as expected. Assuming that +you are providing the join with the correct joinColumn and otherColumn +arguments, be aware it's not possibile to insert extra data via such +methodos, nor will they set any default value. + +Let's have an example: in the previous User/Role system, +you're creating a UserRole intermediate table, with the two columns +containing the foreign keys for the MTM relationship, and an additional +DateTimeCol defaulting to datetime.datetime.now : that column will +stay empty when adding roles with the addRole method. + You may notice that the columns have the extra keyword argument `alternateID`. If you use ``alternateID=True``, this means that the column uniquely identifies rows -- like a username uniquely identifies @@ -727,6 +745,10 @@ saying that if you're not using the ``sqlmeta`` class you're doing things in a deprecated way. +Please note: when using InheritedSQLObject, sqlmeta attributes don't +get inherited, e.g. you can't access via the sqlmeta.columns dictionary +the parent's class column objects. + Using sqlmeta ~~~~~~~~~~~~~ @@ -948,6 +970,22 @@ representation (as those commands generate SQL that is run on the database). +Undefined attributes +~~~~~~~~~~~~~~~~~~~~ + +There's one more thing worth telling, because you may something get +strange results when making a typo. SQLObject won't ever complain or +raise any error when setting a previously undefined attribute; it will +simply set it, without making any change to the database, i.e: it will +work as any other attribute you set on any Python class, it will +'forget' it is a SQLObject class. + +This may sometimes be a problem: if you have got a 'name' attribute and +you you write 'a.namme="Victor"' once, when setting it, you'll get no +error, no warning, nothing at all, and you may get crazy at understanding +why you don't get that value set in your DB. + + Reference ========= @@ -1021,6 +1059,8 @@ `CurrencyCol`: Equivalent to ``DecimalCol(size=10, precision=2)``. + WARNING: as DecimalCol MAY NOT return precise numbers, this column + may share the same behaviour. Please read the DecimalCol warning. `DateTimeCol`: A date and time (usually returned as an datetime or mxDateTime object). @@ -1035,7 +1075,12 @@ Base-10, precise number. Uses the keyword arguments `size` for number of digits stored, and `precision` for the number of digits after the decimal point. - + WARNING: it may happen that DecimalCol values, although correctly + stored in the DB, are returned as floats instead of decimals. + You should test with your database adapter, and you should try + importing the Decimal type and your DB adapter before importing + SQLObject. + `EnumCol`: One of several string values -- give the possible strings as a list, with the `enumValues` keyword argument. MySQL has a native @@ -1085,12 +1130,15 @@ but for back references and many-to-many relationships you'll use joins. -MultipleJoin: One-to-Many -~~~~~~~~~~~~~~~~~~~~~~~~~ +MultipleJoin and SQLMultipleJoin: One-to-Many +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See `One-to-Many Relationships`_ for an example of one-to-many relationships. +MultipleJoin returns a list of results, while SQLMultipleJoin returns a +SelectResults object. + Several keyword arguments are allowed to the `MultipleJoin` constructor: .. _`Multiple Join Keywords`: @@ -1099,6 +1147,14 @@ The column name of the key that points to this table. So, if you have a table ``Product``, and another table has a column ``ProductNo`` that points to this table, then you'd use ``joinColumn="ProductNo"``. + WARNING: the argument you pass must conform to the column name in the + database, not to the column in the class. So, if you have a SQLObject + containing the 'ProductNo' column, this will probably be translated + into 'product_no_id' in the DB ( product_no is the normal uppercase- + to-lowercase + underscores SQLO Translation, the added _id is just + because the column referring to the table is probably a ForeignKey, + and SQLO translates foreign keys that way). + You should pass that parameter. `orderBy`: Like the `orderBy`_ argument to `select()`, you can specify the order that the joined objects should be returned in. `_defaultOrder` @@ -1109,24 +1165,45 @@ created automatically, and is normally implied (i.e., ``addresses = MultipleJoin(...)`` implies ``joinMethodName="addresses"``). -RelatedJoin: Many-to-Many -~~~~~~~~~~~~~~~~~~~~~~~~~ +RelatedJoin and SQLRelatedJoin: Many-to-Many +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See `Many-to-Many Relationships`_ for examples of using many-to-many joins. +RelatedJoin returns a list of results, while SQLRelatedJoin returns a +SelectResults object. + + `RelatedJoin` has all the keyword arguments of `MultipleJoin`__, plus: __ `Multiple Join Keywords`_ `otherColumn`: - Similar to `joinColumn`, but referring to the joined class. + Similar to `joinColumn`, but referring to the joined class. Same + warning about column name. `intermediateTable`: The name of the intermediate table which references both classes. + WARNING: you should pass the database table name, not the SQLO + class representine. `addRemoveName`: In the `user/role example`__, the methods `addRole(role)` and `removeRole(role)` are created. The ``Role`` portion of these method names can be changed by giving a string value here. +`createRelatedTable`: + default: ``True``. If ``False``, then the related table won't be + automatically created; instead you must manually create it (e.g., + with explicit SQLObject classes for the joins). New in 0.7.1. +.. note:: + Let's suppose you have SQLObject-inherited classes Alpha and Beta, + and an AlphasAndBetas used for the many-to-many relationship. + AlphasAndBetas contains the alphaIndex Foreign Key column referring + to Alpha, and the betaIndex FK column referring to Beta. + if you want a 'betas' RelatedJoin in Alpha, you should add it to + Alpha passing 'Beta' (class name!) as the first parameter, then + passing 'alpha_index_id' as joinColumn, 'beta_index_id' as + otherColumn, and 'alphas_and_betas' as intermediateTable. + __ `Many-to-Many Relationships`_ An example schema that requires the use of `joinColumn`, `otherColumn`, @@ -1347,7 +1424,6 @@ class Person(SQLObject): _style = MixedCaseStyle(longID=True) - firstName = StringCol() lastName = StringCol() |
