]> kaliko git repositories - python-musicpd.git/blob - musicpd.py
Bump copyright year
[python-musicpd.git] / musicpd.py
1 # SPDX-FileCopyrightText: 2012-2023  kaliko <kaliko@azylum.org>
2 # SPDX-FileCopyrightText: 2021       Wonko der Verständige <wonko@hanstool.org>
3 # SPDX-FileCopyrightText: 2019       Naglis Jonaitis <naglis@mailbox.org>
4 # SPDX-FileCopyrightText: 2019       Bart Van Loon <bbb@bbbart.be>
5 # SPDX-FileCopyrightText: 2008-2010  J. Alexander Treuman <jat@spatialrift.net>
6 # SPDX-License-Identifier: LGPL-3.0-or-later
7 """python-musicpd: Python Music Player Daemon client library"""
8
9
10 import socket
11 import os
12
13 from functools import wraps
14 # Type hint for python <= 3.8
15 from typing import Any, Dict, List, Tuple
16 from typing import Literal, Optional, Union
17
18 HELLO_PREFIX = "OK MPD "
19 ERROR_PREFIX = "ACK "
20 SUCCESS = "OK"
21 NEXT = "list_OK"
22 VERSION = '0.9.0b0'
23 #: Seconds before a connection attempt times out
24 #: (overriden by MPD_TIMEOUT env. var.)
25 CONNECTION_TIMEOUT: int = 30
26 #: Socket timeout in second (Default is None for no timeout)
27 SOCKET_TIMEOUT: Union[int, None] = None
28
29
30 def iterator_wrapper(func):
31     """Decorator handling iterate option"""
32     @wraps(func)
33     def decorated_function(instance, *args, **kwargs):
34         generator = func(instance, *args, **kwargs)
35         if not instance.iterate:
36             return list(generator)
37         instance._iterating = True
38
39         def iterator(gen):
40             try:
41                 for item in gen:
42                     yield item
43             finally:
44                 instance._iterating = False
45         return iterator(generator)
46     return decorated_function
47
48
49 class MPDError(Exception):
50     pass
51
52
53 class ConnectionError(MPDError):
54     pass
55
56
57 class ProtocolError(MPDError):
58     pass
59
60
61 class CommandError(MPDError):
62     pass
63
64
65 class CommandListError(MPDError):
66     pass
67
68
69 class PendingCommandError(MPDError):
70     pass
71
72
73 class IteratingError(MPDError):
74     pass
75
76
77 class Range:
78
79     def __init__(self, tpl: Tuple[int]):
80         self.tpl = tpl
81         self._check()
82
83     def __str__(self):
84         if len(self.tpl) == 0:
85             return ':'
86         if len(self.tpl) == 1:
87             return '{0}:'.format(self.tpl[0])
88         return '{0[0]}:{0[1]}'.format(self.tpl)
89
90     def __repr__(self):
91         return 'Range({0})'.format(self.tpl)
92
93     def _check(self):
94         if not isinstance(self.tpl, tuple):
95             raise CommandError('Wrong type, provide a tuple')
96         if len(self.tpl) not in [0, 1, 2]:
97             raise CommandError('length not in [0, 1, 2]')
98         for index in self.tpl:
99             try:
100                 index = int(index)
101             except (TypeError, ValueError) as err:
102                 raise CommandError('Not a tuple of int') from err
103
104
105 class _NotConnected:
106
107     def __getattr__(self, attr):
108         return self._dummy
109
110     def _dummy(self, *args):
111         raise ConnectionError("Not connected")
112
113
114 class MPDClient:
115     """MPDClient instance will look for ``MPD_HOST``/``MPD_PORT``/``XDG_RUNTIME_DIR`` environment
116     variables and set instance attribute ``host``, ``port`` and ``pwd``
117     accordingly. Regarding ``MPD_HOST`` format to expose password refer
118     MPD client manual :manpage:`mpc (1)`.
119
120     Then :py:obj:`musicpd.MPDClient.connect` will use ``host`` and ``port`` as defaults if not provided as args.
121
122     Cf. :py:obj:`musicpd.MPDClient.connect` for details.
123
124     >>> from os import environ
125     >>> environ['MPD_HOST'] = 'pass@mpdhost'
126     >>> cli = musicpd.MPDClient()
127     >>> cli.pwd == environ['MPD_HOST'].split('@')[0]
128     True
129     >>> cli.host == environ['MPD_HOST'].split('@')[1]
130     True
131     >>> cli.connect() # will use host/port as set in MPD_HOST/MPD_PORT
132
133     :ivar str host: host used with the current connection
134     :ivar str,int port: port used with the current connection
135     :ivar str pwd: password detected in ``MPD_HOST`` environment variable
136
137     .. warning:: Instance attribute host/port/pwd
138
139       While :py:attr:`musicpd.MPDClient().host` and
140       :py:attr:`musicpd.MPDClient().port` keep track of current connection
141       host and port, :py:attr:`musicpd.MPDClient().pwd` is set once with
142       password extracted from environment variable.
143       Calling :py:meth:`musicpd.MPDClient().password()` with a new password
144       won't update :py:attr:`musicpd.MPDClient().pwd` value.
145
146       Moreover, :py:attr:`musicpd.MPDClient().pwd` is only an helper attribute
147       exposing password extracted from ``MPD_HOST`` environment variable, it
148       will not be used as default value for the :py:meth:`password` method
149     """
150
151     def __init__(self) -> None:
152         self.iterate: bool = False
153         #: Socket timeout value in seconds
154         self._socket_timeout = SOCKET_TIMEOUT
155         #: Current connection timeout value, defaults to
156         #: :py:obj:`CONNECTION_TIMEOUT` or env. var. ``MPD_TIMEOUT`` if provided
157         self.mpd_timeout: Union[None,int] = None
158         self._reset()
159         self._commands = {
160             # Status Commands
161             "clearerror":         self._fetch_nothing,
162             "currentsong":        self._fetch_object,
163             "idle":               self._fetch_list,
164             #"noidle":             None,
165             "status":             self._fetch_object,
166             "stats":              self._fetch_object,
167             # Playback Option Commands
168             "consume":            self._fetch_nothing,
169             "crossfade":          self._fetch_nothing,
170             "mixrampdb":          self._fetch_nothing,
171             "mixrampdelay":       self._fetch_nothing,
172             "random":             self._fetch_nothing,
173             "repeat":             self._fetch_nothing,
174             "setvol":             self._fetch_nothing,
175             "getvol":             self._fetch_object,
176             "single":             self._fetch_nothing,
177             "replay_gain_mode":   self._fetch_nothing,
178             "replay_gain_status": self._fetch_item,
179             "volume":             self._fetch_nothing,
180             # Playback Control Commands
181             "next":               self._fetch_nothing,
182             "pause":              self._fetch_nothing,
183             "play":               self._fetch_nothing,
184             "playid":             self._fetch_nothing,
185             "previous":           self._fetch_nothing,
186             "seek":               self._fetch_nothing,
187             "seekid":             self._fetch_nothing,
188             "seekcur":            self._fetch_nothing,
189             "stop":               self._fetch_nothing,
190             # Queue Commands
191             "add":                self._fetch_nothing,
192             "addid":              self._fetch_item,
193             "clear":              self._fetch_nothing,
194             "delete":             self._fetch_nothing,
195             "deleteid":           self._fetch_nothing,
196             "move":               self._fetch_nothing,
197             "moveid":             self._fetch_nothing,
198             "playlist":           self._fetch_playlist,
199             "playlistfind":       self._fetch_songs,
200             "playlistid":         self._fetch_songs,
201             "playlistinfo":       self._fetch_songs,
202             "playlistsearch":     self._fetch_songs,
203             "plchanges":          self._fetch_songs,
204             "plchangesposid":     self._fetch_changes,
205             "prio":               self._fetch_nothing,
206             "prioid":             self._fetch_nothing,
207             "rangeid":            self._fetch_nothing,
208             "shuffle":            self._fetch_nothing,
209             "swap":               self._fetch_nothing,
210             "swapid":             self._fetch_nothing,
211             "addtagid":           self._fetch_nothing,
212             "cleartagid":         self._fetch_nothing,
213             # Stored Playlist Commands
214             "listplaylist":       self._fetch_list,
215             "listplaylistinfo":   self._fetch_songs,
216             "listplaylists":      self._fetch_playlists,
217             "load":               self._fetch_nothing,
218             "playlistadd":        self._fetch_nothing,
219             "playlistclear":      self._fetch_nothing,
220             "playlistdelete":     self._fetch_nothing,
221             "playlistmove":       self._fetch_nothing,
222             "rename":             self._fetch_nothing,
223             "rm":                 self._fetch_nothing,
224             "save":               self._fetch_nothing,
225             # Database Commands
226             "albumart":           self._fetch_composite,
227             "count":              self._fetch_object,
228             "getfingerprint":     self._fetch_object,
229             "find":               self._fetch_songs,
230             "findadd":            self._fetch_nothing,
231             "list":               self._fetch_list,
232             "listall":            self._fetch_database,
233             "listallinfo":        self._fetch_database,
234             "listfiles":          self._fetch_database,
235             "lsinfo":             self._fetch_database,
236             "readcomments":       self._fetch_object,
237             "readpicture":        self._fetch_composite,
238             "search":             self._fetch_songs,
239             "searchadd":          self._fetch_nothing,
240             "searchaddpl":        self._fetch_nothing,
241             "update":             self._fetch_item,
242             "rescan":             self._fetch_item,
243             # Mounts and neighbors
244             "mount":              self._fetch_nothing,
245             "unmount":            self._fetch_nothing,
246             "listmounts":         self._fetch_mounts,
247             "listneighbors":      self._fetch_neighbors,
248             # Sticker Commands
249             "sticker get":        self._fetch_item,
250             "sticker set":        self._fetch_nothing,
251             "sticker delete":     self._fetch_nothing,
252             "sticker list":       self._fetch_list,
253             "sticker find":       self._fetch_songs,
254             # Connection Commands
255             "close":              None,
256             "kill":               None,
257             "password":           self._fetch_nothing,
258             "ping":               self._fetch_nothing,
259             "binarylimit":        self._fetch_nothing,
260             "tagtypes":           self._fetch_list,
261             "tagtypes disable":   self._fetch_nothing,
262             "tagtypes enable":    self._fetch_nothing,
263             "tagtypes clear":     self._fetch_nothing,
264             "tagtypes all":       self._fetch_nothing,
265             # Partition Commands
266             "partition":          self._fetch_nothing,
267             "listpartitions":     self._fetch_list,
268             "newpartition":       self._fetch_nothing,
269             "delpartition":       self._fetch_nothing,
270             "moveoutput":         self._fetch_nothing,
271             # Audio Output Commands
272             "disableoutput":      self._fetch_nothing,
273             "enableoutput":       self._fetch_nothing,
274             "toggleoutput":       self._fetch_nothing,
275             "outputs":            self._fetch_outputs,
276             "outputset":          self._fetch_nothing,
277             # Reflection Commands
278             "config":             self._fetch_object,
279             "commands":           self._fetch_list,
280             "notcommands":        self._fetch_list,
281             "urlhandlers":        self._fetch_list,
282             "decoders":           self._fetch_plugins,
283             # Client to Client
284             "subscribe":          self._fetch_nothing,
285             "unsubscribe":        self._fetch_nothing,
286             "channels":           self._fetch_list,
287             "readmessages":       self._fetch_messages,
288             "sendmessage":        self._fetch_nothing,
289         }
290         self._get_envvars()
291
292     def _get_envvars(self) -> None:
293         """
294         Retrieve MPD env. var. to overrides "localhost:6600"
295             Use MPD_HOST/MPD_PORT if set
296             else use MPD_HOST=${XDG_RUNTIME_DIR:-/run/}/mpd/socket if file exists
297         """
298         self.host: str = 'localhost'
299         self.pwd: Union[None, str] = None
300         self.port: Union[int,str] = os.getenv('MPD_PORT', '6600')
301         _host: str = os.getenv('MPD_HOST', '')
302         if _host:
303             # If password is set: MPD_HOST=pass@host
304             if '@' in _host:
305                 mpd_host_env = _host.split('@', 1)
306                 if mpd_host_env[0]:
307                     # A password is actually set
308                     self.pwd = mpd_host_env[0]
309                     if mpd_host_env[1]:
310                         self.host = mpd_host_env[1]
311                 elif mpd_host_env[1]:
312                     # No password set but leading @ is an abstract socket
313                     self.host = '@'+mpd_host_env[1]
314             else:
315                 # MPD_HOST is a plain host
316                 self.host = _host
317         else:
318             # Is socket there
319             xdg_runtime_dir = os.getenv('XDG_RUNTIME_DIR', '/run')
320             rundir = os.path.join(xdg_runtime_dir, 'mpd/socket')
321             if os.path.exists(rundir):
322                 self.host = rundir
323         _mpd_timeout = os.getenv('MPD_TIMEOUT', 'X')
324         if _mpd_timeout.isdigit():
325             self.mpd_timeout = int(_mpd_timeout)
326         else:  # Use CONNECTION_TIMEOUT as default even if MPD_TIMEOUT carries gargage
327             self.mpd_timeout = CONNECTION_TIMEOUT
328
329     def __getattr__(self, attr):
330         if attr == 'send_noidle':  # have send_noidle to cancel idle as well as noidle
331             return self.noidle()
332         if attr.startswith("send_"):
333             command = attr.replace("send_", "", 1)
334             wrapper = self._send
335         elif attr.startswith("fetch_"):
336             command = attr.replace("fetch_", "", 1)
337             wrapper = self._fetch
338         else:
339             command = attr
340             wrapper = self._execute
341         if command not in self._commands:
342             command = command.replace("_", " ")
343             if command not in self._commands:
344                 cls = self.__class__.__name__
345                 raise AttributeError(f"'{cls}' object has no attribute '{attr}'")
346         return lambda *args: wrapper(command, args)
347
348     def _send(self, command, args):
349         if self._command_list is not None:
350             raise CommandListError("Cannot use send_%s in a command list" %
351                                    command.replace(" ", "_"))
352         self._write_command(command, args)
353         retval = self._commands[command]
354         if retval is not None:
355             self._pending.append(command)
356
357     def _fetch(self, command, args=None):  # pylint: disable=unused-argument
358         cmd_fmt = command.replace(" ", "_")
359         if self._command_list is not None:
360             raise CommandListError(f"Cannot use fetch_{cmd_fmt} in a command list")
361         if self._iterating:
362             raise IteratingError(f"Cannot use fetch_{cmd_fmt} while iterating")
363         if not self._pending:
364             raise PendingCommandError("No pending commands to fetch")
365         if self._pending[0] != command:
366             raise PendingCommandError(f"'{command}' is not the currently pending command")
367         del self._pending[0]
368         retval = self._commands[command]
369         if callable(retval):
370             return retval()
371         return retval
372
373     def _execute(self, command, args):  # pylint: disable=unused-argument
374         if self._iterating:
375             raise IteratingError(f"Cannot execute '{command}' while iterating")
376         if self._pending:
377             raise PendingCommandError(f"Cannot execute '{command}' with pending commands")
378         retval = self._commands[command]
379         if self._command_list is not None:
380             if not callable(retval):
381                 raise CommandListError(f"'{command}' not allowed in command list")
382             self._write_command(command, args)
383             self._command_list.append(retval)
384         else:
385             self._write_command(command, args)
386             if callable(retval):
387                 return retval()
388             return retval
389         return None
390
391     def _write_line(self, line):
392         self._wfile.write(f"{line!s}\n")
393         self._wfile.flush()
394
395     def _write_command(self, command, args=None):
396         if args is None:
397             args = []
398         parts = [command]
399         for arg in args:
400             if isinstance(arg, tuple):
401                 parts.append('{0!s}'.format(Range(arg)))
402             else:
403                 parts.append('"%s"' % escape(str(arg)))
404         if '\n' in ' '.join(parts):
405             raise CommandError('new line found in the command!')
406         self._write_line(" ".join(parts))
407
408     def _read_binary(self, amount):
409         chunk = bytearray()
410         while amount > 0:
411             result = self._rbfile.read(amount)
412             if len(result) == 0:
413                 self.disconnect()
414                 raise ConnectionError("Connection lost while reading binary content")
415             chunk.extend(result)
416             amount -= len(result)
417         return bytes(chunk)
418
419     def _read_line(self, binary: Literal[True,False] = False):
420         if binary:
421             line = self._rbfile.readline().decode('utf-8')
422         else:
423             line = self._rfile.readline()
424         if not line.endswith("\n"):
425             self.disconnect()
426             raise ConnectionError("Connection lost while reading line")
427         line = line.rstrip("\n")
428         if line.startswith(ERROR_PREFIX):
429             error = line[len(ERROR_PREFIX):].strip()
430             raise CommandError(error)
431         if self._command_list is not None:
432             if line == NEXT:
433                 return None
434             if line == SUCCESS:
435                 raise ProtocolError(f"Got unexpected '{SUCCESS}'")
436         elif line == SUCCESS:
437             return None
438         return line
439
440     def _read_pair(self, separator: str, binary: Literal[True,False] = False):
441         line = self._read_line(binary=binary)
442         if line is None:
443             return None
444         pair = line.split(separator, 1)
445         if len(pair) < 2:
446             raise ProtocolError(f"Could not parse pair: '{line}'")
447         return pair
448
449     def _read_pairs(self, separator=": ", binary: Literal[True,False] =False):
450         pair = self._read_pair(separator, binary=binary)
451         while pair:
452             yield pair
453             pair = self._read_pair(separator, binary=binary)
454
455     def _read_list(self):
456         seen = None
457         for key, value in self._read_pairs():
458             if key != seen:
459                 if seen is not None:
460                     raise ProtocolError(f"Expected key '{seen}', got '{key}'")
461                 seen = key
462             yield value
463
464     def _read_playlist(self):
465         for _, value in self._read_pairs(":"):
466             yield value
467
468     def _read_objects(self, delimiters: Optional[List[str]] = None):
469         obj: Dict[str,Any] = {}
470         if delimiters is None:
471             delimiters = []
472         for key, value in self._read_pairs():
473             key = key.lower()
474             if obj:
475                 if key in delimiters:
476                     yield obj
477                     obj = {}
478                 elif key in obj:
479                     if not isinstance(obj[key], list):
480                         obj[key] = [obj[key], value]
481                     else:
482                         obj[key].append(value)
483                     continue
484             obj[key] = value
485         if obj:
486             yield obj
487
488     def _read_command_list(self):
489         try:
490             for retval in self._command_list:
491                 yield retval()
492         finally:
493             self._command_list = None
494         self._fetch_nothing()
495
496     def _fetch_nothing(self):
497         line = self._read_line()
498         if line is not None:
499             raise ProtocolError(f"Got unexpected return value: '{line}'")
500
501     def _fetch_item(self):
502         pairs = list(self._read_pairs())
503         if len(pairs) != 1:
504             return None
505         return pairs[0][1]
506
507     @iterator_wrapper
508     def _fetch_list(self):
509         return self._read_list()
510
511     @iterator_wrapper
512     def _fetch_playlist(self):
513         return self._read_playlist()
514
515     def _fetch_object(self):
516         objs = list(self._read_objects())
517         if not objs:
518             return {}
519         return objs[0]
520
521     @iterator_wrapper
522     def _fetch_objects(self, delimiters):
523         return self._read_objects(delimiters)
524
525     def _fetch_changes(self):
526         return self._fetch_objects(["cpos"])
527
528     def _fetch_songs(self):
529         return self._fetch_objects(["file"])
530
531     def _fetch_playlists(self):
532         return self._fetch_objects(["playlist"])
533
534     def _fetch_database(self):
535         return self._fetch_objects(["file", "directory", "playlist"])
536
537     def _fetch_outputs(self):
538         return self._fetch_objects(["outputid"])
539
540     def _fetch_plugins(self):
541         return self._fetch_objects(["plugin"])
542
543     def _fetch_messages(self):
544         return self._fetch_objects(["channel"])
545
546     def _fetch_mounts(self):
547         return self._fetch_objects(["mount"])
548
549     def _fetch_neighbors(self):
550         return self._fetch_objects(["neighbor"])
551
552     def _fetch_composite(self):
553         obj = {}
554         for key, value in self._read_pairs(binary=True):
555             key = key.lower()
556             obj[key] = value
557             if key == 'binary':
558                 break
559         if not obj:
560             # If the song file was recognized, but there is no picture, the
561             # response is successful, but is otherwise empty.
562             return obj
563         amount = int(obj['binary'])
564         try:
565             obj['data'] = self._read_binary(amount)
566         except IOError as err:
567             raise ConnectionError(f'Error reading binary content: {err}') from err
568         data_bytes = len(obj['data'])
569         if data_bytes != amount:  # can we ever get there?
570             raise ConnectionError('Error reading binary content: '
571                     f'Expects {amount}B, got {data_bytes}')
572         # Fetches trailing new line
573         self._read_line(binary=True)
574         # Fetches SUCCESS code
575         self._read_line(binary=True)
576         return obj
577
578     @iterator_wrapper
579     def _fetch_command_list(self):
580         return self._read_command_list()
581
582     def _hello(self):
583         line = self._rfile.readline()
584         if not line.endswith("\n"):
585             raise ConnectionError("Connection lost while reading MPD hello")
586         line = line.rstrip("\n")
587         if not line.startswith(HELLO_PREFIX):
588             raise ProtocolError(f"Got invalid MPD hello: '{line}'")
589         self.mpd_version = line[len(HELLO_PREFIX):].strip()
590
591     def _reset(self):
592         self.mpd_version = None
593         self._iterating = False
594         self._pending = []
595         self._command_list = None
596         self._sock = None
597         self._rfile = _NotConnected()
598         self._rbfile = _NotConnected()
599         self._wfile = _NotConnected()
600
601     def _connect_unix(self, path):
602         if not hasattr(socket, "AF_UNIX"):
603             raise ConnectionError("Unix domain sockets not supported on this platform")
604         # abstract socket
605         if path.startswith('@'):
606             path = '\0'+path[1:]
607         sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
608         sock.settimeout(self.mpd_timeout)
609         sock.connect(path)
610         sock.settimeout(self.socket_timeout)
611         return sock
612
613     def _connect_tcp(self, host, port):
614         try:
615             flags = socket.AI_ADDRCONFIG
616         except AttributeError:
617             flags = 0
618         err = None
619         for res in socket.getaddrinfo(host, port, socket.AF_UNSPEC,
620                                       socket.SOCK_STREAM, socket.IPPROTO_TCP,
621                                       flags):
622             af, socktype, proto, _, sa = res
623             sock = None
624             try:
625                 sock = socket.socket(af, socktype, proto)
626                 sock.settimeout(self.mpd_timeout)
627                 sock.connect(sa)
628                 sock.settimeout(self.socket_timeout)
629                 return sock
630             except socket.error as socket_err:
631                 err = socket_err
632                 if sock is not None:
633                     sock.close()
634         if err is not None:
635             raise ConnectionError(str(err))
636         raise ConnectionError("getaddrinfo returns an empty list")
637
638     def noidle(self):
639         # noidle's special case
640         if not self._pending or self._pending[0] != 'idle':
641             raise CommandError('cannot send noidle if send_idle was not called')
642         del self._pending[0]
643         self._write_command("noidle")
644         return self._fetch_list()
645
646     def connect(self, host: Optional[str] = None, port: Optional[Union[int, str]] = None):
647         """Connects the MPD server
648
649         :param str host: hostname, IP or FQDN (defaults to `localhost` or socket, see below for details)
650         :param port: port number (defaults to 6600)
651         :type port: str or int
652
653         The connect method honors MPD_HOST/MPD_PORT environment variables.
654
655         The underlying socket also honors MPD_TIMEOUT environment variable
656         and defaults to :py:obj:`musicpd.CONNECTION_TIMEOUT` (connect command only).
657
658         If you want to have a timeout for each command once you got connected,
659         set its value in :py:obj:`MPDClient.socket_timeout` (in second) or at
660         module level in :py:obj:`musicpd.SOCKET_TIMEOUT`.
661
662         .. note:: Default host/port
663
664           If host evaluate to :py:obj:`False`
665            * use ``MPD_HOST`` environment variable if set, extract password if present,
666            * else looks for an existing file in ``${XDG_RUNTIME_DIR:-/run/}/mpd/socket``
667            * else set host to ``localhost``
668
669           If port evaluate to :py:obj:`False`
670            * if ``MPD_PORT`` environment variable is set, use it for port
671            * else use ``6600``
672         """
673         if not host:
674             host = self.host
675         else:
676             self.host = host
677         if not port:
678             port = self.port
679         else:
680             self.port = port
681         if self._sock is not None:
682             raise ConnectionError("Already connected")
683         if host[0] in ['/', '@']:
684             self._sock = self._connect_unix(host)
685         else:
686             self._sock = self._connect_tcp(host, port)
687         self._rfile = self._sock.makefile("r", encoding='utf-8', errors='surrogateescape')
688         self._rbfile = self._sock.makefile("rb")
689         self._wfile = self._sock.makefile("w", encoding='utf-8')
690         try:
691             self._hello()
692         except:
693             self.disconnect()
694             raise
695
696     @property
697     def socket_timeout(self):
698         """Socket timeout in second (defaults to :py:obj:`SOCKET_TIMEOUT`).
699         Use None to disable socket timout."""
700         return self._socket_timeout
701
702     @socket_timeout.setter
703     def socket_timeout(self, timeout):
704         self._socket_timeout = timeout
705         if getattr(self._sock, 'settimeout', False):
706             self._sock.settimeout(self._socket_timeout)
707
708     def disconnect(self):
709         """Closes the MPD connection.
710         The client closes the actual socket, it does not use the
711         'close' request from MPD protocol (as suggested in documentation).
712         """
713         if hasattr(self._rfile, 'close'):
714             self._rfile.close()
715         if hasattr(self._rbfile, 'close'):
716             self._rbfile.close()
717         if hasattr(self._wfile, 'close'):
718             self._wfile.close()
719         if hasattr(self._sock, 'close'):
720             self._sock.close()
721         self._reset()
722
723     def __enter__(self):
724         self.connect()
725         return self
726
727     def __exit__(self, exception_type, exception_value, exception_traceback):
728         self.disconnect()
729
730     def fileno(self):
731         """Return the socket’s file descriptor (a small integer).
732         This is useful with :py:obj:`select.select`.
733         """
734         if self._sock is None:
735             raise ConnectionError("Not connected")
736         return self._sock.fileno()
737
738     def command_list_ok_begin(self):
739         if self._command_list is not None:
740             raise CommandListError("Already in command list")
741         if self._iterating:
742             raise IteratingError("Cannot begin command list while iterating")
743         if self._pending:
744             raise PendingCommandError("Cannot begin command list with pending commands")
745         self._write_command("command_list_ok_begin")
746         self._command_list = []
747
748     def command_list_end(self):
749         if self._command_list is None:
750             raise CommandListError("Not in command list")
751         if self._iterating:
752             raise IteratingError("Already iterating over a command list")
753         self._write_command("command_list_end")
754         return self._fetch_command_list()
755
756
757 def escape(text: str) -> str:
758     return text.replace("\\", "\\\\").replace('"', '\\"')
759
760 # vim: set expandtab shiftwidth=4 softtabstop=4 textwidth=79: