*************************************************************************
itools 0.60.0
*************************************************************************

These upgrade notes may not be complete. Thanks to report any problem you
find.

New Dependencies
================

Now Python 2.6 is required.  For compiling the C extensions, you need
pkg-config (tested with version 0.23).

For indexing office documents, you need libraries and Python packages. See
README.txt for details.


Imports
=======

See the table below for the imports to update.

  Before (alphabetical order)    Now
  ----------------------------   ---------------------------
  handlers.Database              handlers.RWDatabase
  handlers.merge_dicts           core.merge_dicts
  handlers.Python                python.Python
  handlers.SafeDatabase          ** REPLACED **
  isetup.ArchiveNotSupported     pkg.ArchiveNotSupported
  isetup.download                pkg.download
  isetup.EXTENSIONS              pkg.EXTENSIONS
  isetup.get_installed_info      pkg.get_installed_info
  isetup.get_package_version     ** NOT EXPORTED **
  isetup.PACKAGES_DB             ** NOT EXPORTED **
  isetup.packages_infos          pkg.packages_infos
  isetup.parse_package_name      pkg.parse_package_name
  isetup.PKGINFOFile             pkg.PKGINFOFile
  isetup.RFC822File              ** NOT EXPORTED **
  isetup.SetupFile               ** NOT EXPORTED **
  utils.become_daemon            core.become_daemon
  utils.DEFAULT_REPOSITORY       pkg.DEFAULT_REPOSITORY
  utils.freeze                   core.freeze
  utils.frozendict               core.frozendict
  utils.frozenlist               core.frozenlist
  utils.get_abspath              core.get_abspath
  utils.get_time_spent           core.get_time_spent
  utils.get_version              core.get_version
  utils.setup                    pkg.setup
  utils.vmsize                   core.vmsize
  xml.MSExcel                    office.MSExcel
  xml.MSPowerPoint               office.MSPowerPoint
  xml.MSWord                     office.MSWord
  xml.RTF                        office.RTF
  xml.translate                  xmlfile.translate
  xml.XMLFile                    xmlfile.XMLFile


itools.csv
==========

Due to the changes with xapian (cf itools.xapian) the "schema" for a CSVFile
and the "record_schema" for a Table are modified:

  # Before
  class Foo(CSVFile):

      schema = {'name': String(index='keyword')}
      columns = ['name']

  # Now
  class Foo(CSVFile):

      schema = {'name': String(is_indexed=True)}
      columns = ['name']

And it is the same thing with Table, by example:

  # Before
  class Foo(Table):

      record_schema = {'name': String(index='keyword')}

  # Now
  class Foo(Table):

      record_schema = {'name': String(is_indexed=True)}


itools.datatypes
================

(1) Now the 'URI' datatype returns a string (instead of a uri reference
object).


itools.gettext
==============

Now itools.gettext uses the new formatted strings introduced in Python 2.6:

  # Before
  MSG('hello $name')

  # Now
  MSG('hello {name}')


itools.git
==========

Now the 'get_metadata' function returns all the data from the commit, not
just the committer's name and time.


itools.handlers
===============

(1) Now 'handler.uri' is a string (before it was a 'itools.uri.Reference'
object).  And the public API only takes strings.

(2) The 'SafeDatabase' class has been removed.  It has been replaced by
the new 'GitDatabase' class, which offers the same functionality (atomic
transactions) and more (versioning).

(3) The database API has changed a little:

  Before                          Now
  ------------------------------  ------------------------------
  ReadOnlyDatabase.add_to_cache   ReadOnlyDatabase.push_handler
  ReadOnlyDatabase.set_use_cache  ** REMOVED **


itools.pkg
==========

The API of itools.pkg (formerly known as 'itools.isetup') has changed a
little:

  Before                          Now
  ------------------------------  ------------------------------
  Dist(location)                  Bundle(location)


itools.uri
==========

(1) The 'get_absolute_reference' and 'get_absolute_reference2' functions
have been removed, since itools.vfs already provides this feature, but much
faster:

  # Before
  from itools.uri import get_absolute_reference, get_absolute_reference2
  uri1 = get_absolute_reference(ref1)
  uri2 = get_absolute_reference2(ref2)

  # Now
  from itools.uri import get_reference
  from itools.vfs import cwd
  uri1 = get_reference(cwd.get_uri(ref1))
  uri2 = get_reference(cwd.get_uri(ref2))

Both 'get_absolute_reference' and 'get_absolute_reference2' behaved the
same, except when the optional parameter 'base' was passed, a feature
rarely used.

(2) The 'get_cwd' function has been removed:

  # Before
  from itools.uri import get_cwd
  uri = get_cwd()

  # Now
  from itools.uri import get_reference
  from itools.vfs import cwd
  uri = get_reference(cwd.get_uri())

(3) The 'Segment' and 'Authority' classes have been removed.  Now both path
segments and URI authorities are represented internally as plain strings.

Use the new functional API to parse them.

(4) There is a new functional API that should be used when possible instead
of the old, but still maintained, OO API.  For instance:

  # Before
  from itools.uri import get_reference
  base = get_reference('http://www.hforge.org/itools/')
  ref = get_reference('../ikaaro/')
  uri = base.resolve(ref)
  uri = str(uri)

  # Now
  from itools.uri import resolve_uri
  base = 'http://www.hforge.org/itools/'
  ref = '../ikaaro/'
  uri = resolve_uri(base, ref)


itools.vfs
==========

The Virtual File System does not take anymore itools.uri.Reference objects:

  # Before
  from itools import vfs
  vfs.XXX(uri)

  # Now
  from itools import vfs
  vfs.XXX(str(uri))


itools.web
==========

Many small changes have been done to the Web server.  Most are internal
so there should be little impact in applications.

(1) The 'has_resource' method has been removed.  Use instead the method
'get_resource' with the new argument 'soft' set to True:

  # Before
  if here.has_resource(path):
      ...
  else:
      ...

  # Now
  resource = here.get_resource(path, soft=True)
  if resource is None:
      ...
  else:
      ...

(2) The method 'del_resource' also takes the 'soft' parameter, it simplifies
some patterns:

  # Before
  if here.has_resource(path):
      here.del_resource(path)

  # Now
  here.del_resource(path, soft=True)


(3) The 'context.redirect' method, which was already obsolete, has been
removed.  Return a URI instead.


itools.xapian
=============

(1) Several changes have been done to the way the fields to be indexed are
defined:

- The <Field> classes have been removed, now datatypes are used.
- The 'CatalogAware.get_catalog_fields' method has been removed, now the
  definition of the fields to be indexed is passed to the constructors.
- Now by default the fields are not indexed.
- The new 'is_key_field' variable says which field is the key in the catalog.

For example:

  # Before
  from itools.xapian import IntegerField, TextField
  class MyResource(CatalogAware):
      def get_catalog_fields(self):
          return [
              IntegerField('id', is_stored=True),
              TextField('name')]

  catalog = make_catalog('my_catalog')

  # Now
  from itools.datatypes import Integer, Unicode
  fields = {
      'id': Integer(is_key_field=True, is_stored=True, is_indexed=True),
      'name': Unicode(is_indexed=True)}
  catalog = make_catalog('my_database', fields)

(2) When searching now we pass de-serialized (typed) valuse. For example:

  Before                          Now
  ------------------------------  ------------------------------
  PhraseQuery('is_folder', '1')   PhraseQuery('is_folder', True)

