Pass a reason argument to the disconnect handler (#1422)

docs/client.rst

@@ -312,8 +312,8 @@ server::
         print("The connection failed!")
 
     @sio.event
-    def disconnect():
-        print("I'm disconnected!")
+    def disconnect(reason):
+        print("I'm disconnected! reason:", reason)
 
 The ``connect_error`` handler is invoked when a connection attempt fails. If
 the server provides arguments, these are passed on to the handler. The server
@@ -325,7 +325,20 @@ server initiated disconnects, or accidental disconnects, for example due to
 networking failures. In the case of an accidental disconnection, the client is
 going to attempt to reconnect immediately after invoking the disconnect
 handler. As soon as the connection is re-established the connect handler will
-be invoked once again.
+be invoked once again. The handler receives a ``reason`` argument which
+provides the cause of the disconnection::
+
+    @sio.event
+    def disconnect(reason):
+        if reason == sio.reason.CLIENT_DISCONNECT:
+            print('the client disconnected')
+        elif reason == sio.reason.SERVER_DISCONNECT:
+            print('the server disconnected the client')
+        else:
+            print('disconnect reason:', reason)
+
+See the The :attr:`socketio.Client.reason` attribute for a list of possible
+disconnection reasons.
 
 The ``connect``, ``connect_error`` and ``disconnect`` events have to be
 defined explicitly and are not invoked on a catch-all event handler.
@@ -509,7 +522,7 @@ that belong to a namespace can be created as methods of a subclass of
         def on_connect(self):
             pass
 
-        def on_disconnect(self):
+        def on_disconnect(self, reason):
             pass
 
         def on_my_event(self, data):
@@ -525,7 +538,7 @@ coroutines if desired::
         def on_connect(self):
             pass
 
-        def on_disconnect(self):
+        def on_disconnect(self, reason):
             pass
 
         async def on_my_event(self, data):

docs/server.rst

@@ -232,8 +232,8 @@ automatically when a client connects or disconnects from the server::
         print('connect ', sid)
 
     @sio.event
-    def disconnect(sid):
-        print('disconnect ', sid)
+    def disconnect(sid, reason):
+        print('disconnect ', sid, reason)
 
 The ``connect`` event is an ideal place to perform user authentication, and
 any necessary mapping between user entities in the application and the ``sid``
@@ -256,6 +256,21 @@ message::
     def connect(sid, environ, auth):
         raise ConnectionRefusedError('authentication failed')
 
+The disconnect handler receives the ``sid`` assigned to the client and a
+``reason``, which provides the cause of the disconnection::
+
+    @sio.event
+    def disconnect(sid, reason):
+        if reason == sio.reason.CLIENT_DISCONNECT:
+            print('the client disconnected')
+        elif reason == sio.reason.SERVER_DISCONNECT:
+            print('the server disconnected the client')
+        else:
+            print('disconnect reason:', reason)
+
+See the The :attr:`socketio.Server.reason` attribute for a list of possible
+disconnection reasons.
+
 Catch-All Event Handlers
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -433,7 +448,7 @@ belong to a namespace can be created as methods in a subclass of
         def on_connect(self, sid, environ):
             pass
 
-        def on_disconnect(self, sid):
+        def on_disconnect(self, sid, reason):
             pass
 
         def on_my_event(self, sid, data):
@@ -449,7 +464,7 @@ if desired::
         def on_connect(self, sid, environ):
             pass
 
-        def on_disconnect(self, sid):
+        def on_disconnect(self, sid, reason):
             pass
 
         async def on_my_event(self, sid, data):

examples/client/async/fiddle_client.py

@@ -10,8 +10,8 @@ async def connect():
 
 
 @sio.event
-async def disconnect():
-    print('disconnected from server')
+async def disconnect(reason):
+    print('disconnected from server, reason:', reason)
 
 
 @sio.event

examples/client/sync/fiddle_client.py

@@ -9,8 +9,8 @@ def connect():
 
 
 @sio.event
-def disconnect():
-    print('disconnected from server')
+def disconnect(reason):
+    print('disconnected from server, reason:', reason)
 
 
 @sio.event

examples/server/aiohttp/app.html

@@ -11,8 +11,8 @@
             socket.on('connect', function() {
                 socket.emit('my_event', {data: 'I\'m connected!'});
             });
-            socket.on('disconnect', function() {
-                $('#log').append('<br>Disconnected');
+            socket.on('disconnect', function(reason) {
+                $('#log').append('<br>Disconnected: ' + reason);
             });
             socket.on('my_response', function(msg) {
                 $('#log').append('<br>Received: ' + msg.data);

examples/server/aiohttp/app.py

@@ -70,8 +70,8 @@ async def connect(sid, environ):
 
 
 @sio.event
-def disconnect(sid):
-    print('Client disconnected')
+def disconnect(sid, reason):
+    print('Client disconnected, reason:', reason)
 
 
 app.router.add_static('/static', 'static')
@@ -84,4 +84,4 @@ async def init_app():
 
 
 if __name__ == '__main__':
-    web.run_app(init_app())
+    web.run_app(init_app(), port=5000)

examples/server/aiohttp/fiddle.py

@@ -19,13 +19,13 @@ async def connect(sid, environ, auth):
 
 
 @sio.event
-def disconnect(sid):
-    print('disconnected', sid)
+def disconnect(sid, reason):
+    print('disconnected', sid, reason)
 
 
 app.router.add_static('/static', 'static')
 app.router.add_get('/', index)
 
 
 if __name__ == '__main__':
-    web.run_app(app)
+    web.run_app(app, port=5000)

examples/server/asgi/app.html

@@ -11,8 +11,8 @@
             socket.on('connect', function() {
                 socket.emit('my_event', {data: 'I\'m connected!'});
             });
-            socket.on('disconnect', function() {
-                $('#log').append('<br>Disconnected');
+            socket.on('disconnect', function(reason) {
+                $('#log').append('<br>Disconnected: ' + reason);
             });
             socket.on('my_response', function(msg) {
                 $('#log').append('<br>Received: ' + msg.data);

examples/server/asgi/app.py

@@ -88,8 +88,8 @@ async def test_connect(sid, environ):
 
 
 @sio.on('disconnect')
-def test_disconnect(sid):
-    print('Client disconnected')
+def test_disconnect(sid, reason):
+    print('Client disconnected, reason:', reason)
 
 
 if __name__ == '__main__':

examples/server/asgi/fiddle.py

@@ -17,8 +17,8 @@ async def connect(sid, environ, auth):
 
 
 @sio.event
-def disconnect(sid):
-    print('disconnected', sid)
+def disconnect(sid, reason):
+    print('disconnected', sid, reason)
 
 
 if __name__ == '__main__':

examples/server/javascript/fiddle.js

@@ -19,8 +19,8 @@ io.on('connection', socket => {
     hello: 'you'
   });
 
-  socket.on('disconnect', () => {
-    console.log(`disconnect ${socket.id}`);
+  socket.on('disconnect', (reason) => {
+    console.log(`disconnect ${socket.id}, reason: ${reason}`);
   });
 });
 

examples/server/sanic/app.html

@@ -11,8 +11,8 @@
             socket.on('connect', function() {
                 socket.emit('my_event', {data: 'I\'m connected!'});
             });
-            socket.on('disconnect', function() {
-                $('#log').append('<br>Disconnected');
+            socket.on('disconnect', function(reason) {
+                $('#log').append('<br>Disconnected: ' + reason);
             });
             socket.on('my_response', function(msg) {
                 $('#log').append('<br>Received: ' + msg.data);

examples/server/sanic/app.py

@@ -77,8 +77,8 @@ async def connect(sid, environ):
 
 
 @sio.event
-def disconnect(sid):
-    print('Client disconnected')
+def disconnect(sid, reason):
+    print('Client disconnected, reason:', reason)
 
 
 app.static('/static', './static')

examples/server/sanic/fiddle.py

@@ -21,8 +21,8 @@ async def connect(sid, environ, auth):
 
 
 @sio.event
-def disconnect(sid):
-    print('disconnected', sid)
+def disconnect(sid, reason):
+    print('disconnected', sid, reason)
 
 
 app.static('/static', './static')

examples/server/tornado/app.py

@@ -75,8 +75,8 @@ async def connect(sid, environ):
 
 
 @sio.event
-def disconnect(sid):
-    print('Client disconnected')
+def disconnect(sid, reason):
+    print('Client disconnected, reason:', reason)
 
 
 def main():

examples/server/tornado/fiddle.py

@@ -24,8 +24,8 @@ async def connect(sid, environ, auth):
 
 
 @sio.event
-def disconnect(sid):
-    print('disconnected', sid)
+def disconnect(sid, reason):
+    print('disconnected', sid, reason)
 
 
 def main():

examples/server/tornado/templates/app.html

@@ -11,8 +11,8 @@
             socket.on('connect', function() {
                 socket.emit('my_event', {data: 'I\'m connected!'});
             });
-            socket.on('disconnect', function() {
-                $('#log').append('<br>Disconnected');
+            socket.on('disconnect', function(reason) {
+                $('#log').append('<br>Disconnected: ' + reason);
             });
             socket.on('my_response', function(msg) {
                 $('#log').append('<br>Received: ' + msg.data);

examples/server/wsgi/app.py

@@ -94,8 +94,8 @@ def connect(sid, environ):
 
 
 @sio.event
-def disconnect(sid):
-    print('Client disconnected')
+def disconnect(sid, reason):
+    print('Client disconnected, reason:', reason)
 
 
 if __name__ == '__main__':

examples/server/wsgi/django_socketio/socketio_app/static/index.html

@@ -11,8 +11,8 @@
             socket.on('connect', function() {
                 socket.emit('my_event', {data: 'I\'m connected!'});
             });
-            socket.on('disconnect', function() {
-                $('#log').append('<br>Disconnected');
+            socket.on('disconnect', function(reason) {
+                $('#log').append('<br>Disconnected: ' + reason);
             });
             socket.on('my_response', function(msg) {
                 $('#log').append('<br>Received: ' + msg.data);

examples/server/wsgi/django_socketio/socketio_app/views.py

@@ -78,5 +78,5 @@ def connect(sid, environ):
 
 
 @sio.event
-def disconnect(sid):
-    print('Client disconnected')
+def disconnect(sid, reason):
+    print('Client disconnected, reason:', reason)

examples/server/wsgi/fiddle.py

@@ -23,8 +23,8 @@ def connect(sid, environ, auth):
 
 
 @sio.event
-def disconnect(sid):
-    print('disconnected', sid)
+def disconnect(sid, reason):
+    print('disconnected', sid, reason)
 
 
 if __name__ == '__main__':

examples/server/wsgi/templates/index.html

@@ -11,8 +11,8 @@
             socket.on('connect', function() {
                 socket.emit('my_event', {data: 'I\'m connected!'});
             });
-            socket.on('disconnect', function() {
-                $('#log').append('<br>Disconnected');
+            socket.on('disconnect', function(reason) {
+                $('#log').append('<br>Disconnected: ' + reason);
             });
             socket.on('my_response', function(msg) {
                 $('#log').append('<br>Received: ' + msg.data);

pyproject.toml

@@ -15,7 +15,7 @@ classifiers = [
 requires-python = ">=3.8"
 dependencies = [
     "bidict >= 0.21.0",
-    "python-engineio >= 4.8.0",
+    "python-engineio >= 4.11.0",
 ]
 
 [project.readme]