The Paayes Python library provides convenient access to the Paayes API from applications written in the Python language. It includes a pre-defined set of classes for API resources that initialize themselves dynamically from API responses which makes it compatible with a wide range of versions of the Paayes API.
See the Python API docs.
See video demonstrations covering how to use the library.
You don't need this source code unless you want to modify the package. If you just want to use the package, just run:
pip install --upgrade paayes
Install from source with:
python setup.py install
- Python 2.7+ or Python 3.4+ (PyPy supported)
The library needs to be configured with your account's secret key which is
available in your Paayes Dashboard. Set paayes.api_key
to its
value:
import paayes
paayes.api_key = "sk_test_..."
# list customers
customers = paayes.Customer.list()
# print the first customer's email
print(customers.data[0].email)
# retrieve specific Customer
customer = paayes.Customer.retrieve("cus_123456789")
# print that customer's email
print(customer.email)
Unsuccessful requests raise exceptions. The class of the exception will reflect the sort of error that occurred. Please see the Api Reference for a description of the error classes you should handle, and for information on how to inspect these errors.
Configure individual requests with keyword arguments. For example, you can make requests with a specific Paayes Version or as a connected account:
import paayes
# list customers
paayes.Customer.list(
api_key="sk_test_...",
paayes_account="acct_...",
paayes_version="2019-02-19"
)
# retrieve single customer
paayes.Customer.retrieve(
"cus_123456789",
api_key="sk_test_...",
paayes_account="acct_...",
paayes_version="2019-02-19"
)
The library can be configured to use urlfetch
, requests
, pycurl
, or
urllib2
with paayes.default_http_client
:
client = paayes.http_client.UrlFetchClient()
client = paayes.http_client.RequestsClient()
client = paayes.http_client.PycurlClient()
client = paayes.http_client.Urllib2Client()
paayes.default_http_client = client
Without a configured client, by default the library will attempt to load
libraries in the order above (i.e. urlfetch
is preferred with urllib2
used
as a last resort). We usually recommend that people use requests
.
A proxy can be configured with paayes.proxy
:
paayes.proxy = "https://user:pass@example.com:1234"
You can enable automatic retries on requests that fail due to a transient problem by configuring the maximum number of retries:
paayes.max_network_retries = 2
Various errors can trigger a retry, like a connection error or a timeout, and
also certain API responses like HTTP status 409 Conflict
.
Idempotency keys are automatically generated and added to requests, when not given, to guarantee that retries are safe.
The library can be configured to emit logging that will give you better insight
into what it's doing. The info
logging level is usually most appropriate for
production use, but debug
is also available for more verbosity.
There are a few options for enabling it:
-
Set the environment variable
PAAYES_LOG
to the valuedebug
orinfo
$ export PAAYES_LOG=debug
-
Set
paayes.log
:import paayes paayes.log = 'debug'
-
Enable it through Python's logging module:
import logging logging.basicConfig() logging.getLogger('paayes').setLevel(logging.DEBUG)
If you're writing a plugin that uses the library, we'd appreciate it if you
identified using paayes.set_app_info()
:
paayes.set_app_info("MyAwesomePlugin", version="1.2.34", url="https://myawesomeplugin.info")
This information is passed along when the library makes calls to the Paayes API.
By default, the library sends request latency telemetry to Paayes. These numbers help Paayes improve the overall latency of its API for all users.
You can disable this behavior if you prefer:
paayes.enable_telemetry = False
The test suite depends on paayes-mock, so make sure to fetch and run it from a background terminal (paayes-mock's README also contains instructions for installing via Homebrew and other methods):
go get -u github.com/paayes/paayes-mock
paayes-mock
Run the following command to set up the development virtualenv:
make
Run all tests on all supported Python versions:
make test
Run all tests for a specific Python version (modify -e
according to your Python target):
TOX_ARGS="-e py37" make test
Run all tests in a single file:
TOX_ARGS="-e py37 -- tests/api_resources/abstract/test_updateable_api_resource.py" make test
Run a single test suite:
TOX_ARGS="-e py37 -- tests/api_resources/abstract/test_updateable_api_resource.py::TestUpdateableAPIResource" make test
Run a single test:
TOX_ARGS="-e py37 -- tests/api_resources/abstract/test_updateable_api_resource.py::TestUpdateableAPIResource::test_save" make test
Run the linter with:
make lint
The library uses Black for code formatting. Code must be formatted with Black before PRs are submitted, otherwise CI will fail. Run the formatter with:
make fmt