diff --git a/timesearch/common.py b/timesearch/common.py
index df5a458..eac5c2c 100644
--- a/timesearch/common.py
+++ b/timesearch/common.py
@@ -64,6 +64,10 @@ def fetchgenerator(cursor):
yield item
def generator_chunker(generator, chunk_size):
+ '''
+ Given an item generator, yield lists of length chunk_size, except maybe
+ the last one.
+ '''
chunk = []
for item in generator:
chunk.append(item)
diff --git a/timesearch/livestream.py b/timesearch/livestream.py
index 9f0b47d..c7e0137 100644
--- a/timesearch/livestream.py
+++ b/timesearch/livestream.py
@@ -7,7 +7,22 @@ from . import exceptions
from . import tsdb
+def _listify(x):
+ '''
+ The user may have given us a string containing multiple subreddits / users.
+ Try to split that up into a list of names.
+ '''
+ if not x:
+ return []
+ if isinstance(x, str):
+ return common.split_any(x, ['+', ' ', ','])
+ return x
+
def generator_printer(generator):
+ '''
+ Given a generator that produces livestream update steps, print them out.
+ This yields None because print returns None.
+ '''
prev_message_length = 0
for step in generator:
newtext = '%s: +%ds, %dc' % (step['tsdb'].filepath.basename, step['new_submissions'], step['new_comments'])
@@ -24,8 +39,16 @@ def generator_printer(generator):
yield None
def cycle_generators(generators, only_once, sleepy):
+ '''
+ Given multiple generators, yield an item from each one, cycling through
+ them in a round-robin fashion.
+
+ This is useful if you want to convert multiple livestream generators into a
+ single generator that take turns updating each of them and yields all of
+ their items.
+ '''
while True:
- for (index, generator) in enumerate(generators):
+ for generator in generators:
yield next(generator)
if only_once:
break
@@ -45,18 +68,12 @@ def livestream(
Continuously get posts from this source and insert them into the database.
as_a_generator:
- return a generator where every iteration does a single livestream loop.
- This is good if you want to manage multiple livestreams yourself by
- calling `next` on each of them, instead of getting stuck in here.
+ Return a generator where every iteration does a single livestream loop
+ and yields the return value of TSDB.insert (A summary of new
+ submission & comment count).
+ This is useful if you want to manage the generator yourself.
+ Otherwise, this function will run the generator forever.
'''
-
- def _listify(x):
- if x is None:
- return []
- if isinstance(x, str):
- return common.split_any(x, ['+', ' ', ','])
- return x
-
subreddits = _listify(subreddit)
usernames = _listify(username)
kwargs = {
@@ -65,6 +82,7 @@ def livestream(
'limit': limit,
'params': {'show': 'all'},
}
+
subreddit_generators = [
_livestream_as_a_generator(subreddit=subreddit, username=None, **kwargs) for subreddit in subreddits
]
@@ -72,12 +90,13 @@ def livestream(
_livestream_as_a_generator(subreddit=None, username=username, **kwargs) for username in usernames
]
generators = subreddit_generators + user_generators
+
if as_a_generator:
if len(generators) == 1:
return generators[0]
return generators
- generator = cycle_generators(generators, only_once, sleepy)
+ generator = cycle_generators(generators, only_once=only_once, sleepy=sleepy)
generator = generator_printer(generator)
try:
diff --git a/timesearch/offline_reading.py b/timesearch/offline_reading.py
index 7c500b6..3b3263d 100644
--- a/timesearch/offline_reading.py
+++ b/timesearch/offline_reading.py
@@ -274,6 +274,9 @@ def html_from_tree(tree, sort=None):
return page
def html_helper_permalink(item):
+ '''
+ Given a submission or a comment, return an tag for its permalink.
+ '''
link = 'https://www.reddit.com/r/%s/comments/' % item.subreddit
if item.object_type == 'submission':
link += item.idstr[3:]
@@ -283,6 +286,10 @@ def html_helper_permalink(item):
return link
def html_helper_urlortext(submission):
+ '''
+ Given a submission, return either an tag for its url, or its
+ markdown-rendered selftext.
+ '''
if submission.url:
text = '{url}'.format(url=submission.url)
elif submission.selftext:
@@ -293,6 +300,9 @@ def html_helper_urlortext(submission):
return text
def html_helper_userlink(item):
+ '''
+ Given a submission or comment, return an tag for its author, or [deleted].
+ '''
name = item.author
if name.lower() == '[deleted]':
return '[deleted]'