Add helper / alias endpoints

Author: pyepye

README.md

@@ -138,6 +138,7 @@ paddle.refund_product_payment(order_id=1234, amount=0.01, reason='reason')
 
 # Subscription API
 paddle.list_plans()
+paddle.get_plan(plan=123)
 paddle.create_plan(
     plan_name='plan_name',
     plan_trial_days=14,
@@ -150,6 +151,19 @@ paddle.create_plan(
 paddle.list_subscription_users()
 paddle.cancel_subscription(subscription_id=1234)
 paddle.update_subscription(subscription_id=1234, pause=True)
+paddle.update_subscription(
+    subscription_id=1234,
+    quantity=10.00,
+    currency='USD',
+    recurring_price=10.00,
+    bill_immediately=False,
+    plan_id=123,
+    prorate=True,
+    keep_modifiers=True,
+    passthrough='passthrough',
+)
+paddle.pause_subscription(subscription_id=1234)
+paddle.resume_subscription(subscription_id=1234)
 paddle.preview_update_subscription(
     subscription_id=123,
     bill_immediately=True,
@@ -177,14 +191,12 @@ The below endpoints have been implimented but are not working correctly accordin
 
 * [Generate License](https://developer.paddle.com/api-reference/product-api/licenses/createlicense) - `Paddle error 108 - Unable to find requested product`
 * [Create pay link](https://developer.paddle.com/api-reference/product-api/pay-links/createpaylink) -  `Paddle error 108 - Unable to find requested product`
-* [Reschedule subscription payment](https://developer.paddle.com/api-reference/subscription-api/payments/updatepayment) -  `Paddle error 122 - Provided date is not valid`
+* [Reschedule subscription payment](https://developer.paddle.com/api-reference/subscription-api/payments/updatepayment) -  `Paddle error 122 - Provided date is not valid` - After manually testing via Paddles API reference I believe this is an issue with Paddle's API.
 
 
 ## ToDo
 * Fix generate license, create pay link and reschedule payment endpoints
-* Work out if we want to include 'alias' methods like pause_subscription
 * Get test coverage to 100%
-* Docs (auto docs?)
 * Use `pytest-mock` `Spy` to check params, json, urls etc for test requests
     * Needed to any tests which skip due to missing data
 * How to deal with the manual cleanup?

docs/api_reference.rst

@@ -3,6 +3,10 @@ API Reference
 
 Below is a :ref:`full list<Full reference>` of the Paddle Client methods. :ref:`Supported Paddle endpoints` lists the Paddle API endpoints in the same order as they are in the `Paddle API Reference <https://developer.paddle.com/api-reference>`_
 
+There are also several *helper* methods implimented on top of the Paddle endpoints to make usage of the API easier.
+
+For example the ``pause_subscription`` and ``resume_subscription`` methods have been added on top of ``update_subscription`` as to pause or resume a subscription the ``update_subscription`` endpoint is used but only the ``pause`` parameter can be set (and will fail if any others are).
+
 
 Supported Paddle endpoints
 --------------------------
@@ -27,11 +31,11 @@ As listed in the `Paddle API Reference <https://developer.paddle.com/api-referen
 
 **Subscription API**
 
-- :meth:`List Plans<paddle.PaddleClient.list_plans>`
+- :meth:`List Plans<paddle.PaddleClient.list_plans>` - (Including :meth:`Get Plan<paddle.PaddleClient.get_plan>`)
 - :meth:`Create Plan<paddle.PaddleClient.create_plan>`
 - :meth:`List Subscription Users<paddle.PaddleClient.list_subscription_users>`
 - :meth:`Cancel Subscription<paddle.PaddleClient.cancel_subscription>`
-- :meth:`Update Subscription<paddle.PaddleClient.update_subscription>`
+- :meth:`Update Subscription<paddle.PaddleClient.update_subscription>` - (Including :meth:`Pause Subscription<paddle.PaddleClient.pause_subscription>` and :meth:`Resume Subscription<paddle.PaddleClient.resume_subscription>`)
 - :meth:`Preview Subscription Update<paddle.PaddleClient.preview_subscription_update>`
 - :meth:`Add Modifier<paddle.PaddleClient.add_modifier>`
 - :meth:`Delete Modifier<paddle.PaddleClient.delete_modifier>`

paddle/_pay_links.py

@@ -44,11 +44,14 @@ def create_pay_link(
     `Create Pay Link Paddle docs <https://developer.paddle.com/api-reference/product-api/pay-links/createpaylink>`_
 
     product_id appears to be required:
-        Paddle error 108 - Unable to find requested product
+
+    Paddle error 108 - Unable to find requested product
+
+
     Even though the docs states:
-        "If no product_id is set, custom non-subscription product checkouts
-        can be generated instead by specifying title, webhook_url and prices."
-    https://developer.paddle.com/api-reference/product-api/coupons/createcoupon  # NOQA: E501
+
+    "If no product_id is set, custom non-subscription product checkouts
+    can be generated instead by specifying title, webhook_url and prices."
     """  # NOQA: E501
     url = urljoin(self.vendors_v2, 'product/generate_license')
 

paddle/_plans.py

@@ -19,14 +19,15 @@ def list_plans(self, plan: int = None) -> List[dict]:
     return self.post(url=url)
 
 
-# def get_plan(self, plan: int) -> dict:
-#     """
-#     `List Plans Paddle docs <https://developer.paddle.com/api-reference/subscription-api/plans/listplans>`_  # NOQA: E501
+def get_plan(self, plan: int) -> dict:
+    """
+    `List Plans Paddle docs <https://developer.paddle.com/api-reference/subscription-api/plans/listplans>`_
 
-#     There is no get_plan endpoint in Paddle's API. This is a convenient
-#     alias of the list plans endpoint where the Plan ID is required
-#     """  # NOQA: E501
-#     return self.list_plans(plan=plan)[0]
+    There is no Get Plan endpoint in Paddle's API but list plans does support
+    sending through a plan ID. This is a helper method to get a single plan
+    where the plan parameter is required.
+    """  # NOQA: E501
+    return self.list_plans(plan=plan)[0]
 
 
 def create_plan(

paddle/_subscription_users.py

@@ -36,30 +36,6 @@ def list_subscription_users(
     return self.post(url=url, json=json)
 
 
-# def list_subscriptions(self, **kwargs: dict) -> List[dict]:
-#     """
-#     `List Users (subscription) Paddle docs <https://developer.paddle.com/api-reference/subscription-api/subscription-users/listusers>`_  # NOQA: E501
-
-#     This is a convenient alias for list_subscription_users as while the
-#     other name matches the API name, it's not particularly guessable
-#     """ # NOQA: E501
-#     return self.list_subscription_users(**kwargs)
-
-
-# def get_subscription(self, subscription_id: int) -> dict:
-#     """
-#     `List Users (subscription) Paddle docs <https://developer.paddle.com/api-reference/subscription-api/subscription-users/listusers>`_  # NOQA: E501
-
-#     There is no get_subscription endpoint in Paddle's API, This is a
-#     convenient alias
-#     """  # NOQA: E501
-#     for subscription in self.list_subscription_users():
-#         if subscription['subscription_id'] == subscription_id:
-#             return subscription
-#     error = 'Unable to find subscription with id {0}'.format(subscription_id)
-#     raise ValueError(error)
-
-
 def cancel_subscription(
     self,
     subscription_id: int,
@@ -108,26 +84,26 @@ def update_subscription(
     return self.post(url=url, json=json)
 
 
-# def pause_subscription(self, subscription_id: int) -> dict:
-#     """
-#     `Update Subscription Paddle docs <https://developer.paddle.com/api-reference/subscription-api/subscription-users/updateuser`_  # NOQA: E501
+def pause_subscription(self, subscription_id: int) -> dict:
+    """
+    `Update Subscription Paddle docs <https://developer.paddle.com/api-reference/subscription-api/subscription-users/updateuser>`_
 
-#     There is no resume_subscription endpoint in Paddle's API. This is a
-#     convenient alias for update_subscription as no extra data can be sent
-#     when pausing/resuming subscriptions
-#     """  # NOQA: E501
-#     return self.update_subscription(subscription_id=subscription_id, pause=True)  # NOQA: E501
+    There is no Pause Subscription endpoint in Paddle's API. This is a
+    convenient helper method for update_subscription as no extra data can be
+    sent when pausing/resuming subscriptions
+    """  # NOQA: E501
+    return self.update_subscription(subscription_id=subscription_id, pause=True)  # NOQA: E501
 
 
-# def resume_subscription(self, subscription_id: int) -> dict:
-#     """
-#     `Update Subscription Paddle docs <https://developer.paddle.com/api-reference/subscription-api/subscription-users/updateuser`_  # NOQA: E501
+def resume_subscription(self, subscription_id: int) -> dict:
+    """
+    `Update Subscription Paddle docs <https://developer.paddle.com/api-reference/subscription-api/subscription-users/updateuser>`_
 
-#     There is no resume_subscription endpoint in Paddle's API. This is a
-#     convenient alias for update_subscription as no extra data can be sent
-#     when pausing/resuming subscriptions
-#     """  # NOQA: E501
-#     return self.update_subscription(subscription_id=subscription_id, pause=False)  # NOQA: E501
+    There is no Resume Subscription endpoint in Paddle's API. This is a
+    convenient helper method for update_subscription as no extra data can be
+    sent when pausing/resuming subscriptions
+    """  # NOQA: E501
+    return self.update_subscription(subscription_id=subscription_id, pause=False)  # NOQA: E501
 
 
 def preview_subscription_update(

paddle/paddle.py

@@ -179,12 +179,15 @@ def post(self, url, **kwargs):
     from ._product_payments import refund_product_payment
 
     from ._plans import list_plans
-    # from ._plans import get_plan
+    from ._plans import get_plan
     from ._plans import create_plan
 
     from ._subscription_users import list_subscription_users
+    from ._subscription_users import list_subscription_users as list_subscriptions  # NOQA: E501
     from ._subscription_users import cancel_subscription
     from ._subscription_users import update_subscription
+    from ._subscription_users import pause_subscription
+    from ._subscription_users import resume_subscription
     from ._subscription_users import preview_subscription_update
     # Alias to better match update_subscription
     from ._subscription_users import preview_subscription_update as preview_update_subscription  # NOQA: E501

pyproject.toml

@@ -3,7 +3,7 @@ name = "paddle-client"
 packages = [
     {include = "paddle"}
 ]
-version = "0.7.1"
+version = "0.8.0"
 description = "Python wrapper around the Paddle.com API"
 license = "MIT"
 authors = ["Matt Pye <pyematt@gmail.com>"]

tests/test_one_off_charges.py

@@ -14,8 +14,8 @@ def test_create_one_off_charge(mocker, paddle_client):  # NOQA: F811
     This test is mocked as creating a one off charge against Paddle will
     actually create a one of charge
 
-    If the below test fails it means a change has been made which has affected
-    the refund payment endpoint.
+    If this test fails it means a change has been made which has affected
+    the one-off charge endpoint.
 
     The code now needs to be run directly against Paddle's API at least once to
     ensure the new code is working as expected.

tests/test_plans.py

@@ -34,17 +34,17 @@ def test_list_plans_with_plan(paddle_client):  # NOQA: F811
     assert isinstance(plan['trial_days'], int)
 
 
-# def test_get_plan(paddle_client):  # NOQA: F811
-#     # ToDo: Create plan when API exists for it here
-#     plan_id = int(os.environ['PADDLE_TEST_DEFAULT_PLAN_ID'])
-#     plan = paddle_client.get_plan(plan=plan_id)
-#     assert plan['id'] == plan_id
-#     assert isinstance(plan['billing_period'], int)
-#     assert isinstance(plan['billing_type'], str)
-#     assert isinstance(plan['initial_price'], dict)
-#     assert isinstance(plan['name'], str)
-#     assert isinstance(plan['recurring_price'], dict)
-#     assert isinstance(plan['trial_days'], int)
+def test_get_plan(paddle_client):  # NOQA: F811
+    # ToDo: Create plan when API exists for it here
+    plan_id = int(os.environ['PADDLE_TEST_DEFAULT_PLAN_ID'])
+    plan = paddle_client.get_plan(plan=plan_id)
+    assert plan['id'] == plan_id
+    assert isinstance(plan['billing_period'], int)
+    assert isinstance(plan['billing_type'], str)
+    assert isinstance(plan['initial_price'], dict)
+    assert isinstance(plan['name'], str)
+    assert isinstance(plan['recurring_price'], dict)
+    assert isinstance(plan['trial_days'], int)
 
 
 @pytest.mark.manual_cleanup

tests/test_product_payments.py

@@ -11,8 +11,8 @@ def test_refund_product_payment(mocker, paddle_client):  # NOQA: F811
     This test is mocked as creating a refund is not something you want to
     happen against a live system.
 
-    If the below test fails it means a change has been made which has affected
-    the refund payment endpoint.
+    If this test fails it means a change has been made which has affected
+    the refund product payment endpoint.
 
     The code now needs to be run directly against Paddle's API at least once to
     ensure the new code is working as expected.