From 45cb944c9d64fc93e6d89865bd2b96a5eaa71521 Mon Sep 17 00:00:00 2001
From: Bryan Newbold <bnewbold@archive.org>
Date: Fri, 24 Aug 2018 12:58:29 -0700
Subject: update READMEs

---
 python/README.md | 52 ++++++++++++++++++++++++++++++----------------------
 1 file changed, 30 insertions(+), 22 deletions(-)

(limited to 'python/README.md')

diff --git a/python/README.md b/python/README.md
index aebc160..5c83908 100644
--- a/python/README.md
+++ b/python/README.md
@@ -3,9 +3,20 @@ Hadoop streaming map/reduce jobs written in python using the mrjob library.
 
 ## Development and Testing
 
-System dependencies in addition to `../README.md`:
+System dependencies on Linux (ubuntu/debian):
 
-- `libjpeg-dev` (for wayback libraries)
+    sudo apt install -y python3-dev python3-pip python3-wheel libjpeg-dev build-essential
+    pip3 install --user pipenv
+
+On macOS (using Homebrew):
+
+    brew install libjpeg pipenv
+
+You probably need `~/.local/bin` on your `$PATH`.
+
+Fetch all python dependencies with:
+
+    pipenv install --dev
 
 Run the tests with:
 
@@ -16,10 +27,19 @@ Check test coverage with:
     pytest --cov --cov-report html
     # open ./htmlcov/index.html in a browser
 
-TODO: Persistant GROBID and HBase during development? Or just use live
-resources?
+## Running Python Jobs on Hadoop
+
+The `../please` script automates these steps; you should use that instead.
 
-## Extraction Task
+When running python streaming jobs on the actual hadoop cluster, we need to
+bundle along our python dependencies in a virtual env tarball. Building this
+tarball can be done like:
+
+    export PIPENV_VENV_IN_PROJECT=1
+    pipenv install --deploy
+    tar -czf venv-current.tar.gz -C .venv ."""
+
+### Extraction Task
 
 An example actually connecting to HBase from a local machine, with thrift
 running on a devbox and GROBID running on a dedicated machine:
@@ -30,13 +50,7 @@ running on a devbox and GROBID running on a dedicated machine:
         --grobid-uri http://wbgrp-svc096.us.archive.org:8070 \
         tests/files/example.cdx
 
-Running from the cluster:
-
-    # Create tarball of virtualenv
-    export PIPENV_VENV_IN_PROJECT=1
-    pipenv shell
-    export VENVSHORT=`basename $VIRTUAL_ENV`
-    tar -czf $VENVSHORT.tar.gz -C /home/bnewbold/.local/share/virtualenvs/$VENVSHORT .
+Running from the cluster (once a ./venv-current.tar.gz tarball exists):
 
     ./extraction_cdx_grobid.py \
         --hbase-table wbgrp-journal-extract-0-qa \
@@ -44,10 +58,10 @@ Running from the cluster:
         --grobid-uri http://wbgrp-svc096.us.archive.org:8070 \
         -r hadoop \
         -c mrjob.conf \
-        --archive $VENVSHORT.tar.gz#venv \
+        --archive venv-current.tar.gz#venv \
         hdfs:///user/bnewbold/journal_crawl_cdx/citeseerx_crawl_2017.cdx
 
-## Backfill Task
+### Backfill Task
 
 An example actually connecting to HBase from a local machine, with thrift
 running on a devbox:
@@ -57,18 +71,12 @@ running on a devbox:
         --hbase-host wbgrp-svc263.us.archive.org \
         tests/files/example.cdx
 
-Actual invocation to run on Hadoop cluster (running on an IA devbox, where
-hadoop environment is configured):
-
-    # Create tarball of virtualenv
-    export PIPENV_VENV_IN_PROJECT=1
-    pipenv install --deploy
-    tar -czf venv-current.tar.gz -C .venv .
+Running from the cluster (once a ./venv-current.tar.gz tarball exists):
 
     ./backfill_hbase_from_cdx.py \
         --hbase-host wbgrp-svc263.us.archive.org \
         --hbase-table wbgrp-journal-extract-0-qa \
         -r hadoop \
         -c mrjob.conf \
-        --archive $VENVSHORT.tar.gz#venv \
+        --archive venv-current.tar.gz#venv \
         hdfs:///user/bnewbold/journal_crawl_cdx/citeseerx_crawl_2017.cdx
-- 
cgit v1.2.3