diff options
Diffstat (limited to '')
| -rw-r--r-- | README.md | 218 |
1 files changed, 9 insertions, 209 deletions
@@ -7,217 +7,17 @@ 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] - [--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: - - > 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" - } - ] - -The durations are calculated on a per-user basis by default. -You can change that by supplying either `date` (to group by dates), `weekday` -(to group by weekdays) or `hour` (to group by day hours) 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 -``` - -``` -> online_duration.py --grouping hour db.csv -0:00:00,0:00:00 -1:00:00,0:00:00 -2:00:00,0:00:00 -3:00:00,0:00:00 -4:00:00,0:03:56 -5:00:00,0:14:14 -6:00:00,0:29:30 -7:00:00,0:31:20 -8:00:00,0:12:04 -9:00:00,0:00:00 -10:00:00,0:00:00 -11:00:00,0:23:14 -12:00:00,0:06:00 -13:00:00,0:46:19 -14:00:00,0:00:00 -15:00:00,0:00:00 -16:00:00,0:00:00 -17:00:00,0:00:00 -18:00:00,0:00:00 -19:00:00,0:00:00 -20:00:00,0:00:00 -21:00:00,0:00:00 -22:00:00,0:00:00 -23:00:00,0:00:00 -``` +The main package is located in the "vk/" directory. -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] - - > online_duration.py --output-format img --grouping hour db.csv hour.png - -![hour.png] - -You can limit the scope of the database by supplying a time range. -Only online durations that are within the supplied range shall then be -processed. -Set the range by specifying both or one of the `--from` and `--to` parameters. -Values must be in the `%Y-%m-%dT%H:%M:%SZ` format (a subset of ISO 8601). - -All dates and times are in UTC. - -#### Known issues - -* When people go online using the web version and don't visit other pages over -time (for example, just listening to music), they appear offline. -Hence the 0:00:00 durations you might sometimes encounter. -This might also happen using other clients. - -[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 -[hour.png]: img/online_duration/hour.png - -### mutual_friends.py - -Learn who your ex and her new boyfriend are both friends with. - - 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". - -The output format is CSV (comma-separated values) by default. -You can also get a JSON document: +Additionally, a few scripts are supplied in the "bin/" directory to show-case +the package's capabilities. +Pass the `--help` flag to a script to see its detailed usage information. +The supplied scripts are listed below. - > 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" - } - ] +* [mutual_friends.py]: Learn who your ex and her new boyfriend are both friends +with. +* [track_status.py]: Track when people go online/offline. +* [online_duration.py]: View/visualize the amount of time people spend online. License ------- |