From 67de0e6962f7e0e4de1dc5c7128214b388bdab93 Mon Sep 17 00:00:00 2001 From: Glen Date: Mon, 5 Oct 2020 16:00:53 -0500 Subject: [PATCH 1/2] documentation --- docs/Makefile | 20 +++++++++++++ docs/make.bat | 35 ++++++++++++++++++++++ docs/source/apikey.rst | 25 ++++++++++++++++ docs/source/authentication.rst | 17 +++++++++++ docs/source/conf.py | 55 ++++++++++++++++++++++++++++++++++ docs/source/index.rst | 31 +++++++++++++++++++ docs/source/installation.rst | 13 ++++++++ docs/source/query.rst | 35 ++++++++++++++++++++++ docs/source/retrieve.rst | 9 ++++++ docs/source/transfers.rst | 48 +++++++++++++++++++++++++++++ 10 files changed, 288 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/apikey.rst create mode 100644 docs/source/authentication.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/installation.rst create mode 100644 docs/source/query.rst create mode 100644 docs/source/retrieve.rst create mode 100644 docs/source/transfers.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..6247f7e2 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/apikey.rst b/docs/source/apikey.rst new file mode 100644 index 00000000..2fb6aa32 --- /dev/null +++ b/docs/source/apikey.rst @@ -0,0 +1,25 @@ +Api Keys +============== + +Cuenca-python allows you to create, activate and deactivate api keys. +The example below shows you how to create an api key and how to disable the old one. + +.. code-block:: python + + import cuenca + + # Create new ApiKey + new = cuenca.ApiKey.create() + + # Have to use the new key to deactivate the old key + old_id = cuenca.session.auth[0] + cuenca.session.configure(new.id, new.secret) + cuenca.ApiKey.deactivate(old_id, 60) # revoke prior API key in an hour + + +Nota: +deactivate an ``ApiKey`` in a certain number of minutes. If minutes is +negative, the API will treat it the same as 0. You can't deactivate +the same key with which the client is configured, since that'd risk +locking you out. The deactivated key is returned so that you have the +exact deactivated_at time. diff --git a/docs/source/authentication.rst b/docs/source/authentication.rst new file mode 100644 index 00000000..f0b6114c --- /dev/null +++ b/docs/source/authentication.rst @@ -0,0 +1,17 @@ +Authentication +============== + +Configure the client +-------------------- + +Cuenca-python has configurations values, with sensible defaults. The authentication has a configure the credentials for the +client, the way to configure is to set the :file:`CUENCA_API_KEY` and :file:`CUENCA_API_SECRET` environment variables. +The client library will automatically configure based on the values of those variables. + +To configure manually: + +.. code-block:: python + + import cuenca + + cuenca.configure(api_key='PKxxxx', api_secret='yyyyyy') diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..54e7cbf4 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,55 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'cuenca-python' +copyright = '2020, Cuenca' +author = 'Cuenca' + +# The full version, including alpha/beta/rc tags +release = '0.3.2' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..dbd1a5cf --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,31 @@ +.. cuenca-python documentation master file, created by + sphinx-quickstart on Wed Sep 30 13:11:39 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Cuenca-python! +========================================= + +Welcome to cuenca-python's documentation. Cuenca-python is a client library that allows connecting to different Cuenca's services. +Get started with :doc:`installation` + + +User's Guide +------------ +.. toctree:: + :maxdepth: 2 + + + installation + +Usage +------------ +.. toctree:: + :maxdepth: 2 + + + authentication + transfers + retrieve + query + apikey diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 00000000..a7045db3 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,13 @@ +Installation +============ + +Install Cuenca-python +--------------------- + +Use the following command to install cuenca-python: + +.. code-block:: sh + + $ pip install cuenca + +cuenca-python is now installed. diff --git a/docs/source/query.rst b/docs/source/query.rst new file mode 100644 index 00000000..a99cfb48 --- /dev/null +++ b/docs/source/query.rst @@ -0,0 +1,35 @@ +Query by idempotency_key, account_number and status +--------------------------------------------------------------- + +Results are always returned in descending order of ``created_at`` + +the methods that can be used: + +* ``one()`` - returns a single result. Raises ``NoResultFound`` if there are no results and ``MultipleResultsFound`` if there are more than one. + +* ``first()`` - returns the first result or ``None`` if there aren't any. + +* ``all()`` - returns a generator of all matching results. Pagination is handled automatically as you iterate over the response. + +* ``count()`` - returns an integer with the count of the matching results. + + +You can use like this example: + +.. code-block:: python + + import cuenca + from cuenca.types import Status + + # find the unique transfer using the idempotency key + local_transfer_id = '078efdc20bab456285437309c4b75673' + transfer = cuenca.Transfer.one(idempotency_key=local_transfer_id) + + # returns a generator of all succeeded transfers to the specific account + transfers = cuenca.Transfer.all( + account_number='646180157000000004', + status=Status.succeeded + ) + + # the total number of succeeded transfers + count = cuenca.Transfer.count(status=Status.succeeded) diff --git a/docs/source/retrieve.rst b/docs/source/retrieve.rst new file mode 100644 index 00000000..a55b9337 --- /dev/null +++ b/docs/source/retrieve.rst @@ -0,0 +1,9 @@ +Retrieve by id +------------------- +The way for retrieve a transfer is with the ``id``, like this: + +.. code-block:: python + + import cuenca + + transfer = cuenca.Transfer.retrieve('tr_123') diff --git a/docs/source/transfers.rst b/docs/source/transfers.rst new file mode 100644 index 00000000..45707d6b --- /dev/null +++ b/docs/source/transfers.rst @@ -0,0 +1,48 @@ +Transfers +============== + +Create transfer +-------------------- +In cuenca-python you can create transfers, something like this: + +.. code-block:: python + + import cuenca + + cuenca.configure(sandbox=True) # if using sandbox + + local_transfer_id = '078efdc20bab456285437309c4b75673' + + transfer = cuenca.Transfer.create( + recipient_name='Benito Juárez', + account_number='646180157042875763', # CLABE or card number + amount=12345, # Mx$123.45 + descriptor='sending money', # As it'll appear for the customer + idempotency_key=local_transfer_id + ) + + # To get updated status + transfer.refresh() + + +You can enable sandbox if you using this. + +To create a transfer the following parameters are necessary: + +===================== ========================================== +``account_number:`` CLABE +``amount:`` needs to be in centavos (not pesos) +``descriptor:`` how it'll appear for the recipient +``recipient_name:`` name of recipient +``idempotency_key:`` must be unique for each transfer to avoid duplicates +===================== ========================================== + +The recommended idempotency_key scheme: + +1. Create a transfer entry in your own database with the status created. + + +2. Call this method with the unique id from your database as the ``idempotency_key``. + + +3. Update your database with the status created or submitted after receiving a response from this method. From 317fcb01a72f5f2c0945a49ebbb72df07de03126 Mon Sep 17 00:00:00 2001 From: Glen Date: Mon, 5 Oct 2020 16:06:10 -0500 Subject: [PATCH 2/2] add-sphinx --- requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements.txt b/requirements.txt index 1433a036..f0b176bf 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,3 +2,4 @@ requests==2.24.0 cuenca-validations==0.5.7 dataclasses>=0.7;python_version<"3.7" aws-requests-auth==0.4.3 +sphinx==3.2.1