From: Harmon <Harmon758@gmail.com>
Date: Fri, 4 Feb 2022 08:28:02 +0000 (-0600)
Subject: Add logging documentation
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=77015065f63022747eb10f6ed081b39dbc75c4a3;p=tweepy.git

Add logging documentation
---

diff --git a/docs/index.rst b/docs/index.rst
index e4928e9..cd79f5a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -21,6 +21,7 @@ Contents:
    asyncstream.rst
    exceptions.rst
    extended_tweets.rst
+   logging.rst
    pagination.rst
    streaming.rst
    changelog.md
diff --git a/docs/logging.rst b/docs/logging.rst
new file mode 100644
index 0000000..65e7692
--- /dev/null
+++ b/docs/logging.rst
@@ -0,0 +1,35 @@
+.. _logging:
+
+*******
+Logging
+*******
+
+Tweepy uses the :mod:`logging` standard library module.
+
+The simplest way to set up logging is using :func:`logging.basicConfig`, e.g.::
+
+    import logging
+    
+    logging.basicConfig(level=logging.DEBUG)
+
+This will output logging from Tweepy, as well as other libraries (like Tweepy's
+dependencies) that use the :mod:`logging` module, directly to the console.
+
+The optional ``level`` argument can be any
+:ref:`logging level <python:levels>`.
+
+To configure logging for Tweepy (or each individual library) specifically, you
+can use :func:`logging.getLogger` to retrieve the logger for the library. For
+example::
+
+    import logging
+    
+    logger = logging.getLogger("Tweepy")
+    logger.setLevel(logging.DEBUG)
+    handler = logging.FileHandler(filename="tweepy.log")
+    logger.addHandler(handler)
+
+More advanced configuration is possible with the :mod:`logging` module.
+For more information, see the
+:doc:`logging module documentation <python:library/logging>` and
+:doc:`tutorials <python:howto/logging>`.