paddle-python-sdk 0.1.0__py3-none-any.whl

examples/catalog_management.py

@@ -0,0 +1,166 @@
+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,
+    Money,
+    TimePeriod,
+    PriceQuantity,
+    UnitPriceOverride,
+    Interval,
+    Status,
+    TaxCategory
+)
+
+from paddle_billing.Exceptions.ApiError                        import ApiError
+from paddle_billing.Exceptions.SdkExceptions.MalformedResponse import MalformedResponse
+
+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        = getenv('PADDLE_ENVIRONMENT', 'sandbox')
+paddle_environment = getattr(Environment, environment)  # E.g. Environment.sandbox
+
+# Initialize the Paddle client
+paddle = Client(api_key, options=Options(paddle_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, MalformedResponse) 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, MalformedResponse) 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  = TimePeriod(Interval.Week, 1),
+        billing_cycle = TimePeriod(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, MalformedResponse) 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, MalformedResponse) 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, MalformedResponse) 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, MalformedResponse) 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, MalformedResponse) 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()

examples/event_polling.py

@@ -0,0 +1,56 @@
+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.Exceptions.SdkExceptions.MalformedResponse import MalformedResponse
+
+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        = getenv('PADDLE_ENVIRONMENT', 'sandbox')
+paddle_environment = getattr(Environment, environment)  # E.g. Environment.sandbox
+
+# Initialize the Paddle client
+paddle = Client(api_key, options=Options(paddle_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, MalformedResponse) 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.format()}")
+    # 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})

examples/get_products.py

@@ -0,0 +1,46 @@
+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.Exceptions.SdkExceptions.MalformedResponse import MalformedResponse
+
+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        = getenv('PADDLE_ENVIRONMENT', 'sandbox')
+paddle_environment = getattr(Environment, environment)  # E.g. Environment.sandbox
+
+# Initialize the Paddle client
+paddle = Client(api_key, options=Options(paddle_environment), logger=log)
+
+products = None
+try:
+    products = paddle.products.list()
+except (ApiError, MalformedResponse) 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 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

examples/logger.py

