[Pkg-mpd-commits] [python-mpd] 177/262: doc: provides a new porting doc to explain API breakage

[Simon McVittie]

This is an automated email from the git hooks/post-receive script.

smcv pushed a commit to branch upstream
in repository python-mpd.

commit fcb68084650bf2af739dfe25346ae6d9b40f3ffc
Author: Jonathan Ballet <jon at multani.info>
Date:   Sat Jan 5 22:02:21 2013 +0800

    doc: provides a new porting doc to explain API breakage
---
 PORTING.txt | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/PORTING.txt b/PORTING.txt
new file mode 100644
index 0000000..64b4c78
--- /dev/null
+++ b/PORTING.txt
@@ -0,0 +1,44 @@
+=============
+Porting guide
+=============
+
+Until the versions 0.4.x, `python-mpd2`_ was a drop-in replacement for application
+which were using the original `python-mpd`_. That is, you could just replace the
+package's content of the latter one by the former one, and *things should just
+work*.
+
+However, starting from version 0.5, `python-mpd2`_ provides enhanced features
+which are *NOT* backward compatibles with the original `python-mpd`_ package.
+This goal of this document is to explains the differences the releases and if it
+makes sense, how to migrate from one version to another.
+
+
+Stickers API
+============
+
+When fetching stickers, `python-mpd2`_ used to return mostly the raw results MPD
+was providing::
+
+    >>> client.sticker_get('song', 'foo.mp3', 'my-sticker')
+    'my-sticker=some value'
+    >>> client.sticker_list('song', 'foo.mp3')
+    ['my-sticker=some value', 'foo=bar']
+
+Starting from version 0.5, `python-mpd2`_ provides a higher-level representation
+of the stickers' content::
+
+    >>> client.sticker_get('song', 'foo.mp3', 'my-sticker')
+    'some value'
+    >>> client.sticker_list('song', 'foo.mp3')
+    {'my-sticker': 'some value', 'foo': 'bar'}
+
+This removes the burden from the application to do the interpretation of the
+stickers' content by itself.
+
+.. versionadded:: 0.5
+
+
+.. _python-mpd: http://jatreuman.indefero.net/p/python-mpd/
+.. _python-mpd2: https://github.com/Mic92/python-mpd2/
+
+.. vim:ft=rst

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-mpd/python-mpd.git