1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
Overview
--------
This is PyXMMS, a Python interface to XMMS (the X MultiMedia System), an audio
and video player for Unix-like platforms.
As of version 2.00, PyXMMS consists of two components:
- a set of Python bindings for all the xmms_remote_* functions accessible
through the libxmms library (which comes with XMMS), plus a few
higher-level functions that I (Florent Rougon) find useful;
- a Python wrapper around the functions for configuration file management
in libxmms.
In short, the first component allows you to control XMMS from a Python program
while the second component is for Python programs that need to manage the XMMS
main configuration file (reading or writing).
These two components are accessible by means of the xmms.control and
xmms.config modules respectively.
License
-------
PyXMMS is free software, licensed under the GNU GPL.
Documentation
-------------
PyXMMS is fully documented through Python docstrings.
The easiest way to browse the PyXMMS documentation is to go through the
following steps (as a normal user, from the PyXMMS base directory):
- build PyXMMS:
python ./setup.py build
If this step fails (perhaps you are missing required libraries, or your
Python version is not supported), read the INSTALL file.
- build the documentation (this uses the pydoc module):
python ./build-documentation.py
Then, you'll have all the documentation for the Python version used in these
steps in the "doc" directory (see Compatibility below).
Otherwise, you can browse the documentation in an interactive Python session
if you have already installed PyXMMS (see the INSTALL file) or if you have
built PyXMMS and are in the appropriate directory for your platform and Python
version (for instance, build/lib.linux-i686-2.3). Then, if you are interested
in "item" (a function or class name, or the module name) from the "module"
module (xmms.control or xmms.config, for instance):
- if you are at a Python 2.1 command prompt (and probably any earlier
version with pydoc installed), type:
import pydoc, module; pydoc.help(item)
- if you are at a Python 2.2-or-above command prompt, type:
import module; help(item)
If PyXMMS is installed, you can also read the documentation with a Web browser
if you use pydoc as an HTTP server. For instance:
pydoc -p 1234 (does not need root privileges if
the chosen port is greater than 1024)
will start an HTTP server listening on the 1234 port and serving the
documentation for your whole Python installation. Then, you just have to point
your browser to http://localhost:1234/
See the pydoc module's documentation for more information.
Compatibility
-------------
As explained at the top of this file, versions 2.?? of PyXMMS contain two
components:
- one to control XMMS, whose main module is xmms.control
- one to manage the main configuration file for XMMS, whose main module is
xmms.config
The 'control' component has been tested with Python 2.1 through 2.3 (it
*might* work with versions earlier than 2.1).
The 'config' component, however, uses "new-style classes" and therefore
requires Python 2.2 or above. It has been tested with Python 2.2 and 2.3 at
the time of this writing.
Since building the documentation relies on pydoc and pydoc imports the modules
to generate documentation for, you cannot build the documentation for the
'config' component with Python 2.1 or earlier. build-documentation.py will
handle this situation correctly, you just won't have find doc/xmms.config.html
after you run build-documentation.py with Python 2.1 or earlier.
Note: running "setup.py build" with various Python versions will build PyXMMS
for these versions and store the results in
build/lib.<platform>-<python version> so that those builds don't
overwrite each other. However, build-documentation.py will (require a
complete build for the Python version it is running on and) just store
the built documentation in the "doc" directory. So, if you first ran
build-documentation.py with Python 2.2 or above, you obtained a
doc/xmms.config.html file, but if you run it again with Python 2.1, this
file will be erased and not regenerated.
Upgrading from PyXMMS 1 to PyXMMS 2
-----------------------------------
A few changes have been made to the control component between PyXMMS 1.07 and
PyXMMS 2.00, so you should read the following paragraphs so that you use the
new API for new code and update old code to conform to it. However, *all
changes are backward-compatible for now* (except the cosmetic issue with
exception messages---see below) and I will not drop support for the old API
before the beginning of 2005 unless *really* necessary.
Also, talking about a "new API" is a bit of an overstatement. Here are the
changes:
- Due to the addition of the 'config' component, xmms was made into a
package, containing two main modules, xmms.control and xmms.config.
Therefore all the stuff that was under the xmms module in PyXMMS 1 (e.g.,
xmms.play) is now under xmms.control (e.g., xmms.control.play). You will
still find these things under xmms to preserve compatibility, but should
not rely on this in the long term. Don't forget to import xmms.control!
- For consistency with other Python modules, 'PyXMMSGenericException' is now
an alias for 'error', which should be referred to as xmms.error or
xmms.common.error (both are correct; I would suggest you use xmms.error if
you have no strong preference).
- The complete_message method of PyXMMS exceptions (subclasses of 'error')
does not add a full stop at the end of the message embedded in an
exception instance any more, so that your program can decide whether it
wants the full stop or not. This is the only backward-incompatible change
between PyXMMS 1.07 and PyXMMS 2.00.
Home page
---------
PyXMMS' home page is currently (2005/02/07) at:
http://people.via.ecp.fr/~flo/
|
