Merge pull request #31 from hughrun/v2

V2 changes

.gitignore

@@ -1 +1,4 @@
-settings.py
+settings.py
+schedule.sh 
+week.plist 
+day.plist

README.md

@@ -1,17 +1,23 @@
 # pocket-snack
 When your Pocket list is overwhelming, pocket-snack lets you see just what you can read today
 
-Each time the `refresh` command runs, it moves everything in `My List` to `Archive` with a particular tag, then randomly selects X number of items with that tag to go back into `My List` so that instead of an overwhelming number of things to be read, you just have the number you can comfortably expect to read per cycle (day, week etc).
+## A note on version 2
 
-This is a work in progress, but all functions described here should be working.
+All commands have changed since version 1 - read the _Usage_ section carefully. This was necessary in order to provide better functionality without making the code too confusing.
+
+One of the changes is that the `refresh` command from version 1 no longer exists. This is so that `--since`, and `--before` can be used with both `--stash` and `lucky_dip`. If you want replicate `refresh` you simply need to run `--stash` followed by `--lucky_dip`. From the command line you could do:
+```bash
+pocketsnack -s && pocketsnack -d
+```
+The automation of `pocketsnack refresh` has _also_ been removed. This didn't really work very consistently, and was causing a lot of maintenance headaches. I'm looking at how to bring it back in a different way, but for now it's been removed.
 
 ## Getting started
 
-### tl;dr
+### Quick version
 
-1. install python 3 and the _requests_ module
+1. make sure you have installed Python 3 and it is callable with `python3`
 2. copy `settings-example.py` to `settings.py`
-3. create Pocket app and paste consumer key into settings.py
+3. create Pocket app and paste consumer key into `settings.py`
 4. run `bash install.sh` and follow the prompts
 
 ### Dependencies
