During the 0.x development cycle of kaa.base, the API has changed several
times.  This document describes incompatible API changes introduced in each
released version.

We are quickly approaching a 1.0 release.  After 1.0, the API will not change
in any incompatible ways throughout the 1.0.x lifecycle.  Minor releases (1.x)
may introduce incompatible API changes, but we will follow the standard Python
approach of warning when an API usage is deprecated and provide a migration
path (similar to that of Python's __future__ module).

Compatible API changes (new methods and properties, or addition of kwargs to
existing methods) may be introduced at any time.


Changes for 0.6.0
-----------------

1. Callback.(set|get)_ignore_caller_args() and (set|get)_user_args_first() are
   replaced by read/write properties named ignore_caller_args and
   user_args_first respectively.

2. Callback.get_user_args() has changed to an internal method called 
   _get_user_args()

3. Timer.get_interval() is now a read-only property called 'interval'

4. active() method changed to read-only property called 'active' for the
   following classes: Timer, WeakTimer, OneShotTimer, WeakOneShotTimer,
   ThreadInProgress, Event.

5. WeakCallback.set_weakref_destroyed_cb() is now a read/write property
   called 'weakref_destroyed_cb'

6. CoroutineInProgress.set_interval() is now a read/write property called
   'interval'

7. ThreadCallback.wait_on_exit() is now a read/write property called
   'wait_on_exit'

8. Database.add_object() has been renamed to add(); 
   Database.update_object() has been renamed to update()

9. config.Group.get_variables() is now a read-only property called 'variables';
   config.Group.get_parent() is now a read-only property called 'parent'.

10. The (nested) InProgress.Progress class has been pulled out from InProgress
    and renamed to InProgressStatus.

11. kaa.Process has been completely rewritten:
       a. signals['stdout'] -> stdout.signals['readline']
       b. signals['raw-stdout'] -> stdout.signals['read']
       c. signals['stderr'] -> stderr.signals['readline']
       d. signals['raw-stderr'] -> stderr.signals['read']
       e. signals['completed'] -> signals['finished'] or signals['exited']
          depending on the desired behaviour (see docs).
       f. is_alive() -> alive property
       g. stop() is now a coroutine and finishes when the process is dead
       h. set_stop_command() -> read/write property 'stop_command'
       i. close_stdin() -> stdin.close()
       k. get_pid() -> read-only property 'pid'
       l. 'readline' signal now only delimits on \n by default, as opposed to
          both \r _or_ \n like the old class.  To delimit on either, set the
          delimiter property to ['\r', '\n']

   Several new methods and properties are available now.  Notably, read() and
   readline(), which are coroutines.  See documentation for more details.


12. InProgressCallback does not support a signal as argument anymore,
    yield inprogress(signal) instead.

13. @kaa.coroutine does not support the keyword synchronize anymore,
    use policy=kaa.POLICY_SYNCHRONIZED instead.

14. InProgressSignals and InProgressList classes have been replaced with
    InProgressAny and InProgressAll classes.  The latter are not direct
    translations but similar functionality can be obtained.

15. Semantics of the 'step' signal has changed: rather than being more like
    an idle signal, it now emits only for each iteration of the main loop.
    Therefore if there is nothing for the mainloop to do, the 'step' signal
    will not emit.



Changes for 0.4.0
-----------------

1. MainThreadCallback.set_async() is removed.  Calling a
   MainThreadCallback will return an InProgress object, and the
   new approach now is to wait() on this InProgress.

2. Several decorators renamed:
      @kaa.execute_in_timer  -->  @kaa.timed
      @kaa.execute_in_thread  -->  @kaa.threaded
      @kaa.execute_in_mainloop  --> @kaa.threaded(kaa.MAINTHREAD)
      @kaa.yield_execution  -->  @kaa.coroutine

   @kaa.timed also changed the parameter order and name. It is now
   interval, timer (default Timer) and policy (default
   POLICY_RESTART).

3. SocketDispatcher and WeakSocketDispatcher are renamed to IOMonitor
   and WeakIOMonitor.

4. Rename YieldContinue to NotFinished
   Rename YieldCallback to InProgressCallback
   Remove YieldFunction from the API, the class is now only for
   internal use and may change without further notice.



Changes for 0.3.0
-----------------

1. Rename kaa.notifier mainloop control:
   kaa.notifier.init() is kaa.main.select_notifier()
   kaa.notifier.loop() and kaa.main() is now kaa.main.run()
   kaa.notifier.step() is kaa.main.step()
   kaa.notifier.shutdown() is kaa.main.stop()
   kaa.notifier.running is kaa.main.is_running()
   kaa.notifier.signals (shutdown/step) are now kaa.main.signals

   kaa.main can be accessed by importing kaa, you can NOT import
   kaa.main directly.

2. Move kaa.notifier classes and functions into the kaa namespace.
   E.g. kaa.notifier.Timer is now kaa.Timer. No part of the code
   should use anything from kaa.notifier.

   Note: Exception for this is kaa.notifier.url right now

3. Renamed ThreadCallback to NamedThreadCallback and make the first
   paramater in __init__ the thread information (name or list of name
   and priority). The register function will be changed to __call__.
   The NamedThreadCallback is not InProgress object anymore, it is a
   Callback. In most cases ThreadCallback was not used directly so
   this API change should not break some code.

4. Renamed Thread to ThreadCallback. The class has no signals anymore
   and the start function is now __call__ and it will return an
   InProgress object.

5. Rename exception_handler in InProgress into exception and the
   exception callback function to throw. Add a convenience function
   connect_both. The member variable is_finished is now a function.

6. yield_execution decorator: lock kwarg was renamed to synchronize

7. All exception handlers now take three arguments (instead of one):
   exception type, exception value, traceback.

8. yield_execution now always returns an InProgress object. This
   InProgress object may already be finished. Using yield on a
   finished object will return without waiting. For Python 2.5 the
   yield also returns the value or can raise an exception.


