Extend docs on PayPal subscriber report.

paypal_report.py

@@ -1,4 +1,11 @@
-"""Download subscriber info from PayPal.
+"""Download subscribers or subscriber transactions from PayPal.
+
+Used to help Conservancy keep track of Sustainers.
+
+Prints out either a list of recurring payment transactions or a list of unique
+recurring payment subscriber profiles. This recreates the features available in
+the previous PayPal SOAP API where you could query for all ProfileIDs
+(identifying unique subscribers).
 
 Run it like this:
 
@@ -7,6 +14,16 @@ $ export PAYPAL_CLIENT_SECRET=YYY
 $ python3 paypal_report.py profiles 2021-11-01T00:00:00-07:00 2021-11-30T23:59:59-07:00 > profiles.txt
 $ python3 paypal_report.py transactions 2021-11-01T00:00:00-07:00 2021-11-30T23:59:59-07:00 > transactions.txt
 
+The PayPal OAuth 2.0 client ID and secret can be obtained from the Developer
+Dashboard as described here: https://developer.paypal.com/api/rest/.
+
+This tool isn't directly related Beancount, but it may duplicate some
+functionality from the PayPal importer and paypal_rest tools, which I wasn't
+aware of at the time. See:
+
+ - conservancy_beancount/doc/PayPalQuery.md
+ - NPO-Accounting/paypal_rest
+
 """
 import argparse
 import collections
@@ -107,6 +124,12 @@ def get_transactions_for_period(access_token, start_date, end_date, page=1):
 
 
 def report_on_unique_profiles(transactions):
+    """Print a list of subscribers from a set of transactions.
+
+    PayPal doesn't provide a way to query for subscribers directly, so we build
+    this by scanning through the list of transactions and finding the unique
+    subscribers.
+    """
     records = set()
     for t in transactions:
         transaction_info = t['transaction_info']
@@ -128,6 +151,7 @@ def report_on_unique_profiles(transactions):
 
 
 def report_on_transactions(transactions):
+    """Print a formatted list of transactions."""
     for t in transactions:
         transaction_info = t['transaction_info']
         if 'paypal_reference_id' in transaction_info: