[SQL-CVS] SQLObject/docs News.txt,1.5,1.6

[<ian...@us...>]

Update of /cvsroot/sqlobject/SQLObject/docs
In directory sc8-pr-cvs1:/tmp/cvs-serv21723

Modified Files:
	News.txt 
Log Message:
Documented the new features.


Index: News.txt
===================================================================
RCS file: /cvsroot/sqlobject/SQLObject/docs/News.txt,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** News.txt	7 Apr 2003 20:11:28 -0000	1.5
--- News.txt	25 May 2003 06:03:45 -0000	1.6
***************
*** 8,11 ****
--- 8,138 ----
  .. _start:
  
+ SQLObject 0.4
+ =============
+ 
+ Features
+ --------
+ 
+ * You can specify columns in a new, preferred manner::
+ 
+       class SomeObject(SQLObject):
+           someColumn = Col()
+ 
+   Equivalent to::
+ 
+       class SomeObject(SQLObject):
+           _columns = [Col('someColumn')]
+ 
+ * Cache objects have a clear method, which empties all objects.
+   However, weak references to objects *are* maintained, so the
+   integrity of the cache can be ensured.
+ 
+ * SQLObject subclasses can be further subclassed, adding or removing
+   column definitions (as well as changing settings like connection,
+   style, etc).  Each class still refers to a single concrete table in
+   the database -- the class hierarchy is not represented in the
+   database.
+ 
+ * Each SQLObject subclass can have an associated style, as given in
+   the `_style` attribute.  This object is used to map between Python
+   and database names (e.g., the column name for a Python attribute).
+   Some samples are available in the `Style` module.
+ 
+ * Postgres support for `_fromDatabase` (reading a table definition from
+   the database, and creating a class from that).
+ 
+ * Postgres id columns more permissive, you don't have to create a
+   specially named sequence (or implicitly create that sequence through
+   ``SERIAL``).  lastoid is used instead.
+ 
+ * MySQL uses ``localhost`` as the default host, and the empty string
+   as the default password.
+ 
+ * Added functions for use with queries: `ISNULL`, `ISNOTNULL`.  ``==`` 
+   and ``!=`` can be used with None, and is translated into `ISNULL`, 
+   `ISNOTNULL`.
+ 
+ * Classes can be part of a specific registry.  Since classes are 
+   referred to by name in several places, the names have to be unique.
+   This can be problematic, so you can add a class variable `_registry`,
+   the value of which should be a string.  Classes references are 
+   assumed to be inside that registry, and class names need only be
+   unique among classes in that registry.
+ 
+ * ``SomeClass.select()`` selects all, instead of using 
+   ``SomeClass.select('all')``.  You can also use None instead of
+   ``'all'``.
+ 
+ * Trying to fetch non-existent objects raises `SQLObjectNotFound`,
+   which is a subclass of the builtin exception `LookupError`.
+   This may not be raised if `_cacheValues` is False and you use
+   the ID to fetch an object (but alternateID fetches will raise 
+   the exception in either case).
+ 
+ Col and Join
+ ~~~~~~~~~~~~
+ 
+ * `Join` constructors have an argument `orderBy`, which is the name
+   of a Python attribute to sort results by.  If not given, the 
+   appropriate class's `_defaultOrder` will be used.  None implies
+   no sorting (and ``orderBy=None`` will override `_defaultOrder`).
+ 
+ * `ForeignKey` class (subclass of `Col`), for somewhat easier/clearer
+   declaration of foreign keys.
+ 
+ * `Col` (and subclasses) can take a `sqlType` argument, which is used
+   in table definitions.  E.g., ``Col(sqlType="BOOLEAN")`` can be used
+   to create a ``BOOLEAN`` column, even though no `BooleanCol` exists.
+ 
+ * `alternateID` (a specifier for columns) implies ``NOT NULL``.  Also
+   implies ``UNIQUE``.
+ 
+ * `unique` (a specifier for columns) added.
+ 
+ * `DecimalCol` and `CurrencyCol` added.
+ 
+ * `EnumCol` uses constraints on Postgres (if you use `createTable`).
+ 
+ Bugs
+ ----
+ 
+ * `DateTimeCol` uses ``TIMESTAMP`` for Postgres.  Note that the
+   Python type name is used for column names, not necessarily the
+   SQL standard name.
+ 
+ * Foreign key column names are slightly more permissive.  They still
+   need to end in ``id``, but it's case insensitive.
+ 
+ * _defaultOrder should be the python attribute's name, not the database
+   name.
+ 
+ * SomeClass.q.colName uses proper Python attributes for colName, and
+   proper database names when executed in the database.
+ 
+ * SQLite select results back to being proper iterator.
+ 
+ * SomeClass.q.colName now does proper translation to database names,
+   using dbName, etc., instead of being entirely algorithm-driven.
+ 
+ * Raise `TypeError` if you pass an unknown argument to the `new` 
+   method.
+ 
+ * You can override the _get_* or _set_* version of a property without
+   overriding the other.
+ 
+ * Python 2.3 compatible.
+ 
+ * Trying to use ``Col('id')`` or ``id = Col()`` will raise an 
+   exception, instead of just acting funky.
+ 
+ Internal
+ --------
+ 
+ * `Col` class separated into `Col` and `SOCol` (and same for all other
+   `*Col` classes).  `Col` defines a column, `SOCol` is that definition
+   bound to a particular SQLObject class.
+ 
+ * Instance variable ``_SO_columns`` holds the `SOCol` instances.
+ 
  SQLObject 0.3
  =============