NPO-Accounting/paypal_rest
6
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

doc: Initial README and CODE.

Browse source
This commit is contained in:
Brett Smith 2020-11-19 12:01:21 -05:00
parent e51be066d0
commit 2319df1066
2 changed files with 58 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
CODE.rst Normal file
View file

@ -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.

41
README.rst Normal file
View file

@ -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.