mbeliaev: logging and debugging

README.md

@@ -42,6 +42,7 @@ package.
   * [FileStat](#filestat)
   * [Promote Docker image](#promote-docker-image)
   * [Builds](#builds)
+  * [Logging](#logging)
 - [Admin area](#admin-area)
   * [User](#user)
     + [API Keys](#api-keys)
@@ -85,7 +86,6 @@ pip install dohq-artifactory==0.5.dev243
 ```
 
 # Usage
-
 ## Authentication ##
 
 `dohq-artifactory` supports these ways of authentication:
@@ -505,19 +505,19 @@ You can use [Artifactory Query Language](https://www.jfrog.com/confluence/displa
 ```python
 from artifactory import ArtifactoryPath
 
-aql = ArtifactoryPath(
+arti_path = ArtifactoryPath(
     "http://my-artifactory/artifactory"
 )  # path to artifactory, NO repo
 
 # dict support
 # Send query:
 # items.find({"repo": "myrepo"})
-artifacts = aql.aql("items.find", {"repo": "myrepo"})
+artifacts = arti_path.aql("items.find", {"repo": "myrepo"})
 
 # list support.
 # Send query:
 # items.find().include("name", "repo")
-artifacts = aql.aql("items.find()", ".include", ["name", "repo"])
+artifacts = arti_path.aql("items.find()", ".include", ["name", "repo"])
 
 #  support complex query
 # Example 1
@@ -529,7 +529,7 @@ artifacts = aql.aql("items.find()", ".include", ["name", "repo"])
 #         ]
 #     }
 # )
-args = [
+aqlargs = [
     "items.find",
     {
         "$and": [
@@ -546,7 +546,7 @@ args = [
 
 # artifacts_list contains raw data (list of dict)
 # Send query
-artifacts_list = aql.aql(*args)
+artifacts_list = arti_path.aql(*aqlargs)
 
 # Example 2
 # The query will find all items in repo docker-prod that are of type file and were created after timecode. The
@@ -572,11 +572,11 @@ aqlargs = [
     ".sort",
     {"$asc": ["repo", "path", "name"]},
 ]
-artifacts_list = aql.aql(*args)
+artifacts_list = arti_path.aql(*aqlargs)
 
 # You can convert to pathlib object:
-artifact_pathlib = map(aql.from_aql, artifacts_list)
-artifact_pathlib_list = list(map(aql.from_aql, artifacts_list))
+artifact_pathlib = map(arti_path.from_aql, artifacts_list)
+artifact_pathlib_list = list(map(arti_path.from_aql, artifacts_list))
 ```
 
 
@@ -651,6 +651,22 @@ build_number1.promote(ci_user="admin", properties={
  })
 ~~~
 
+## Logging 
+The library can be configured to emit logging that will give you better insight into what it's doing.
+Just configure `logging` module in your python script. Simplest example to add debug messages to a console:
+~~~python
+import logging
+from artifactory import ArtifactoryPath
+
+logging.basicConfig()
+# set level only for artifactory module, if omitted, then global log level is used, eg from basicConfig
+logging.getLogger('artifactory').setLevel(logging.DEBUG)
+
+path = ArtifactoryPath(
+    "http://my-artifactory/artifactory/myrepo/restricted-path", apikey="MY_API_KEY"
+)
+~~~
+
 # Admin area
 You can manipulate with user\group\repository and permission. First, create `ArtifactoryPath` object without a repository
 ```python

artifactory.py

@@ -64,6 +64,11 @@
 default_config_path = "~/.artifactory_python.cfg"
 global_config = None
 
+# set logger to be configurable from external
+logger = logging.getLogger(__name__)
+# Set default logging handler to avoid "No handler found" warnings.
+logger.addHandler(logging.NullHandler())
+
 
 def read_config(config_path=default_config_path):
     """
@@ -265,7 +270,7 @@ def log_download_progress(bytes_now, total_size):
     else:
         msg = "Downloaded {}MB".format(int(bytes_now / 1024 / 1024))
 
-    logging.debug(msg)
+    logger.debug(msg)
 
 
 class HTTPResponseWrapper(object):
@@ -385,6 +390,7 @@ def quote_url(url):
     :param url: (str) URL that should be quoted
     :return: (str) quoted URL
     """
+    logger.debug(f"Raw URL passed for encoding: {url}")
     parsed_url = urllib3.util.parse_url(url)
     if parsed_url.port:
         quoted_path = requests.utils.quote(
@@ -1332,10 +1338,10 @@ def __new__(cls, *args, **kwargs):
         auth_type = kwargs.get("auth_type")
 
         if apikey:
-            logging.debug("Use XJFrogApiAuth apikey")
+            logger.debug("Use XJFrogApiAuth apikey")
             obj.auth = XJFrogArtApiAuth(apikey=apikey)
         elif token:
-            logging.debug("Use XJFrogArtBearerAuth token")
+            logger.debug("Use XJFrogArtBearerAuth token")
             obj.auth = XJFrogArtBearerAuth(token=token)
         else:
             auth = kwargs.get("auth")
@@ -1961,6 +1967,7 @@ def aql(self, *args):
         """
         aql_query_url = "{}/api/search/aql".format(self.drive.rstrip("/"))
         aql_query_text = self.create_aql_text(*args)
+        logger.debug(f"AQL query request text: {aql_query_text}")
         r = self.session.post(aql_query_url, data=aql_query_text)
         r.raise_for_status()
         content = r.json()
@@ -1969,7 +1976,7 @@ def aql(self, *args):
     @staticmethod
     def create_aql_text(*args):
         """
-        Create AQL querty from string or list or dict arguments
+        Create AQL query from string or list or dict arguments
         """
         aql_query_text = ""
         for arg in args:
@@ -1978,6 +1985,7 @@ def create_aql_text(*args):
             elif isinstance(arg, list):
                 arg = "({})".format(json.dumps(arg)).replace("[", "").replace("]", "")
             aql_query_text += arg
+
         return aql_query_text
 
     def from_aql(self, result):