@@ -20,7 +26,7 @@ You will need Python 3.x installed and it must be called by `python3`, rather th
 
 On MacOS the easiest thing to do is to [install Python 3 using Homebrew](https://docs.brew.sh/Homebrew-and-Python): `brew install python`.
 
-Then install the Python **requests** module using **pip**: `pip3 install requests`
+The install script should install the `requests` module for you when you run `bash install.sh`. If you prefer, you can install it manually using **pip**: `pip3 install requests`
 
 ### Settings
 
@@ -37,71 +43,101 @@ You can adjust most settings, but the defaults in **settings-example.py** should
 
 ### Pocket access token
 
-Pocket uses OAuth to confirm that your app has permission from your user account to do stuff in your account. This means you need to authorise the app before you can do anything else. Once you have copied you app consumer key into settings.py, when you run the `install.sh` bash script, this will run `authorise` for you. If you are doing everything manually you should run `pocketsnack authorise` to get your token (see below).
+Pocket uses OAuth to confirm that your app has permission from your user account to do stuff in your account. This means you need to authorise the app before you can do anything else. Once you have copied you app consumer key into settings.py, when you run the `install.sh` bash script, this will run `authorise` for you. If you prefer to install manually, or want to change the Pocket account details, you should run `pocketsnack --authorise` to get your token (see below).
 
 You should now have a line at the bottom of settings.py saying something like `pocket_access_token = 'aa11bb-zz9900xx'`
 
 ## Usage
 
-For most users you simply need to run `install.sh` and then forget about it. The install script will ask a series of questions, authorise your app, and optionally set up a daily or weekly task to refresh your list. On MacOS this is done via **launchd** and on Linux via **cron**. If you want to use cron instead of launchd on Mac, just choose 'Linux' when asked - but I wouldn't recommend it (read on for why).
+To run commands, use `pocketsnack [command]`.
+
+### -h, --help
+
+Outputs help for each command
+
+## admin commands
+
+### -t, --test
+
+Outputs the first article returned by a call to the API. Normally you will never need to use this.
+
+### -u, --authorise
+
+This command has an 's', not a 'z', and the short version is a 'u', not an 'a'.
+
+You need this to authorise your app. This command is automatically run by `install.sh`. Everything else works exclusively on the command line, but _authorise_ needs to open a browser to complete the authorisation process, so you need to run this on a machine with a web browser. It will authorise your app with your user, wait for you to confirm that you have completed the authorisation (by typing 'done') and then add the token to `settings.py`. Use it if you want to change the Pocket account you are using with pocketsnack.
+
+## action commands
 
-In both cases, `pocketsnack refresh` will run at the specified time. In the case of **cron**, this will only happen if the machine is up and logged on - e.g. a server. In the case of **launchd**, the script will be associated with your user account. If your machine is sleeping or your account logged out at the scheduled time, it will run immediately when you wake the machine up or log in. This allows you to set it for, e.g. 5am and be confident that when you open your Macbook at 7am the script will run and your Pocket account will refresh.
+### -d, --lucky_dip
 
-If you use launchd, log files for stdout and errors will be created wherever you saved _pocketsnack_.
+Returns items with the archive tag from the archive to the list, and removes the archive tag. The number of items returned is determined by `items_per_cycle` in `settings.py`. Note that if `num_videos` and `num_images` add up to more than `items_per_cycle`, _lucky_dip_ will only return the total specified in `items_per_cycle`. Videos take precedence.
 
-To run commands manually, use `pocketsnack [command]`.
+### -p, --purge
 
-## commands
+You can use **purge_tags** to clear all tags in your List, Archive, or both, excluding the `archive_tag` and any `retain_tags`. This is useful if you've been using the Aus GLAM Blogs Pocket tool or anything else that retains the original tags from articles.
+
+`--purge` requires a second argument: `--list`, `--archive`, or `--all`, depending on where you want to purge tags.
+
+**NOTE** that by design, `--purge` will process **all** items in your archive, not just items with the `archive_tag`. This may lead to miss-matches between the number returned by `--info --archive` and the number of items processed by `--purge --archive`.
 
-### archive
+### -s, --stash
 
-This tells you how many items are in your archive and how many of them are 'long reads'. You can set the wordcount defining a long read in `settings.py`.
+Adds the archive tag to everything in your list, and then archives them. Depending on the value of `ignore_faves` and `ignore_tags` in `settings.py`, and any before/since values, some items may be excluded and remain in the List.
 
-### authorise
+## optional flags
 
-This has an 's', not a 'z'.
+### -a, --archive
 
-You need this to authorise your app. Everything else works exclusively on the command line, but _authorise_ needs to open a browser to complete the authorisation process, so you need to run this on a machine with a web browser. It will authorise your app with your user, wait for you to confirm that you have completed the authorisation (by typing 'done') and then add the token to `settings.py`.
+Used in combination with `--info`, this tells you how many items are in your archive and how many of them are 'long reads'. You can set the wordcount defining a long read in `settings.py`. Used with `--purge`, it purges tags on items in the archive.
 
-### list
+### -l, --list
 
 Same as _archive_ but for your list instead of your archive.
 
-### lucky_dip
+### -b, -all
 
-Returns items from the archive to the list, and removes the archive tag. The number of items returned is determined by `items_per_cycle` in `settings.py`. Note that if `num_videos` and `num_images` add up to more than `items_per_cycle`, _lucky_dip_ will only return the total specified in `items_per_cycle`. Videos take precedence.
+For use with `--purge` - purge tags from _both_ the List and the Archive.
 
-### purge_tags
+### -n, --since SINCE
 
-You can use **purge_tags** to clear all tags in your List, Archive, or both, excluding the `archive_tag` and any `retain_tags`. This is useful if you've been using the Aus GLAM Blogs Pocket tool or anything else that retains the original tags from articles.
+Restrict the current _action command_ to only items updated more recently than _SINCE_ number of days.
 
-`purge_tags` requires a second argument: `list`, `archive`, or `all`, depending on where you want to purge tags.
+### -o, --before BEFORE
 
-### refresh
+Restrict the current _action command_ to only items updated less recently than _BEFORE_ number of days.
 
-Runs `stash` followed by `lucky_dip`. This is the command that is run by launchd or cron if you set it up using `install.sh`.
+## examples
 
-### stash
+Stash only items updated in the last 2 days:  
 
-Adds the archive tag to everything in your list, and then archives them. Depending on the value of `ignore_faves` and `ignore_tags` in `settings.py` some items may remain in the List.
+`pocketsnack --stash -n 2`
 
-## Uninstalling
+Stash only items NOT updated in the last 7 days:  
 
-Don't like _pocket-snack_ any more or want to re-install it in a new directory? No problem, you will just need to do a little maintenance:
+`pocketsnack --stash -o 7`
 
-1. If you set up `refresh` on a Mac you should unload the plist file:
+Purge tags on all items in the List that were updated in the last day:
 
-   `launchctl unload ~/Library/LaunchAgents/com.getpocket.pocketsnack.plist`
+`pocketsnack -pln 1`
 
-2. Once unloaded, you can delete it:
+Run lucky_dip:
 
-   `rm ~/Library/LaunchAgents/com.getpocket.pocketsnack.plist`
+`pocketsnack --lucky_dip`
+
+Run lucky_dip but only choose from items last updated longer ago than one week:
+
+`pocketsnack -d -o 7`
+
+## Uninstalling or moving to a new directory
+
+Don't like _pocket-snack_ any more or want to re-install it in a new directory? No problem, you will just need to do a little maintenance:
 
-3. Delete the executable link - if you don't do this when re-installing in a different directory, running `pocketsnack` will fail because it will still be pointing at the old directory.
+1. Delete the executable link - if you don't do this when re-installing in a different directory, running `pocketsnack` will fail because it will still be pointing at the old directory.
 
    `rm /usr/local/bin/pocketsnack`
 
-Now you can safely delete the pocket-snack directory.
+2. Now you can safely delete the pocket-snack directory.
 
 ## Bugs and suggestions