From f1a4bf0ce674b0b8ea3f05bd2d3605e19097244a Mon Sep 17 00:00:00 2001 From: Egor Tensin Date: Tue, 4 May 2021 00:50:07 +0300 Subject: README: update --- README.md | 50 ++++---------- docs/mutual_friends.md | 46 ------------- docs/mutuals.md | 46 +++++++++++++ docs/online_sessions.md | 171 ------------------------------------------------ docs/sessions.md | 171 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/status.md | 44 +++++++++++++ docs/track_status.md | 44 ------------- 7 files changed, 274 insertions(+), 298 deletions(-) delete mode 100644 docs/mutual_friends.md create mode 100644 docs/mutuals.md delete mode 100644 docs/online_sessions.md create mode 100644 docs/sessions.md create mode 100644 docs/status.md delete mode 100644 docs/track_status.md diff --git a/README.md b/README.md index f448066..9bdd9fe 100644 --- a/README.md +++ b/README.md @@ -5,47 +5,28 @@ VK scripts A collection of scripts abusing VK.com API. -Prerequisites -------------- +Installation +------------ -* Python 3.4 or higher -* [matplotlib] (required by [online_sessions.py]) -* [numpy] (required by [matplotlib]) + pip install vk-scripts -The versions below have been verified to work properly. -| Software | Version -| ---------- | ------- -| CPython | 3.5.1 -| numpy | 1.11.0 -| matplotlib | 1.5.1 - -Windows binaries for CPython can be acquired at -http://www.lfd.uci.edu/~gohlke/pythonlibs/. +Python 3.4 or higher is required. +`vk-sessions` uses [matplotlib]. [matplotlib]: http://matplotlib.org/ -[numpy]: http://www.numpy.org/ Usage ----- -The main package resides in the "vk/" directory. - -Also, a few scripts are supplied in the "bin/" directory to showcase the -package's capabilities. -Run the scripts from the top-level directory using `python -m`. -Pass the `--help` flag to a script to examine its detailed usage information. -The supplied scripts are listed below. +* [vk-mutuals] — Learn who your ex and her new boyfriend are both friends +with. +* [vk-status] — Track when people go online/offline. +* [vk-sessions] — View/visualize the amount of time people spend online. -* [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_sessions.py] — View/visualize the amount of time people spend -online. - -[mutual_friends.py]: docs/mutual_friends.md -[track_status.py]: docs/track_status.md -[online_sessions.py]: docs/online_sessions.md +[vk-mutuals]: docs/mutuals.md +[vk-status]: docs/status.md +[vk-sessions]: docs/sessions.md Development ----------- @@ -53,13 +34,8 @@ Development ### Linting Requires [Pylint]. -To lint everything, run from the top-level directory: - - > pylint vk - ... - > pylint bin - ... + pylint vk [Pylint]: https://www.pylint.org/ diff --git a/docs/mutual_friends.md b/docs/mutual_friends.md deleted file mode 100644 index 39ee76f..0000000 --- a/docs/mutual_friends.md +++ /dev/null @@ -1,46 +0,0 @@ -mutual_friends.py -================= - -Learn who your ex and her new boyfriend are both friends with. - -Usage ------ - -Run from the top-level directory using `python -m`: - - > python -m bin.mutual_friends -h - usage: mutual_friends.py [-h] [-f {csv,json}] [-o PATH] UID [UID ...] - ... - -For example (using made up user IDs/"screen names"), - - > python -m bin.mutual_friends john.doe jane.doe - 89497105,John,Smith - 3698577,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. - -The output format is CSV (comma-separated values) by default. -You can also get a JSON document: - - > python -m bin.mutual_friends --format json john.doe jane.doe - [ - { - "uid": 89497105, - "first_name": "John", - "last_name": "Smith" - }, - { - "uid": 3698577, - "first_name": "Jane", - "last_name": "Smith" - } - ] - -See also --------- - -* [License] - -[License]: ../README.md#license diff --git a/docs/mutuals.md b/docs/mutuals.md new file mode 100644 index 0000000..39ee76f --- /dev/null +++ b/docs/mutuals.md @@ -0,0 +1,46 @@ +mutual_friends.py +================= + +Learn who your ex and her new boyfriend are both friends with. + +Usage +----- + +Run from the top-level directory using `python -m`: + + > python -m bin.mutual_friends -h + usage: mutual_friends.py [-h] [-f {csv,json}] [-o PATH] UID [UID ...] + ... + +For example (using made up user IDs/"screen names"), + + > python -m bin.mutual_friends john.doe jane.doe + 89497105,John,Smith + 3698577,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. + +The output format is CSV (comma-separated values) by default. +You can also get a JSON document: + + > python -m bin.mutual_friends --format json john.doe jane.doe + [ + { + "uid": 89497105, + "first_name": "John", + "last_name": "Smith" + }, + { + "uid": 3698577, + "first_name": "Jane", + "last_name": "Smith" + } + ] + +See also +-------- + +* [License] + +[License]: ../README.md#license diff --git a/docs/online_sessions.md b/docs/online_sessions.md deleted file mode 100644 index 7c9d4d4..0000000 --- a/docs/online_sessions.md +++ /dev/null @@ -1,171 +0,0 @@ -online_sessions.py -================== - -View/visualize the amount of time people spend online. - -Usage ------ - -Run from the top-level directory using `python -m`: - -``` -> python -m bin.online_sessions -h -usage: online_sessions.py [-h] [-g {user,date,weekday,hour}] - [-i {csv,log,null}] [-o {csv,json,plot}] - [-a TIME_FROM] [-b TIME_TO] - [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): - -``` -> python -m bin.online_sessions 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: - -``` -> python -m bin.online_sessions --output-format json db.csv -[ - { - "uid": 89497105, - "first_name": "John", - "last_name": "Smith", - "domain": "john.smith", - "duration": "0:12:31" - }, - { - "uid": 3698577, - "first_name": "Jane", - "last_name": "Smith", - "domain": "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 `--group-by` -parameter value. -For example (assuming that both Jane and Joe spent their time online on Friday, -June 17, 2016). - -``` -> python -m bin.online_sessions --output-format json --group-by date db.csv -[ - { - "date": "2016-06-17", - "duration": "1:47:17" - } -] -``` - -``` -> python -m bin.online_sessions --output-format csv --group-by 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 -``` - -``` -> python -m bin.online_sessions --group-by 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 -``` - -In my opinion, the script's most useful feature is its ability to easily create -plots that represent this data (like in the examples above). -To produce a plot, pass `plot` as the `--output-format` parameter value and add -a file path to write the image to. - -``` -> python -m bin.online_sessions --output-format plot db.csv user.png -``` - -![user.png] - -``` -> python -m bin.online_sessions --output-format plot --group-by date db.csv date.png -``` - -![date.png] - -``` -> python -m bin.online_sessions --output-format plot --group-by weekday db.csv weekday.png -``` - -![weekday.png] - -``` -> python -m bin.online_sessions --output-format plot --group-by hour db.csv hour.png -``` - -![hour.png] - -You can limit the scope of the database by supplying a time range. -Only online sessions that overlap with this range shall then be processed. -Set the range by specifying both or one of the `--from` and `--to` parameters. -The values must be in the `%Y-%m-%dT%H:%M:%SZ` format (a subset of ISO 8601). - -All dates and times are in UTC. - -[matplotlib]: http://matplotlib.org/ -[track_status.py]: track_status.md - -[user.png]: images/user.png -[date.png]: images/date.png -[weekday.png]: images/weekday.png -[hour.png]: images/hour.png - -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. - -See also --------- - -* [License] - -[License]: ../README.md#license diff --git a/docs/sessions.md b/docs/sessions.md new file mode 100644 index 0000000..7c9d4d4 --- /dev/null +++ b/docs/sessions.md @@ -0,0 +1,171 @@ +online_sessions.py +================== + +View/visualize the amount of time people spend online. + +Usage +----- + +Run from the top-level directory using `python -m`: + +``` +> python -m bin.online_sessions -h +usage: online_sessions.py [-h] [-g {user,date,weekday,hour}] + [-i {csv,log,null}] [-o {csv,json,plot}] + [-a TIME_FROM] [-b TIME_TO] + [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): + +``` +> python -m bin.online_sessions 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: + +``` +> python -m bin.online_sessions --output-format json db.csv +[ + { + "uid": 89497105, + "first_name": "John", + "last_name": "Smith", + "domain": "john.smith", + "duration": "0:12:31" + }, + { + "uid": 3698577, + "first_name": "Jane", + "last_name": "Smith", + "domain": "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 `--group-by` +parameter value. +For example (assuming that both Jane and Joe spent their time online on Friday, +June 17, 2016). + +``` +> python -m bin.online_sessions --output-format json --group-by date db.csv +[ + { + "date": "2016-06-17", + "duration": "1:47:17" + } +] +``` + +``` +> python -m bin.online_sessions --output-format csv --group-by 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 +``` + +``` +> python -m bin.online_sessions --group-by 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 +``` + +In my opinion, the script's most useful feature is its ability to easily create +plots that represent this data (like in the examples above). +To produce a plot, pass `plot` as the `--output-format` parameter value and add +a file path to write the image to. + +``` +> python -m bin.online_sessions --output-format plot db.csv user.png +``` + +![user.png] + +``` +> python -m bin.online_sessions --output-format plot --group-by date db.csv date.png +``` + +![date.png] + +``` +> python -m bin.online_sessions --output-format plot --group-by weekday db.csv weekday.png +``` + +![weekday.png] + +``` +> python -m bin.online_sessions --output-format plot --group-by hour db.csv hour.png +``` + +![hour.png] + +You can limit the scope of the database by supplying a time range. +Only online sessions that overlap with this range shall then be processed. +Set the range by specifying both or one of the `--from` and `--to` parameters. +The values must be in the `%Y-%m-%dT%H:%M:%SZ` format (a subset of ISO 8601). + +All dates and times are in UTC. + +[matplotlib]: http://matplotlib.org/ +[track_status.py]: track_status.md + +[user.png]: images/user.png +[date.png]: images/date.png +[weekday.png]: images/weekday.png +[hour.png]: images/hour.png + +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. + +See also +-------- + +* [License] + +[License]: ../README.md#license diff --git a/docs/status.md b/docs/status.md new file mode 100644 index 0000000..8fe0746 --- /dev/null +++ b/docs/status.md @@ -0,0 +1,44 @@ +track_status.py +=============== + +Track when people go online/offline. + +Usage +----- + +Run from the top-level directory using `python -m`: + + > python -m bin.track_status -h + usage: track_status.py [-h] [-t SECONDS] [-l PATH] [-f {csv,log,null}] + [-o PATH] + UID [UID ...] + ... + +For example (using made up user IDs/"screen names"), + + > python -m bin.track_status 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 using +[online_sessions.py], specify the path to a database using the `--output` +parameter. +Be careful: if the file already exists, it will be overwritten! + +[online_sessions.py]: online_sessions.md + +See also +-------- + +* [License] + +[License]: ../README.md#license diff --git a/docs/track_status.md b/docs/track_status.md deleted file mode 100644 index 8fe0746..0000000 --- a/docs/track_status.md +++ /dev/null @@ -1,44 +0,0 @@ -track_status.py -=============== - -Track when people go online/offline. - -Usage ------ - -Run from the top-level directory using `python -m`: - - > python -m bin.track_status -h - usage: track_status.py [-h] [-t SECONDS] [-l PATH] [-f {csv,log,null}] - [-o PATH] - UID [UID ...] - ... - -For example (using made up user IDs/"screen names"), - - > python -m bin.track_status 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 using -[online_sessions.py], specify the path to a database using the `--output` -parameter. -Be careful: if the file already exists, it will be overwritten! - -[online_sessions.py]: online_sessions.md - -See also --------- - -* [License] - -[License]: ../README.md#license -- cgit v1.2.3