paddle-python-sdk 0.2.2__tar.gz → 0.3.0__tar.gz

paddle_python_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.1
+Name: paddle-python-sdk
+Version: 0.3.0
+Summary: Paddle's Python SDK for Paddle Billing
+Home-page: https://developer.paddle.com/api-reference/overview
+Author: Paddle and contributors
+Author-email: team-dx@paddle.com
+License: Apache-2.0
+Keywords: paddle,sdk,python
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Requires-Dist: urllib3>=1.26.18
+Provides-Extra: dev
+Requires-Dist: pytest<8.4.0,>=7.4.4; extra == "dev"
+Requires-Dist: pytest-cov~=4.1.0; extra == "dev"
+Requires-Dist: requests-mock~=1.11.0; extra == "dev"
+Requires-Dist: setuptools>=69.0.3; extra == "dev"
+Requires-Dist: pre-commit>=3.8.0; extra == "dev"
+Requires-Dist: black>=24.8.0; extra == "dev"
+Requires-Dist: flake8>=7.1.1; extra == "dev"
+
+[![Build Status](https://img.shields.io/github/actions/workflow/status/PaddleHQ/paddle-python-sdk/publish_to_pypi.yml)](https://github.com/PaddleHQ/paddle-python-sdk/actions/?query=branch%3Amain)
+[![PyPI](https://img.shields.io/pypi/v/paddle-python-sdk.svg)](https://pypi.python.org/pypi/paddle-python-sdk)
+[![PyPI pyversions](https://img.shields.io/pypi/pyversions/paddle-python-sdk.svg)](https://pypi.python.org/pypi/paddle-python-sdk/)
+[![License: Apache 2.0](https://img.shields.io/github/license/PaddleHQ/paddle-python-sdk)](http://www.apache.org/licenses/LICENSE-2.0)
+
+
+# paddle-python-sdk
+[Paddle Billing](https://www.paddle.com/billing?utm_source=dx&utm_medium=paddle-python-sdk) is a complete digital product sales and subscription management platform, designed for modern software businesses. It helps you increase your revenue, retain customers, and scale your operations.
+
+This is a [Python](https://www.python.org/) SDK that you can use to integrate Paddle Billing with applications written in Python.
+
+For working with Paddle in your frontend, use [Paddle.js](https://developer.paddle.com/paddlejs/overview?utm_source=dx&utm_medium=paddle-python-sdk). You can open checkouts, securely collect payment information, build pricing pages, and integrate with Paddle Retain.
+
+> **Important:** This package works with Paddle Billing. It does not support Paddle Classic. To work with Paddle Classic, see: [Paddle Classic API reference](https://developer.paddle.com/classic/api-reference/1384a288aca7a-api-reference?utm_source=dx&utm_medium=paddle-python-sdk)
+
+
+## Table of contents
+- [Requirements](#Requirements)
+- [Install](#Install)
+- [Usage](#Usage)
+- [Examples](#Examples)
+- [Resources](#Resources)
+
+## Requirements
+Python>=3.11 (for native type hinting, StrEnum, trailing commas, f-strings)
+
+**Project dependencies** (automatically installed by pip):
+- requests>=2.31
+- urllib3>=2.1.0
+
+
+## Install
+Because `paddle-python-sdk` is [available on PyPi](https://pypi.org/project/paddle-python-sdk/), installation is as simple as running the following `pip` command: 
+
+`pip install paddle-python-sdk`
+
+
+
+## Usage
+To authenticate, you'll need an API key. You can create and manage API keys in **Paddle > Developer tools > Authentication**.
+
+Pass your API key while initializing a new Paddle client:
+``` python
+from paddle_billing import Client
+
+paddle = Client('PADDLE_API_SECRET_KEY')
+```
+
+You can pass your Paddle API secret key into the SDK from an environment variable:
+``` python
+from os             import getenv
+from paddle_billing import Client
+
+paddle = Client(getenv('PADDLE_API_SECRET_KEY'))
+```
+
+You can also pass an environment to work with Paddle's sandbox:
+``` python
+from paddle_billing import Client, Environment, Options
+
+paddle = Client('PADDLE_API_SECRET_KEY', options=Options(Environment.SANDBOX))
+```
+
+Keep in mind that API keys are separate for your sandbox and live accounts, so you'll need to generate keys for each environment.
+
+
+
+## Examples
+There are examples included in the [examples folder](https://github.com/PaddleHQ/paddle-python-sdk/tree/main/examples). To prevent leaking errors we recommend encapsulating Paddle operations inside Try/Except blocks. For brevity, most of the examples below do not do this.
+
+### List entities
+You can list supported entities with the `list()` method in the resource. It returns an iterator to help when working with multiple pages.
+``` python
+from paddle_billing import Client
+
+paddle = Client('PADDLE_API_SECRET_KEY')
+
+products = paddle.products.list()
+
+# list() returns an iterable, so pagination is automatically handled
+for product in products:
+    print(f"Product's id: {product.id}")
+```
+
+### Get an entity
+You can get an entity with the `get()` method in the resource. It accepts the `id` of the entity to get. The entity is returned.
+``` python
+from paddle_billing import Client
+
+paddle = Client('PADDLE_API_SECRET_KEY')
+
+product = paddle.products.get('PRODUCT_ID')
+```
+
+### Create an entity
+You can create a supported entity with the `create()` method in the resource. It accepts the resource's corresponding `CreateOperation` e.g. `CreateProduct`. The created entity is returned.
+
+``` python
+from paddle_billing                               import Client
+from paddle_billing.Entities.Shared.TaxCategory   import TaxCategory
+from paddle_billing.Resources.Products.Operations import CreateProduct
+
+paddle = Client('PADDLE_API_SECRET_KEY')
+
+created_product = paddle.products.create(CreateProduct(
+    name         = 'My Product',
+    tax_category = TaxCategory.Standard,
+))
+```
+
+### Update an entity
+You can update a supported entity with the `update()` method in the resource. It accepts the `id` of the entity to update and the corresponding `UpdateOperation` e.g. `UpdateProduct`. The updated entity is returned.
+``` python
+from paddle_billing                        import Client
+from paddle_billing.Resources.Products.Operations import UpdateProduct
+
+paddle = Client('PADDLE_API_SECRET_KEY')
+
+# Update the name of the product
+updated_product = paddle.products.update('PRODUCT_ID', UpdateProduct(
+    name = 'My Improved Product'
+))
+```
+
+Where operations require more than one `id`, the `update()` method accepts multiple arguments. For example, to update an address for a customer, pass the `customerId` and the `addressId`:
+``` python
+updated_address = paddle.addresses.update(
+    'CUSTOMER_ID',
+    'ADDRESS_ID',
+    operation_goes_here,
+)
+```
+
+### Delete an entity
+You can delete an entity with the `delete()` method in the resource. It accepts the `id` of the entity to delete. The deleted entity is returned.
+``` python
+from paddle_billing import Client
+
+paddle = Client('PADDLE_API_SECRET_KEY')
+
+deleted_product = paddle.products.delete('PRODUCT_ID')
+```
+
+
+## Resources
+
+### Webhook signature verification
+The SDK includes a helper class to verify webhook signatures sent by Notifications from Paddle.
+
+``` python
+from paddle_billing.Notifications import Secret, Verifier
+
+integrity_check = Verifier().verify(request, Secret('WEBHOOK_SECRET_KEY'))
+```
+
+## Learn more
+- [Paddle API reference](https://developer.paddle.com/api-reference/overview?utm_source=dx&utm_medium=paddle-python-sdk)
+- [Sign up for Paddle Billing](https://login.paddle.com/signup?utm_source=dx&utm_medium=paddle-python-sdk)

paddle_python_sdk-0.3.0/examples/catalog_management.py

@@ -0,0 +1,175 @@
+from logging import getLogger
+from os import getenv
+from sys import exit  # You should use classes/functions that returns instead of exits
+
+from paddle_billing import Client, Environment, Options
+
+from paddle_billing.Entities.Shared import (
+    CountryCode,
+    CurrencyCode,
+    CustomData,
+    Duration,
+    Money,
+    PriceQuantity,
+    UnitPriceOverride,
+    Interval,
+    Status,
+    TaxCategory,
+)
+
+from paddle_billing.Exceptions.ApiError import ApiError
+
+from paddle_billing.Resources.Prices.Operations import CreatePrice, UpdatePrice, PriceIncludes
+from paddle_billing.Resources.Products.Operations import CreateProduct, UpdateProduct, ProductIncludes, ListProducts
+
+log = getLogger("my_app")
+
+# Verify your Paddle API key was provided by a PADDLE_SECRET_API_KEY environment variable
+# It is strongly advised that you do not include secrets in your source code
+# Use environment variables, and/or secrets management like Vault to obtain your secrets
+api_key: str = getenv("PADDLE_SECRET_API_KEY", None)
+if not api_key:
+    raise ValueError("You must provide the PADDLE_SECRET_API_KEY in your environment variables")
+
+# Determine the environment, defaulting to sandbox
+environment = Environment(getenv("PADDLE_ENVIRONMENT", "sandbox"))
+
+# Initialize the Paddle client
+paddle = Client(api_key, options=Options(environment), logger=log)
+
+
+# ┌───
+# │ Create Product │
+# └────────────────┘
+try:
+    product = paddle.products.create(
+        CreateProduct(
+            name="Kitten Service",
+            tax_category=TaxCategory.Standard,
+            description="Simply an awesome product",
+            image_url="https://placekitten.com/200/300",
+            custom_data=CustomData({"foo": "bar"}),
+        )
+    )
+except ApiError as error:
+    print(error)
+    exit(1)
+
+print(f"Created product '{product.id}': {product.description}")
+
+
+# ┌───
+# │ Update Product │
+# └────────────────┘
+try:
+    product = paddle.products.update(
+        product.id,
+        UpdateProduct(
+            name="Bear Service",
+            image_url="https://placebear.com/200/300",
+            custom_data=CustomData({"beep": "boop"}),
+        ),
+    )
+except ApiError as error:
+    print(error)
+    exit(1)
+
+print(f"Updated product '{product.id}': {product.description}")
+
+
+# ┌───
+# │ Create Price │
+# └──────────────┘
+try:
+    price = paddle.prices.create(
+        CreatePrice(
+            description="Bear Hug",
+            product_id=product.id,
+            unit_price=Money("1000", CurrencyCode.GBP),
+            trial_period=Duration(Interval.Week, 1),
+            billing_cycle=Duration(Interval.Year, 1),
+            quantity=PriceQuantity(1, 1),
+            custom_data=CustomData({"foo": "bar"}),
+            unit_price_overrides=[
+                UnitPriceOverride(
+                    [CountryCode.CA, CountryCode.US],
+                    Money("5000", CurrencyCode.USD),
+                ),
+            ],
+        )
+    )
+except ApiError as error:
+    print(error)
+    exit(1)
+
+print(f"Created price '{price.id}': {price.description}")
+
+
+# ┌───
+# │ Update Price │
+# └──────────────┘
+try:
+    price = paddle.prices.update(
+        price.id,
+        UpdatePrice(
+            description="One-off Bear Hug",
+            unit_price=Money("500", CurrencyCode.GBP),
+            custom_data=CustomData({"beep": "boop"}),
+        ),
+    )
+except ApiError as error:
+    print(error)
+    exit(1)
+
+print(f"Updated price '{price.id}': {price.description}")
+
+
+# ┌───
+# │ Get Product with Prices │
+# └─────────────────────────┘
+try:
+    product = paddle.products.get(product.id, [ProductIncludes.Prices])
+except ApiError as error:
+    print(error)
+    exit(1)
+
+print(f"product.prices={product.prices}")
+print(f"Read product '{product.id}' with prices " + ", ".join([str(price.id) for price in product.prices]))
+
+
+# ┌───
+# │ Get Price with Product │
+# └────────────────────────┘
+try:
+    price = paddle.prices.get(price.id, [PriceIncludes.Product])
+except ApiError as error:
+    print(error)
+    exit(1)
+
+print(f"Read price '{price.id}' with product {price.product.id if price.product else 'MISSING PRODUCT'}")
+
+
+# ┌───
+# │ Get Products │
+# └──────────────┘
+try:
+    products = paddle.products.list(
+        ListProducts(
+            includes=[ProductIncludes.Prices],
+            statuses=[Status.Active],
+        )
+    )
+except ApiError as error:
+    print(error)
+    exit(1)
+
+
+# ┌───
+# │ Iterate Products and Prices │
+# └─────────────────────────────┘
+for product in products:
+    print(f"Product: {product.name}")
+    print("-" * len(product.name))
+    for price in product.prices:
+        print(f"Price: {price.name} - {price.description}")
+    print()

paddle_python_sdk-0.3.0/examples/event_polling.py

@@ -0,0 +1,54 @@
+from logging import getLogger
+from os import getenv
+from sys import exit  # You should use classes/functions that returns instead of exits
+
+from paddle_billing import Client, Environment, Options
+
+from paddle_billing.Exceptions.ApiError import ApiError
+
+from paddle_billing.Resources.Events.Operations import ListEvents
+from paddle_billing.Resources.Shared.Operations import Pager
+
+log = getLogger("my_app")
+
+# Verify your Paddle API key was provided by a PADDLE_SECRET_API_KEY environment variable
+# It is strongly advised that you do not include secrets in your source code
+# Use environment variables, and/or secrets management like Vault to obtain your secrets
+api_key: str = getenv("PADDLE_SECRET_API_KEY", None)
+if not api_key:
+    raise ValueError("You must provide the PADDLE_SECRET_API_KEY in your environment variables")
+
+# Determine the environment, defaulting to sandbox
+environment = Environment(getenv("PADDLE_ENVIRONMENT", "sandbox"))
+
+# Initialize the Paddle client
+paddle = Client(api_key, options=Options(environment), logger=log)
+
+# Placeholder for the last processed event ID
+last_processed_event_id = "evt_01hfxx8t6ek9h399srcrp36jt3"
+
+events = None
+try:
+    # List events starting after the last processed event ID
+    events = paddle.events.list(ListEvents(Pager(after=last_processed_event_id)))
+except ApiError as error:
+    log.error(error)
+    # Your additional logic that can handle Paddle's hints about what went wrong
+except Exception as error:
+    log.error(f"We received an error listing events: {error}")
+
+if not events:
+    print("There was an error trying to list events")
+    exit(1)
+if not len(events.items):
+    log.warning("There are no events to list")
+    print("There are no products to list")
+    exit(0)
+
+for event in events:
+    last_processed_event_id = event.event_id  # Update the last processed event ID
+    print(f"event: {event.event_id}\t\t Type: {event.event_type.value:28}\t\t Occurred At: {event.occurred_at}")
+    # Your additional logic for using each event
+
+# Now you're up-to-date, you should keep a record of the last processed event...
+# db.save(db_events.update({last_processed_event_id=last_processed_event_id})

paddle_python_sdk-0.3.0/examples/get_products.py

@@ -0,0 +1,49 @@
+from logging import getLogger
+from os import getenv
+from sys import exit  # You should use classes/functions that returns instead of exits
+
+from paddle_billing import Client, Environment, Options
+
+from paddle_billing.Exceptions.ApiError import ApiError
+
+log = getLogger("my_app")
+
+# Verify your Paddle API key was provided by a PADDLE_SECRET_API_KEY environment variable
+# It is strongly advised that you do not include secrets in your source code
+# Use environment variables, and/or secrets management like Vault to obtain your secrets
+api_key = getenv("PADDLE_SECRET_API_KEY", None)
+if not api_key:
+    raise ValueError("You must provide the PADDLE_SECRET_API_KEY in your environment variables")
+
+# Determine the environment, defaulting to sandbox
+environment = Environment(getenv("PADDLE_ENVIRONMENT", "sandbox"))
+
+# Initialize the Paddle client
+paddle = Client(api_key, options=Options(environment), logger=log)
+
+products = None
+try:
+    products = paddle.products.list()
+except ApiError as error:
+    log.error(error)
+    # Your additional logic that can handle Paddle's hints about what went wrong.
+    print(f"error_type: {error.error_type}")
+    print(f"error_code: {error.error_code}")
+    print(f"detail: {error.detail}")
+    print(f"field_errors: {error.field_errors}")
+    print(f"response.status_code: {error.response.status_code}")
+except Exception as error:
+    log.error(f"We received an error listing products: {error}")
+
+if not products:
+    print("There was an error trying to list products")
+    exit(1)
+if not len(products.items):
+    log.warning("There are no products to list, have you created one?")
+    print("There are no products to list")
+    exit(0)
+
+# No need to specifically iterate products.items, products itself is iterable
+for product in products:
+    print(f"Product's id: {product.id}")
+    # Your additional logic for using each product

paddle_python_sdk-0.3.0/examples/logger.py

@@ -0,0 +1,33 @@
+import logging
+
+from os import getenv
+from paddle_billing import Client, Environment, Options
+
+
+# Verify your Paddle API key was provided by a PADDLE_SECRET_API_KEY environment variable
+# It is strongly advised that you do not include secrets in your source code
+# Use environment variables, and/or secrets management like Vault to obtain your secrets
+api_key = getenv("PADDLE_SECRET_API_KEY", None)
+if not api_key:
+    raise ValueError("You must provide the PADDLE_SECRET_API_KEY in your environment variables")
+
+# Determine the environment, defaulting to sandbox
+environment = Environment(getenv("PADDLE_ENVIRONMENT", "sandbox"))
+
+# Initialize the Paddle client
+paddle = Client(
+    api_key,
+    options=Options(environment),
+    logger=logging.getLogger("my_app"),
+)
+
+# Set up logging to standard output
+stdout_handler = logging.StreamHandler()
+stdout_handler.setLevel(logging.INFO)
+paddle.log.addHandler(stdout_handler)
+
+# List products
+products = paddle.products.list()
+
+for product in products:
+    print(f"Product's id: {product.id}")

paddle_python_sdk-0.3.0/examples/webhook_verification.py

@@ -0,0 +1,33 @@
+from paddle_billing.Entities.Notifications import NotificationEvent
+from paddle_billing.Notifications import Secret, Verifier
+from examples.Utils.Requests.Request import Request
+
+# This example requires environment variable TEST_MODE=1 to disable time drift checks, e.g.
+# TEST_MODE=1 python webhook_verification.py
+
+secret = "pdl_ntfset_01hs0t3tw21j988db1pam5xg8m_GrOWLNef+vmtjJYq4mSnHNzvc8uWoJ1I"
+
+request = Request.create_from_fixture(
+    "webhook_payload.json",
+    {
+        "Paddle-Signature": "ts=1710498758;h1=558bf93944dbeb4790c7a8af6cb2ea435c8ca9c8396aafc1a4e37424ac132744",
+    },
+)
+
+integrity_check = Verifier().verify(request, Secret(secret))
+
+if integrity_check is True:
+    print("Webhook is verified")
+
+    notification = NotificationEvent.from_request(request)
+    print(f"Notification ID: {notification.notification_id}")
+    print(f"Event ID: {notification.event_id}")
+    print(f"Event Type: {notification.event_type}")
+    print(f"Occurred At: {notification.occurred_at}")
+
+    customer = notification.data
+    print(f"Customer ID: {customer.id}")
+    print(f"Customer Name: {customer.name}")
+    print(f"Customer Email: {customer.email}")
+else:
+    print("Webhook is not verified")