docs: fix broken README and docstring examples

README.md

@@ -202,7 +202,7 @@ def appium_service():
 
 def create_ios_driver(custom_opts=None):
     options = XCUITestOptions()
-    options.platformVersion = '13.4'
+    options.platform_version = '13.4'
     options.udid = '123456789ABC'
     if custom_opts is not None:
         options.load_capabilities(custom_opts)
@@ -212,7 +212,7 @@ def create_ios_driver(custom_opts=None):
 
 def create_android_driver(custom_opts=None):
     options = UiAutomator2Options()
-    options.platformVersion = '10'
+    options.platform_version = '10'
     options.udid = '123456789ABC'
     if custom_opts is not None:
         options.load_capabilities(custom_opts)
@@ -378,15 +378,20 @@ from appium.options.ios import XCUITestOptions
 
 import urllib3
 from appium.webdriver.appium_connection import AppiumConnection
+from appium.webdriver.client_config import AppiumClientConfig
 
 # Retry connection error up to 3 times.
-init_args_for_pool_manage = {'retries': urllib3.util.retry.Retry(total=3, connect=3, read=False)}
-appium_executor = AppiumConnection(
-    remote_server_addr='http://127.0.0.1:4723', init_args_for_pool_manage=init_args_for_pool_manage
+# Selenium passes the arguments under the nested 'init_args_for_pool_manager' key to urllib3.PoolManager.
+init_args_for_pool_manager = {
+    'init_args_for_pool_manager': {'retries': urllib3.util.retry.Retry(total=3, connect=3, read=False)}
+}
+client_config = AppiumClientConfig(
+    remote_server_addr='http://127.0.0.1:4723', init_args_for_pool_manager=init_args_for_pool_manager
 )
+appium_executor = AppiumConnection(client_config=client_config)
 
 options = XCUITestOptions()
-options.platformVersion = '13.4'
+options.platform_version = '13.4'
 options.udid = '123456789ABC'
 options.app = '/full/path/to/app/UICatalog.app.zip'
 driver = webdriver.Remote(appium_executor, options=options)

appium/webdriver/extensions/flutter_integration/flutter_commands.py

@@ -38,7 +38,8 @@ def wait_for_visible(
 
         Args:
             locator (Union[WebElement, FlutterFinder]): The element to wait for; can be a WebElement or a FlutterFinder.
-            timeout (Optional[float]): Maximum wait time in seconds. Defaults to a predefined timeout if not specified.
+            timeout (Optional[float]): Maximum wait time in whole seconds. The Flutter server drops any fractional
+                part, so 0.5 becomes 0. Defaults to a predefined timeout if not specified.
 
         Returns:
             None
@@ -59,7 +60,8 @@ def wait_for_invisible(
 
         Args:
             locator (Union[WebElement, FlutterFinder]): The element to wait for; can be a WebElement or a FlutterFinder.
-            timeout (Optional[float]): Maximum wait time in seconds. Defaults to a predefined timeout if not specified.
+            timeout (Optional[float]): Maximum wait time in whole seconds. The Flutter server drops any fractional
+                part, so 0.5 becomes 0. Defaults to a predefined timeout if not specified.
 
         Returns:
             None:

appium/webdriver/webdriver.py

@@ -74,7 +74,7 @@ class ExtensionBase:
 
     Example:
         When you want to add `example_command` which calls a get request to
-        `session/$sessionId/path/to/your/custom/url`.
+        `/session/$sessionId/path/to/your/custom/url`.
 
         #. Defines an extension as a subclass of `ExtensionBase`
             .. code-block:: python
@@ -91,7 +91,7 @@ def custom_method_name(self):
 
                     # Used to register the command pair as "Appium command" in this driver.
                     def add_command(self):
-                        return ('GET', 'session/$sessionId/path/to/your/custom/url')
+                        return ('GET', '/session/$sessionId/path/to/your/custom/url')
 
         #. Creates a session with the extension.
             .. code-block:: python
@@ -105,7 +105,7 @@ def add_command(self):
             .. code-block:: python
 
                 # Then, the driver calls a get request against
-                # `session/$sessionId/path/to/your/custom/url`. `$sessionId` will be
+                # `/session/$sessionId/path/to/your/custom/url`. `$sessionId` will be
                 # replaced properly in the driver. Then, the method returns
                 # the `value` part of the response.
                 driver.custom_method_name()
@@ -127,16 +127,16 @@ class YourCustomCommand(ExtensionBase):
                 def method_name(self):
                     return 'custom_method_name'
 
-                def test_command(self, argument):
+                def custom_method_name(self, argument):
                     return self.execute(argument)['value']
 
                 def add_command(self):
-                    return ('post', 'session/$sessionId/path/to/your/custom/url')
+                    return ('post', '/session/$sessionId/path/to/your/custom/url')
 
             driver = webdriver.Remote('http://localhost:4723/wd/hub', options=options,
                 extensions=[YourCustomCommand])
 
-            # Then, the driver sends a post request to `session/$sessionId/path/to/your/custom/url`
+            # Then, the driver sends a post request to `/session/$sessionId/path/to/your/custom/url`
             # with `{'dummy_arg': 'as a value'}` JSON body.
             driver.custom_method_name({'dummy_arg': 'as a value'})
 
@@ -153,13 +153,13 @@ def custom_method_name(self, element_id):
                     return self.execute({'id': element_id})['value']
 
                 def add_command(self):
-                    return ('GET', 'session/$sessionId/path/to/your/custom/$id/url')
+                    return ('GET', '/session/$sessionId/path/to/your/custom/$id/url')
 
             driver = webdriver.Remote('http://localhost:4723/wd/hub', options=options,
-                extensions=[YourCustomCommand])
+                extensions=[CustomURLCommand])
             element = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='id')
 
-            # Then, the driver calls a get request to `session/$sessionId/path/to/your/custom/$id/url`
+            # Then, the driver calls a get request to `/session/$sessionId/path/to/your/custom/$id/url`
             # with replacing the `$id` with the given `element.id`
             driver.custom_method_name(element.id)