From 790d98d5681a6a8f9025c9a607675b922357c29b Mon Sep 17 00:00:00 2001 From: Egor Tensin Date: Sat, 18 Jun 2016 06:16:38 +0300 Subject: README update --- README.md | 151 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 145 insertions(+), 6 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index c888dda..3243fb8 100644 --- a/README.md +++ b/README.md @@ -7,25 +7,164 @@ Requires Python 3.4 or higher. Usage ----- +Pass the `--help` flag to a script to see its detailed usage information. + ### track_status.py Track when people go online/offline. - usage: track_status.py [-h] [-t TIMEOUT] [-l LOG] UID [UID ...] + usage: track_status.py [-h] [-t TIMEOUT] [-l LOG] + [--output-format {csv,log,null}] [-o OUTPUT] + UID [UID ...] + +For example (using made up user IDs/"screen names"), + + > track_status.py john.doe jane.smith + [2016-06-18 01:43:34] John Doe is ONLINE. + [2016-06-18 01:43:34] John Doe was last seen at 2016-06-18 01:33:58+03:00 using the official iPhone app. + [2016-06-18 01:43:34] Jane Smith is OFFLINE. + [2016-06-18 01:43:34] Jane Smith was last seen at 2016-06-18 01:15:47+03:00 using the web version (or an unrecognized app). + [2016-06-18 01:59:09] Jane Smith went ONLINE. + [2016-06-18 01:59:09] Jane Smith was last seen at 2016-06-18 01:59:07+03:00 using the official Android app. + [2016-06-18 02:10:00] John Doe went OFFLINE. + [2016-06-18 02:10:00] John Doe was last seen at 2016-06-18 01:54:58+03:00 using the official iPhone app. + ... + +By default, the script produces a human-readable log. +Use the `--log` parameter to write the log to a file. +If you want to record when people go online/offline for [further analysis], +specify the path to a database using the `--output` parameter. +Be careful: if the file already exists, it will be overwritten! + +[further analysis]: #online_durationpy + +### online_duration.py + +View the amount of time people spent online. + + usage: online_duration.py [-h] [--grouping {user,date,weekday}] + [--input-format {csv,log,null}] + [--output-format {csv,json,img}] + input [output] + +This script additionally requires [matplotlib] to be installed. + +Analyze the database produced by [track_status.py] and calculate the total +amount of time people spent online. + +For example (assuming the database in "db.csv" was generated by +[track_status.py] before): + + > online_duration.py db.csv + 89497105,John,Smith,john.smith,0:12:31 + 3698577,Jane,Smith,jane.smith,1:34:46 + +In the example above, "John Smith" and "Jane Smith" spent approx. 13 and 95 +minutes online respectively. + +The output format is CSV (comma-separated values) by default. +You can also get a JSON document: -For example, + > online_duration.py --output-format json db.csv + [ + { + "uid": 89497105, + "first_name": "John", + "last_name": "Smith", + "screen_name": "john.smith", + "duration": "0:12:31" + }, + { + "uid": 3698577, + "first_name": "Jane", + "last_name": "Smith", + "screen_name": "jane.smith", + "duration": "1:34:46" + } + ] - > track_status.py egor.tensin id1 +The durations are calculated on a per-user basis by default. +You can change that by supplying either `date` (to group by dates) or `weekday` +(to group by weekdays) as the `--grouping` parameter value. +For example (assuming that both Jane and Joe spent their time online on Friday, +June 17, 2016). + + > online_duration.py --output-format json --grouping date db.csv + [ + { + "date": "2016-06-17", + "duration": "1:47:17" + } + ] + + > online_duration.py --output-format csv --grouping weekday db.csv + Monday,0:00:00 + Tuesday,0:00:00 + Wednesday,0:00:00 + Thursday,0:00:00 + Friday,1:47:17 + Saturday,0:00:00 + Sunday,0:00:00 + +In my opinion, the script's most useful feature is the ability to easily create +plots that represent the text data (like in the examples above). +To produce a plot, pass `img` as the `--output-format` parameter value and add +a file path to write the image to. + + > online_duration.py --output-format img db.csv user.png + +![user.png] + + > online_duration.py --output-format img --grouping date db.csv date.png + +![date.png] + + > online_duration.py --output-format img --grouping weekday db.csv weekday.png + +![weekday.png] + +[matplotlib]: http://matplotlib.org/ +[track_status.py]: #track_statuspy + +[user.png]: img/online_duration/user.png +[date.png]: img/online_duration/date.png +[weekday.png]: img/online_duration/weekday.png ### mutual_friends.py Learn who your ex and her new boyfriend are both friends with. - usage: mutual_friends.py [-h] UID [UID ...] + usage: mutual_friends.py [-h] [--output-format {csv,json}] UID [UID ...] + +For example (using made up user IDs/"screen names"), + + > mutual_friends.py john.doe jane.doe + 89497105,John,Smith,john.smith + 3698577,Jane,Smith,jane.smith + +In the example above, both "John Doe" and "Jane Doe" are friends with "John +Smith" and "Jane Smith", whose user IDs are 89497105 and 3698577 respectively. +Their "screen names" (the part after "vk.com/" of their personal page URLs) are +"john.smith" and "jane.smith". -For example, +The output format is CSV (comma-separated values) by default. +You can also get a JSON document: - > mutual_friends.py egor.tensin durov + > mutual_friends.py --output-format json john.doe jane.doe + [ + { + "uid": 89497105, + "first_name": "John", + "last_name": "Smith", + "screen_name": "john.smith" + }, + { + "uid": 3698577, + "first_name": "Jane", + "last_name": "Smith", + "screen_name": "jane.smith" + } + ] License ------- -- cgit v1.2.3