Implemented --save option, closes #2

Also added usage instructions to README.

README.md

@@ -9,3 +9,36 @@ Create a SQLite database containing your checkin history from Foursquare Swarm.
 ## How to install
 
     $ pip install swarm-to-sqlite
+
+## Usage
+
+You will need to first obtain a valid OAuth token for your Foursquare account.
+
+Simplest usage is to simply provide the name of the database file you wish to write to. The tool will prompt you to paste in your token, and will then download your checkins and store them in the specified database file.
+
+    $ swarm-to-sqlite checkins.db
+    Please provide your Foursquare OAuth token:
+    Importing 3699 checkins  [#########-----------------------] 27% 00:02:31
+
+You can also pass the token as a command-line option:
+
+    $ swarm-to-sqlite checkins.db --token=XXX
+
+Or as an environment variable:
+
+    $ export FOURSQUARE_TOKEN=XXX
+    $ swarm-to-sqlite checkins.db
+
+In addition to saving the checkins to a database, you can also write them to a JSON file using the `--save` option:
+
+    $ swarm-to-sqlite checkins.db --save=checkins.json
+
+Having done this, you can re-import checkins directly from that file (rather than making API calls to fetch data from Foursquare) like this:
+
+    $ swarm-to-sqlite checkins.db --load=checkins.json
+
+## Using with Datasette
+
+The SQLite database produced by this tool is designed to be browsed using [Datasette](https://datasette.readthedocs.io/).
+
+You can install the [datasette-cluster-map](https://github.com/simonw/datasette-cluster-map) plugin to view your checkins on a map.

swarm_to_sqlite/cli.py

@@ -11,9 +11,17 @@
     type=click.Path(file_okay=True, dir_okay=False, allow_dash=False),
     required=True,
 )
-@click.option("-t", "--token", help="Foursquare OAuth token")
-@click.option("--load", help="Load checkins from this JSON file on disk")
-@click.option("--save", help="Save checkins to this JSON file on disk")
+@click.option("--token", envvar="FOURSQUARE_TOKEN", help="Foursquare OAuth token")
+@click.option(
+    "--load",
+    type=click.File(),
+    help="Load checkins from this JSON file on disk",
+)
+@click.option(
+    "--save",
+    type=click.File("w"),
+    help="Save checkins to this JSON file on disk",
+)
 @click.option("-s", "--silent", is_flag=True, help="Don't show progress bar")
 def cli(db_path, token, load, save, silent):
     "Save Swarm checkins to a SQLite database"
@@ -29,12 +37,15 @@ def cli(db_path, token, load, save, silent):
         checkins = fetch_all_checkins(token, count_first=True)
         checkin_count = next(checkins)
     else:
-        checkins = json.load(open(load))
+        checkins = json.load(load)
         checkin_count = len(checkins)
     db = sqlite_utils.Database(db_path)
+    saved = []
     if silent:
         for checkin in checkins:
             save_checkin(checkin, db)
+            if save:
+                saved.append(checkin)
     else:
         with click.progressbar(
             length=checkin_count,
@@ -45,5 +56,9 @@ def cli(db_path, token, load, save, silent):
             for checkin in checkins:
                 save_checkin(checkin, db)
                 bar.update(1)
+                if save:
+                    saved.append(checkin)
     ensure_foreign_keys(db)
     create_views(db)
+    if save:
+        json.dump(saved, save)

swarm_to_sqlite/utils.py

@@ -4,6 +4,8 @@
 
 
 def save_checkin(checkin, db):
+    # Create copy that we can modify
+    checkin = dict(checkin)
     if "venue" in checkin:
         venue = checkin.pop("venue")
         categories = venue.pop("categories")