@@ -0,0 +1,31 @@
+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        = getenv('PADDLE_ENVIRONMENT', 'sandbox')
+paddle_environment = getattr(Environment, environment)  # E.g. Environment.sandbox
+
+# Initialize the Paddle client
+paddle = Client(
+    api_key,
+    options = Options(paddle_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
+paddle.products.list()

paddle_billing/Client.py

@@ -0,0 +1,201 @@
+from json               import dumps as json_dumps
+from logging            import Logger, getLogger
+from requests           import Response, RequestException, Session
+from requests.adapters  import HTTPAdapter
+from urllib3.util.retry import Retry
+from urllib.parse       import urljoin, urlencode
+from uuid               import uuid4
+
+from paddle_billing.FiltersUndefined import FiltersUndefined
+from paddle_billing.HasParameters    import HasParameters
+from paddle_billing.Options          import Options
+
+from paddle_billing.Logger.NullHandler import NullHandler
+
+from paddle_billing.Resources.Addresses.AddressesClient                       import AddressesClient
+from paddle_billing.Resources.Adjustments.AdjustmentsClient                   import AdjustmentsClient
+from paddle_billing.Resources.Businesses.BusinessesClient                     import BusinessesClient
+from paddle_billing.Resources.Customers.CustomersClient                       import CustomersClient
+from paddle_billing.Resources.Discounts.DiscountsClient                       import DiscountsClient
+from paddle_billing.Resources.Events.EventsClient                             import EventsClient
+from paddle_billing.Resources.EventTypes.EventTypesClient                     import EventTypesClient
+from paddle_billing.Resources.Notifications.NotificationsClient               import NotificationsClient
+from paddle_billing.Resources.NotificationLogs.NotificationLogsClient         import NotificationLogsClient
+from paddle_billing.Resources.NotificationSettings.NotificationSettingsClient import NotificationSettingsClient
+from paddle_billing.Resources.Prices.PricesClient                             import PricesClient
+from paddle_billing.Resources.PricingPreviews.PricingPreviewsClient           import PricingPreviewsClient
+from paddle_billing.Resources.Products.ProductsClient                         import ProductsClient
+from paddle_billing.Resources.Reports.ReportsClient                           import ReportsClient
+from paddle_billing.Resources.Subscriptions.SubscriptionsClient               import SubscriptionsClient
+from paddle_billing.Resources.Transactions.TransactionsClient                 import TransactionsClient
+
+
+class Client:
+    """
+    Client for making API requests using Python's requests library.
+    """
+    def __init__(
+        self,
+        api_key:         str,
+        options:         Options  = None,
+        http_client:     Session  = None,
+        logger:          Logger   = None,
+        retry_count:     int      = 3,
+        use_api_version: int      = 1,
+    ):
+        self.__api_key       = api_key
+        self.retry_count     = retry_count
+        self.transaction_id  = None
+        self.use_api_version = use_api_version
+        self.options         = options     if options     else Options()
+        self.log             = logger      if logger      else Client.null_logger()
+        self.client          = http_client if http_client else self.build_request_session()
+        self.payload         = None  # Used by pytest
+        self.status_code     = None  # Used by pytest
+
+        # Initialize the various clients
+        self.addresses             = AddressesClient(self)
+        self.adjustments           = AdjustmentsClient(self)
+        self.businesses            = BusinessesClient(self)
+        self.customers             = CustomersClient(self)
+        self.discounts             = DiscountsClient(self)
+        self.events                = EventsClient(self)
+        self.event_types           = EventTypesClient(self)
+        self.notifications         = NotificationsClient(self)
+        self.notification_logs     = NotificationLogsClient(self)
+        self.notification_settings = NotificationSettingsClient(self)
+        self.prices                = PricesClient(self)
+        self.pricing_previews      = PricingPreviewsClient(self)
+        self.products              = ProductsClient(self)
+        self.reports               = ReportsClient(self)
+        self.subscriptions         = SubscriptionsClient(self)
+        self.transactions          = TransactionsClient(self)
+
+
+    @staticmethod
+    def null_logger() -> Logger:
+        """
+        Create a logger instance that logs everything to nowhere
+        """
+
+        null_logger = getLogger('null_logger')
+        null_logger.addHandler(NullHandler())
+
+        return null_logger
+
+
+    def logging_hook(self, response, *args, **kwargs):
+        """
+        Requests logs were redirected here and to our custom logger which filters out sensitive data
+        """
+
+        self.log.info(f"Request: {response.request.method} {response.request.url}")
+        self.log.debug(f"Response: {response.status_code} {response.text}")
+
+
+    @staticmethod
+    def serialize_json_payload(payload: dict) -> str:
+        # Removes unneeded level of nested CustomData data
+        if payload.get('custom_data') and 'data' in payload['custom_data']:
+            payload['custom_data'] = payload['custom_data']['data']
+
+        json_payload = json_dumps(payload)
+        final_json   = json_payload if json_payload != '[]' else '{}'
+
+        return final_json
+
+
+    def _make_request(
+        self,
+        method:     str,
+        url:        str,
+        payload:    dict | None = None,
+    ) -> Response:
+        """
+        Makes an actual API call to Paddle
+        """
+        # Parse and update URL with base URL components if necessary
+        if isinstance(url, str):
+            url = urljoin(self.options.environment.base_url, url)
+
+        self.client.headers.update({
+            'X-Transaction-ID': str(self.transaction_id) if self.transaction_id else str(uuid4())
+        })
+
+        self.payload = self.serialize_json_payload(payload) if payload else None
+        try:
+            # We use data= instead of json= because we manually serialize data into JSON
+            response         = self.client.request(method.upper(), url, data=self.payload)
+            self.status_code = response.status_code
+            response.raise_for_status()
+
+            return response
+        except RequestException as e:
+            self.status_code = e.response.status_code
+
+            if self.log:
+                self.log.error(f"Request failed: {e}")
+            raise
+
+
+    @staticmethod
+    def format_uri_parameters(uri: str, parameters: HasParameters | dict) -> str:
+        if isinstance(parameters, HasParameters):
+            parameters = parameters.get_parameters()
+
+        query = urlencode(parameters)
+        uri  += '&' if '?' in uri else '?'
+        uri  += query
+
+        return uri
+
+
+    def get_raw(self, url: str, parameters: HasParameters | dict = None) -> Response:
+        url = Client.format_uri_parameters(url, parameters) if parameters else url
+
+        return self._make_request('GET', url, None)
+
+
+    def post_raw(
+        self,
+        url:        str,
+        payload:    dict                 | None = None,
+        parameters: HasParameters | dict | None = None
+    ) -> Response:
+        if payload:
+            payload = FiltersUndefined.filter_undefined_values(payload)  # Strip Undefined items from the dict
+
+        url = Client.format_uri_parameters(url, parameters) if parameters else url
+
+        return self._make_request('POST', url, payload)
+
+
+    def patch_raw(self, url: str, payload: dict | None) -> Response:
+        if payload:
+            payload = FiltersUndefined.filter_undefined_values(payload)  # Strip Undefined items from the dict
+
+        return self._make_request('PATCH', url, payload)
+
+
+    def delete_raw(self, url: str) -> Response:
+        return self._make_request('DELETE', url)
+
+
+    def build_request_session(self) -> Session:
+        session = Session()
+        session.headers.update({
+            'Authorization':  f"Bearer {self.__api_key}",
+            'Content-Type':   'application/json',
+            'Paddle-Version': str(self.use_api_version),
+            'User-Agent':     'PaddleSDK/python 0.1.0',
+        })
+
+        # Configure retries
+        retries = Retry(total=self.retry_count, backoff_factor=1, status_forcelist=[429, 500, 502, 503, 504])
+        session.mount('https://', HTTPAdapter(max_retries=retries))
+
+        # Handle logging
+        if self.log:
+            session.hooks['response'] = self.logging_hook
+
+        return session

paddle_billing/ConditionallyRemoveImportMeta.py

@@ -0,0 +1,14 @@
+from dataclasses import fields
+
+from paddle_billing.RecursivelyRemoveKey import recursively_remove_key
+
+
+def conditionally_remove_import_meta(entity_class, data: dict):
+    """
+    Paddle sends us import_meta in the data, but not all Entities support this, causing dynamic class instantiation
+    to break. We selectively remove import_meta if the target Entity class doesn't define it.
+    """
+    import_meta_in_class = 'import_meta' in [field.name for field in fields(entity_class)]
+    import_meta_in_data  = 'import_meta' in data['data']
+    if not import_meta_in_class and import_meta_in_data:
+        recursively_remove_key(data, 'import_meta')

paddle_billing/Entities/Address.py

@@ -0,0 +1,44 @@
+from __future__  import annotations
+from dataclasses import dataclass
+from datetime    import datetime
+
+from paddle_billing.Entities.Entity import Entity
+from paddle_billing.Entities.Shared import CountryCode, CustomData, ImportMeta, Status
+
+
+@dataclass
+class Address(Entity):
+    id:           str
+    customer_id:  str
+    description:  str | None
+    first_line:   str | None
+    second_line:  str | None
+    city:         str | None
+    postal_code:  str | None
+    region:       str | None
+    country_code: CountryCode
+    custom_data:  CustomData | None
+    status:       Status
+    created_at:   datetime
+    updated_at:   datetime
+    import_meta:  ImportMeta | None
+
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Address:
+        return Address(
+            id           = data['id'],
+            customer_id  = data['customer_id'],
+            description  = data.get('description'),
+            first_line   = data.get('first_line'),
+            second_line  = data.get('second_line'),
+            city         = data.get('city'),
+            postal_code  = data.get('postal_code'),
+            region       = data.get('region'),
+            country_code = CountryCode(data['country_code']),
+            status       = Status(data['status']),
+            created_at   = datetime.fromisoformat(data['created_at']),
+            updated_at   = datetime.fromisoformat(data['updated_at']),
+            custom_data  = CustomData(data['custom_data'])           if data.get('custom_data') else None,
+            import_meta  = ImportMeta.from_dict(data['import_meta']) if data.get('import_meta') else None,
+        )

paddle_billing/Entities/Adjustment.py

@@ -0,0 +1,45 @@
+from __future__  import annotations
+from dataclasses import dataclass
+from datetime    import datetime
+
+from paddle_billing.Entities.Entity      import Entity
+from paddle_billing.Entities.Adjustments import AdjustmentItem
+from paddle_billing.Entities.Shared      import Action, AdjustmentStatus, CurrencyCode, PayoutTotalsAdjustment, AdjustmentTotals
+
+
+@dataclass
+class Adjustment(Entity):
+    id:                        str
+    action:                    Action
+    transaction_id:            str
+    subscription_id:           str | None
+    customer_id:               str
+    reason:                    str
+    credit_applied_to_balance: bool | None
+    currency_code:             CurrencyCode
+    status:                    AdjustmentStatus
+    items:                     list[AdjustmentItem]
+    totals:                    AdjustmentTotals
+    payout_totals:             PayoutTotalsAdjustment | None
+    created_at:                datetime
+    updated_at:                datetime | None
+
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Adjustment:
+        return Adjustment(
+            id                        = data['id'],
+            action                    = Action(data['action']),
+            transaction_id            = data['transaction_id'],
+            subscription_id           = data.get('subscription_id'),
+            customer_id               = data['customer_id'],
+            reason                    = data['reason'],
+            credit_applied_to_balance = data.get('credit_applied_to_balance'),
+            currency_code             = CurrencyCode(data['currency_code']),
+            status                    = AdjustmentStatus(data['status']),
+            totals                    = AdjustmentTotals.from_dict(data['totals']),
+            created_at                = datetime.fromisoformat(data['created_at']),
+            items                     = [AdjustmentItem.from_dict(item) for item in data['items']],
+            payout_totals             = PayoutTotalsAdjustment.from_dict(data['payout_totals']) if data.get('payout_totals') else None,
+            updated_at                = datetime.fromisoformat(data['updated_at'])              if data.get('updated_at')    else None,
+        )

paddle_billing/Entities/Adjustments/AdjustmentCustomerBalance.py

@@ -0,0 +1,18 @@
+from __future__  import annotations
+from dataclasses import dataclass
+
+
+@dataclass
+class AdjustmentCustomerBalance:
+    available: str
+    reserved:  str
+    used:      str
+
+
+    @staticmethod
+    def from_dict(data: dict) -> AdjustmentCustomerBalance:
+        return AdjustmentCustomerBalance(
+            available = data['available'],
+            reserved  = data['reserved'],
+            used      = data['used'],
+        )

paddle_billing/Entities/Adjustments/AdjustmentItem.py

@@ -0,0 +1,26 @@
+from __future__  import annotations
+from dataclasses import dataclass
+
+from paddle_billing.Entities.Shared import AdjustmentItemTotals, AdjustmentProration, AdjustmentType
+
+
+@dataclass
+class AdjustmentItem:
+    id:        str
+    item_id:   str
+    type:      AdjustmentType
+    amount:    str                 | None
+    proration: AdjustmentProration | None
+    totals:    AdjustmentItemTotals
+
+
+    @staticmethod
+    def from_dict(data: dict) -> AdjustmentItem:
+        return AdjustmentItem(
+            id        = data['id'],
+            item_id   = data['item_id'],
+            type      = AdjustmentType(data['type']),
+            amount    = data.get('amount'),
+            proration = AdjustmentProration.from_dict(data['proration']) if data.get('proration') else None,
+            totals    = AdjustmentItemTotals.from_dict(data['totals']),
+        )

paddle_billing/Entities/Adjustments/__init__.py

@@ -0,0 +1,2 @@
+from paddle_billing.Entities.Adjustments.AdjustmentItem            import AdjustmentItem
+from paddle_billing.Entities.Adjustments.AdjustmentCustomerBalance import AdjustmentCustomerBalance