Add missing docstrings

Author: vshlapakov

scrapinghub/client/activity.py

@@ -44,10 +44,13 @@ class Activity(_Proxy):
         >>> project.activity.add(events)
 
     """
-    def __init__(self, *args, **kwargs):
-        super(Activity, self).__init__(*args, **kwargs)
-
     def iter(self, **params):
+        """Iterate over activity events.
+
+        :return: a generator object over a list of activity event dicts.
+        :rtype: :class:`types.GeneratorType[dict]`
+        """
+        # TODO describe allowable params
         params = self._modify_iter_params(params)
         return self._origin.list(**params)
 

scrapinghub/client/collections.py

@@ -181,11 +181,29 @@ def delete(self, keys):
         self._origin.delete(keys)
 
     def count(self, *args, **kwargs):
+        """Count collection items with a given filters.
+
+        :return: amount of elements in collection.
+        :rtype: :class:`int`
+        """
+        # TODO describe allowable params
         return self._origin._collections.count(
             self._origin.coltype, self._origin.colname, *args, **kwargs)
 
     def iter(self, key=None, prefix=None, prefixcount=None, startts=None,
              endts=None, requests_params=None, **params):
+        """A method to iterate through collection items.
+
+        :param key: a string key or a list of keys to filter with.
+        :param prefix: a string prefix to filter items.
+        :param prefixcount: maximum number of values to return per prefix.
+        :param startts: UNIX timestamp at which to begin results.
+        :param endts: UNIX timestamp at which to end results.
+        :param requests_params: (optional) a dict with optional requests params.
+        :param \*\*params: (optional) additional query params for the request.
+        :return: an iterator over items list.
+        :rtype: :class:`collections.Iterable[dict]`
+        """
         update_kwargs(params, key=key, prefix=prefix, prefixcount=prefixcount,
                       startts=startts, endts=endts,
                       requests_params=requests_params)
@@ -195,6 +213,19 @@ def iter(self, key=None, prefix=None, prefixcount=None, startts=None,
 
     def iter_raw_json(self, key=None, prefix=None, prefixcount=None,
                       startts=None, endts=None, requests_params=None, **params):
+        """A method to iterate through json pack-ed items.
+        Can be convenient if data is needed in the json format.
+
+        :param key: a string key or a list of keys to filter with.
+        :param prefix: a string prefix to filter items.
+        :param prefixcount: maximum number of values to return per prefix.
+        :param startts: UNIX timestamp at which to begin results.
+        :param endts: UNIX timestamp at which to end results.
+        :param requests_params: (optional) a dict with optional requests params.
+        :param \*\*params: (optional) additional query params for the request.
+        :return: an iterator over items list packed with json.
+        :rtype: :class:`collections.Iterable[str]`
+        """
         update_kwargs(params, key=key, prefix=prefix, prefixcount=prefixcount,
                       startts=startts, endts=endts,
                       requests_params=requests_params)
@@ -248,6 +279,18 @@ def list(self, key=None, prefix=None, prefixcount=None, startts=None,
                       startts=startts, endts=endts)
         return list(self.iter(requests_params=requests_params, **params))
 
-    def create_writer(self, **kwargs):
+    def create_writer(self, start=0, auth=None, size=1000, interval=15,
+                      qsize=None, content_encoding='identity',
+                      maxitemsize=1024 ** 2, callback=None):
+        """Create a new writer for a collection.
+
+        :return: a new writer object.
+        :rtype: :class:`~scrapinghub.hubstorage.batchuploader._BatchWriter`
+        """
+        # TODO describe allowable params
+        kwargs = {}
+        update_kwargs(start=start, auth=auth, size=size, interval=interval,
+                      qsize=qsize, content_encoding=content_encoding,
+                      maxitemsize=maxitemsize, callback=callback)
         return self._origin._collections.create_writer(
             self._origin.coltype, self._origin.colname, **kwargs)

scrapinghub/client/frontiers.py

@@ -121,9 +121,11 @@ def newcount(self):
         return sum(self._origin.newcount.values())
 
     def flush(self):
+        """Flush data in all frontiers writer threads."""
         self._origin.flush()
 
     def close(self):
+        """Close frontier writer threads one-by-one."""
         self._origin.close()
 
 

scrapinghub/client/logs.py

@@ -50,22 +50,34 @@ class Logs(_ItemsResourceProxy, _DownloadableProxyMixin):
         }]
     """
     def log(self, message, level=logging.INFO, ts=None, **other):
+        """Base method to write a log entry.
+
+        :param message: a string message.
+        :param level: (optional) logging level, default to INFO.
+        :param ts: (optional) unix timestamp in milliseconds.
+        :param \*\*other: other optional kwargs.
+        """
         self._origin.log(message, level=level, ts=ts, **other)
 
     def debug(self, message, **other):
+        """Log a message with DEBUG level."""
         self._origin.debug(message, **other)
 
     def info(self, message, **other):
+        """Log a message with INFO level."""
         self._origin.info(message, **other)
 
     def warn(self, message, **other):
+        """Log a message with WARN level."""
         self._origin.warn(message, **other)
     warning = warn
 
     def error(self, message, **other):
+        """Log a message with ERROR level."""
         self._origin.error(message, **other)
 
     def batch_write_start(self):
+        """Override to set a start parameter when commencing writing."""
         return self._origin.batch_write_start()
 
     def _modify_iter_params(self, params):

scrapinghub/client/requests.py

@@ -42,5 +42,16 @@ class Requests(_ItemsResourceProxy, _DownloadableProxyMixin):
         }]
     """
     def add(self, url, status, method, rs, parent, duration, ts, fp=None):
+        """ Add a new requests.
+
+        :param url: string url for the request.
+        :param status: HTTP status of the request.
+        :param method: stringified request method.
+        :param rs: response body length.
+        :param parent: parent request id or ``None``.
+        :param duration: request duration in milliseconds.
+        :param ts: unix timestamp in milliseconds.
+        :param fp: (optional) string fingerprint for the request.
+        """
         return self._origin.add(
             url, status, method, rs, parent, duration, ts, fp=None)