[Documentation] Improve API reference for patch and patch_all (#407)

aws_xray_sdk/core/patcher.py

@@ -47,6 +47,18 @@
 
 
 def patch_all(double_patch=False):
+    """
+    The X-Ray Python SDK supports patching aioboto3, aiobotocore, boto3, botocore, pynamodb, requests, 
+    sqlite3, mysql, httplib, pymongo, pymysql, psycopg2, pg8000, sqlalchemy_core, httpx, and mysql-connector.
+
+    To patch all supported libraries::
+
+        from aws_xray_sdk.core import patch_all
+
+        patch_all()
+
+    :param bool double_patch: enable or disable patching of indirect dependencies.
+    """
     if double_patch:
         patch(SUPPORTED_MODULES, raise_errors=False)
     else:
@@ -66,6 +78,16 @@ def _is_valid_import(module):
 
 
 def patch(modules_to_patch, raise_errors=True, ignore_module_patterns=None):
+    """
+    To patch specific modules::
+
+        from aws_xray_sdk.core import patch
+
+        i_want_to_patch = ('botocore') # a tuple that contains the libs you want to patch
+        patch(i_want_to_patch)
+
+    :param tuple modules_to_patch: a tuple containing the list of libraries to be patched
+    """
     enabled = global_sdk_config.sdk_enabled()
     if not enabled:
         log.debug("Skipped patching modules %s because the SDK is currently disabled." % ', '.join(modules_to_patch))

aws_xray_sdk/core/recorder.py

@@ -88,6 +88,7 @@ def configure(self, sampling=None, plugins=None,
 
         Configure needs to run before patching thrid party libraries
         to avoid creating dangling subsegment.
+
         :param bool sampling: If sampling is enabled, every time the recorder
             creates a segment it decides whether to send this segment to
             the X-Ray daemon. This setting is not used if the recorder

docs/aws_xray_sdk.ext.httpx.rst

@@ -0,0 +1,21 @@
+aws\_xray\_sdk.ext.httpx package
+================================
+
+Submodules
+----------
+
+aws\_xray\_sdk.ext.httpx.patch module
+-------------------------------------
+
+.. automodule:: aws_xray_sdk.ext.httpx.patch
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: aws_xray_sdk.ext.httpx
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/aws_xray_sdk.ext.pg8000.rst

@@ -0,0 +1,21 @@
+aws\_xray\_sdk.ext.pg8000 package
+=================================
+
+Submodules
+----------
+
+aws\_xray\_sdk.ext.pg8000.patch module
+--------------------------------------
+
+.. automodule:: aws_xray_sdk.ext.pg8000.patch
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: aws_xray_sdk.ext.pg8000
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/aws_xray_sdk.ext.psycopg2.rst

@@ -0,0 +1,21 @@
+aws\_xray\_sdk.ext.psycopg2 package
+===================================
+
+Submodules
+----------
+
+aws\_xray\_sdk.ext.psycopg2.patch module
+----------------------------------------
+
+.. automodule:: aws_xray_sdk.ext.psycopg2.patch
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: aws_xray_sdk.ext.psycopg2
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/aws_xray_sdk.ext.pymongo.rst

@@ -0,0 +1,21 @@
+aws\_xray\_sdk.ext.pymongo package
+==================================
+
+Submodules
+----------
+
+aws\_xray\_sdk.ext.pymongo.patch module
+---------------------------------------
+
+.. automodule:: aws_xray_sdk.ext.pymongo.patch
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: aws_xray_sdk.ext.pymongo
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/aws_xray_sdk.ext.pymysql.rst

@@ -0,0 +1,21 @@
+aws\_xray\_sdk.ext.pymysql package
+==================================
+
+Submodules
+----------
+
+aws\_xray\_sdk.ext.pymysql.patch module
+---------------------------------------
+
+.. automodule:: aws_xray_sdk.ext.pymysql.patch
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: aws_xray_sdk.ext.pymysql
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/aws_xray_sdk.ext.sqlalchemy_core.rst

@@ -0,0 +1,21 @@
+aws\_xray\_sdk.ext.sqlalchemy\_core package
+===========================================
+
+Submodules
+----------
+
+aws\_xray\_sdk.ext.sqlalchemy\_core.patch module
+------------------------------------------------
+
+.. automodule:: aws_xray_sdk.ext.sqlalchemy_core.patch
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: aws_xray_sdk.ext.sqlalchemy_core
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/thirdparty.rst

@@ -6,8 +6,8 @@ Third Party Library Support
 Patching Supported Libraries
 ----------------------------
 
-The SDK supports aioboto3, aiobotocore, boto3, botocore, pynamodb, requests, sqlite3, httplib and
-mysql-connector.
+The X-Ray Python SDK supports patching aioboto3, aiobotocore, boto3, botocore, pynamodb, requests, 
+sqlite3, mysql, httplib, pymongo, pymysql, psycopg2, pg8000, sqlalchemy_core, httpx, and mysql-connector.
 
 To patch, use code like the following in the main app::
 
@@ -36,6 +36,12 @@ The following modules are availble to patch::
         'sqlite3',
         'mysql',
         'httplib',
+        'pymongo',
+        'pymysql',
+        'psycopg2',
+        'pg8000',
+        'sqlalchemy_core',
+        'httpx',
     )
 
 Patching boto3 and botocore are equivalent since boto3 depends on botocore.