doc: Initial README and CODE.

CODE.rst

@@ -0,0 +1,17 @@
+Code Overview
+=============
+
+This document gives a quick overview of the structure of the ``paypal_rest`` code.
+
+``client.py`` is the heart of the library. This is the code that takes Python data, constructs a API request from it, sends it to PayPal, and then turns the result back into Python data.
+
+There are separate modules to provide higher-level interfaces to those results. Right now there's just ``transaction.py``, which knows how to traverse the JSON result; convert data types like datetimes and amounts to native Python data structures; and so on.
+
+Adding support for more of the API should follow this pattern: add method(s) to ``client.PayPalAPIClient``, and have them return rich data structures from a corresponding submodule.
+
+The ``paypal-query`` tool is implemented in ``cliquery.py``. Other submodules like ``cliutil.py`` and ``config.py`` support it.
+
+Running tests
+-------------
+
+Run ``./setup.py test`` to run unit tests. Run ``./setup.py typecheck`` to run the type checker. Run ``tox`` to run both on all supported Pythons.

README.rst

@@ -0,0 +1,41 @@
+paypal_rest
+===========
+
+Introduction
+------------
+
+``paypal_rest`` is a library to wrap PayPal's REST interface. In late 2020, most Python libraries for the PayPal API are focused on charging customers. This library is focused on getting information about past charges and customers.
+
+paypal-query tool
+-----------------
+
+This library includes a command line tool, ``paypal-query``, to quickly get information from the API; provide an illustration of using the library; and help with debugging. To use it, first write a configuration file ``~/.config/paypal_rest/config.ini`` with your client credentials from PayPal::
+
+  [query]
+  client_id = ...
+  client_secret = ...
+  ; site can 'live', 'sandbox', or an API endpoint URL
+  site = live
+
+To see an overview of transactions over a time period::
+
+  paypal-query [--begin DATETIME] [--end DATETIME]
+
+Specify all datetimes in ISO8601 format: ``YYYY-MM-DDTHH:MM:SS``. You can omit any part of the time, or the whole thing. You can also add a timezone offset, like ``-04:00`` or ``+01:00``, or ``Z`` for UTC.
+
+To see details of a specific transaction or subscription::
+
+  paypal-query [--end DATETIME] PAYPALID1234ABCD0 [...]
+
+The PayPal API does not let you look up an individual transaction by ID; you have to search through 30-day time windows. The tool will automatically search backwards through time to find your result, but specifying the latest date to search from with the ``--end`` option can speed up the search significantly.
+
+Library quickstart
+------------------
+
+Create a ``paypal_rest.client.PayPalAPIClient`` using one of the classmethod constructors, then call its methods and handle the results::
+
+  config = configparser.ConfigParser()
+  config.read(os.path.expanduser('~/.config/paypal_rest/config.ini'))
+  paypal = paypal_rest.client.PayPalAPIClient.from_config(config['query'])
+  for txn in paypal.iter_transactions(start_date, end_date):
+    ...  # txn is a paypal_rest.transaction.Transaction object you can query.