Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
193 lines (139 sloc) 7.47 KB
Most Important API Changes
Those are mentioned here as are not backward compatible.
I want the API to be stable and consistent in the next release and later,
so I do all the big changes now (I would have to do them at some time anyway).
M2Crypto dependency dropped in favor of the 'ssl' module from the
standard Python library. TLS API has been changed a bit: certificate
verification callback now should expect one argument only (a dictionary
with certificate information)
Python 2.6 is now _required!
Interface API for better externalisation of various components. First
introduced to the Client classes -- one may create different classes
to handle different stanza types and namespaces, annotate them with
interfaces implemented (IFeaturesProvider, IPresenceHandlersProvider,
IMessageHandlersProvider or IIqHandlersProvider) and list their
instances in a Client object's interface_providers attribute.
See the example to see how to use that.
Exception handling improvements, part one.
All PyXMPP-specific exceptions moved to pyxmpp.exceptions module. Some exceptions
have been removed (those which were used where some standard exception, like ValueError,
would be a better choice), the most important omission is StanzaError exception.
ProtocolError exception with some derivatives added -- these are raised when
an error is detected in a stanza (received) processed. These exceptions
will be handled internally by PyXMPP some day (automatically
<bad-request/> or similar XMPP error will be raised).
CachedPropertyObject class removed and its usage in pyxmpp.jabber.disco
Now all the DiscoItem/DiscoInfo/DiscoItems attributes are regular properties
calling set_*, get_* funtions on every access.
The old cached properties were giving no speed gain and only complicated things.
Usage of non-unicode strings in PyXMPP API is deprecated. No
no implicit conversion is made where utf-8 string would previously be
accepted (e.g. JID constructor). Sometimes deprecation warning will be
raised when string is used instead of unicode.
"common_doc", "common_root", and "common_ns" can no longer be imported
from the "stanza" module. They were moved to the "xmlextra" module.
Minor change: now "disco_info" and "disco_items" attributes
of pyxmpp.jabber.client and pyxmpp.jabberd.component are initialized
in the constructors of those classes. Those __init__() methods now
accept "disco_name", "disco_category" and "disco_type" arguments
to set up the entity identity. Also register_feature() and
unregister_feature() methods were added for managing the feature
list in .disco_info.
Continuation of the big API unification.
All attribute and parameter names "node", relating to XML node have
been renamed to "xmlnode". The most important change is `Stanza.node` renamed
to `Stanza.xmlnode`.
Roster.items(), Roster.groups(), Roster.items_by_name(), Roster.items_by_group(),
Roser.items_by_jid() renamed to: Roster.get_items(), Roster.get_groups(),
Roster.get_items_by_name(), Roster.get_items_by_group(), Roster.get_item_by_jid()
Keys of Roster.items_dict are now JIDs, not unicode.
More .as_xml() methods unified. To reuse most of the code needed two
new virtual classes were added: pyxmpp.objects.StanzaPayloadObject
and pyxmpp.objects.StanzaPayloadWrapperObject. Objects providing .as_xml()
methods may be used directly as argument to Stanza.set_content() and
Stanza.add_content() methods.
Big API unification started.
jabber.vcard.VCard and jabber.delay.Delay
classes' method as_xml accepts now "parent" and "doc" arguments in
that order. Argument interpretation is also unified. All other similar
objects will have the add_xml() with the same signature soon.
Classes in jabber.disco module were modified heavily, so all the
getter are named get_*, all the setters set_* and all the interesting
properties may be accessed as attributes which also adds some caching.
Other classes, if they don't use that get_*/set_* naming, will be
modified in similar way soon.
There was a design flaw in PyXMPP from the very beginning, which caused
that many unnecessary modules from PyXMPP package (and subpackages,
when they were used) were imported even when only one simple module was
used. That was because pyxmpp imported all the useful names from
submodules. That was a problem (unnecessarily long startup time
sometimes), but it was also quite convenient.
To resolve the problem those imports were removed from __init__
modules, so importing a package doesn't cause any other imports now.
To improve backward compatibility and keep the convenience of the old
behavior "all" modules were added to "pyxmpp", "pyxmpp.jabber" and
"pyxmpp.jabber" packages.
If your application was broken by that change just import "pyxmpp.all"
(and/or "pyxmpp.jabber.all", "pyxmpp.jabberd.all" if you use them)
there -- you need to do it once per application (no need to change
every module). After that everything should work as before.
If you use only small part of the API and don't want to import unused
modules import names like "JID" or "Stanza" directly from modules that
define them (e.g.: 'import JID from pyxmpp.jid').
dnspython ( is now used for resolving DNS
names. Please note, that because of a conflict between dnspython and
old PyXMPP DNS implementation you must clean up after old PyXMPP
installation and do 'make clean' before building PyXMPP.
Stanza, Message, Iq and Presence constructors arguments have been
changed again. "typ" and "sid" were really stupid and ugly.
Now Stanza (derived classes) constructor keyword parameters are:
from_jid, to_jid, stanza_type, stanza_id
I hope this will never change again, at least not after the next
official release. You may update your application code using
"" script.
Stanza, Message, Iq and Presence constructors arguments have been
changed so build-ins "type" and "id" are not redefined. So the "type"
argument has been changed to "typ" and the "id" argument to "sid"
(stanza id).
Stream.data_in and Stream.data_out callbacks removed. Data sent and
received is now logged via 'logging' module to 'pyxmpp.Stream.out' and
'' loggers. The raw data is available for logging
handlers as the first element of 'args' attribute of the log record
All debug messages are passed to the standard python 'logging' module.
There is no debug() methods in PyXMPP classes any more.
Python 2.2 support is gone. Compliant XMPP implementation
requires stringprep and IDN support. Python 2.3 provides both,
Python 2.2 none. Maintaining separete stringprep and IDN
implementations for use with Python 2.2 is IMHO not worth the effort
Roster and RosterItems classes rewritten. Now they are not wrapper
around roster XML node any more. Old code was complicated, slow,
and not standard compliant (ingored stringprep profiles).
Most important changes:
- no `node` attribute in Roster and RosterItem
- RosterItem constructor doesn't take `roster` argument any more
- `jid`, `ask`, `subscription`, `name` and `groups` are now attributes,
not methods, of `RosterItem`
- `add_group`, `rm_group`, etc. methods of `RosterItem` are gone. Use
list operations on `groups` attribute now.
- inline documentation included
vi: spell spelllang=en