Merge pull request #281 from EasyPost/v8_upgrade_guide

docs: adds v8 upgrade guide

Author: Justintime50

CHANGELOG.md

@@ -1,15 +1,19 @@
 # CHANGELOG
 
-## Next Major Release
+## v8.0.0 (2023-05-22)
 
-- New client object
-  - Services and models
+- New `EasyPostClient` object
+  - Logic is grouped together in Services and each EasyPost object has a new model (eg: `client.shipment.create()`)
+- Error handling overhaul
+  - Introduces ~2 dozen new error types that extend from either `ApiError` or `EasyPostError`
+  - ApiErrors behave like the previous `Error` class did. They will include a `message`, `http_status`, and `http_body`. Additionally, a new `code` and `errors` keys are present and populate when available
 - Beta namespace changed from `easypost.beta.x` to `client.beta_x`
 - Empty API response functions return `None` instead of `True`
-- References to `Referral` are now `ReferralCustomer` and `referral_customer` to match the API and docs
-- References to `Smartrate` are now `SmartRate` and `smart_rate` to match the API and docs
-- References to `Scanform` are now `ScanForm` and `scan_form`
-- `primary_or_secondary` paramater name for billing functions is now called `priority` to match the API and docs
+- Corrected naming conventions
+  - References to `Referral` are now `ReferralCustomer` and `referral_customer` to match the API and docs
+  - References to `Smartrate` are now `SmartRate` and `smart_rate` to match the API and docs
+  - References to `Scanform` are now `ScanForm` and `scan_form`
+  - `primary_or_secondary` paramater name for billing functions is now called `priority` to match the API and docs
 - The `update_email` function of the `referral_customer` service had the parameter order switched so `id` (previously called `user_id`) is first which matches the rest of the library
 - Dropped Python 3.6 support
 - Bumps all dependencies

README.md

@@ -27,9 +27,9 @@ A simple create & buy shipment example:
 import os
 import easypost
 
-easypost.api_key = os.getenv('EASYPOST_API_KEY')
+client = easypost.EasyPostClient(os.getenv('EASYPOST_API_KEY'))
 
-shipment = easypost.Shipment.create(
+shipment = client.shipment.create(
     from_address = {
         "name": "EasyPost",
         "street1": "118 2nd Street",
@@ -57,9 +57,9 @@ shipment = easypost.Shipment.create(
     },
 )
 
-shipment.buy(rate=shipment.lowest_rate())
+bought_shipment = client.shipment.buy(shipment.id, rate=shipment.lowest_rate())
 
-print(shipment)
+print(bought_shipment)
 ```
 
 ## Documentation

UPGRADE_GUIDE.md

@@ -2,11 +2,132 @@
 
 Use the following guide to assist in the upgrade process of the `easypost-python` library between major versions.
 
+- [Upgrading from 7.x to 8.0](#upgrading-from-7x-to-80)
 - [Upgrading from 6.x to 7.0](#upgrading-from-6x-to-70)
 - [Upgrading from 5.x to 6.0](#upgrading-from-5x-to-60)
 
+## Upgrading from 7.x to 8.0
+
+### 8.0 High Impact Changes
+
+- [Updating Dependencies](#80-updating-dependencies)
+- [EasyPostClient](#80-easypostclient)
+- [Improved Error Handling](#80-improved-error-handling)
+
+### 8.0 Medium Impact Changes
+
+- [Corrected Naming Conventions](#80-corrected-naming-conventions)
+
+### 8.0 Low Impact Changes
+
+- [Beta Namespace Changed](#80-beta-namespace-changed)
+- [Changed Function Parameter Order and Return Types](#80-changed-function-parameter-order-and-return-types)
+
+## 8.0 Updating Dependencies
+
+Likelihood of Impact: High
+
+**Python 3.7 Required**
+
+easypost-python now requires Python 3.7 or greater.
+
+**Dependencies**
+
+All dependencies had minor version bumps.
+
+## 8.0 EasyPostClient
+
+Likelihood of Impact: High
+
+This library is now thread-safe with the introduction of a new `EasyPostClient` object. Instead of defining a global API key that all requests use, you create an `EasyPostClient` object and pass your API key to it. You then call your desired functions against a "service" which coincide with EasyPost objects:
+
+```python
+# Old method
+easypost.api_key = os.getenv('EASYPOST_API_KEY')
+shipment = easypost.Shipment.create({'data': 'here'})
+
+# New method
+client = easypost.EasyPostClient(api_key=os.getenv('EASYPOST_API_KEY'))
+shipment = client.shipment.create({'data': 'here'})
+```
+
+All instance methods are now static with the exception of `lowest_rate` as these make API calls and require the EasyPostClient (EasyPost objects do not contain an API key to make API calls with).
+
+Previously used `.save()` instance methods are now static `.update()` functions where you specify first the ID of the object you are updating and second, the parameters that need updating.
+
+Functions no longer accept an API key as an optional parameter. If you need per-function API key changes, create a new EasyPostClient object and call the function on the new client that uses the API key you need.
+
+### 8.0 Improved Error Handling
+
+Likelihood of Impact: High
+
+There are ~2 dozen new error types that extend either `ApiError` or `EasyPostError`.
+
+New ApiErrors (extends EasyPostError):
+
+- `ApiError`
+- `EncodingError`
+- `ExternalApiError`
+- `ForbiddenError`
+- `GatewayTimeoutError`
+- `HttpError`
+- `InternalServerError`
+- `InvalidRequestError`
+- `JsonError`
+- `MethodNotAllowedError`
+- `NotFoundError`
+- `PaymentError`
+- `RateLimitError`
+- `RedirectError`
+- `ServiceUnavailableError`
+- `TimeoutError`
+- `UnauthorizedError`
+- `UnknownApiError`
+
+New EasyPostErrors (extends builtin Exception):
+
+- `EasyPostError`
+- `EndOfPaginationError`
+- `FilteringError`
+- `InvalidObjectError`
+- `InvalidParameterError`
+- `MissingParameterError`
+- `SignatureVerificationError`
+
+ApiErrors will behave like the previous Error class did. They will include a `message`, `http_status`, and `http_body`. Additionally, a new `code` and `errors` keys are present and populate when available. This class extends the more generic `EasyPostError` which only contains a message, used for errors thrown directly from this library.
+
+The `original_exception` property has been removed and is now returned directly in the error message if present.
+
+### 8.0 Corrected Naming Conventions
+
+Likelihood of Impact: Medium
+
+Occurances of `referral` are now `referral_customer` and `Referral` are now `ReferralCustomer` to match the documentation and API.
+
+Occurances of `smartrate` are now `smart_rate` and `Smartrate` are now `SmartRate` to match the documentation and API.
+
+Occurances of `scanform` are now `scan_form` and `Scanform` are now `ScanForm` to match the documentation and API.
+
+The `primary_or_secondary` parameter name for billing functions is now called `priority` to match the documentation and API.
+
+## 8.0 Beta Namespace Changed
+
+Likelihood of Impact: Low
+
+Previously, the beta namespace was found at `easypost.beta.x` where `x` is the name of your model. Now, the beta namespace is simply prepended to the name of your service: `client.beta_x`. for instance, you can call `client.beta_referral_customer.add_payment_method()`.
+
+## 8.0 Changed Function Parameter Order and Return Types
+
+Likelihood of Impact: Low
+
+The `update_email` function of the `referral_customer` service had the parameter order switched and name changed. Previously, you would pass the email and then the id, Now, you pass the `id` of the user first, then the email. This change matches the rest of the library where an ID always comes first.
+
+Functions that previously returned `True` now do not return anything as there is no response body from the API (eg: `fund_wallet`, `delete_payment_method`, `update_email`, `create_list`)
+
 ## Upgrading from 6.x to 7.0
 
+**NOTICE:** v7 is deprecated.
+
 ### 7.0 High Impact Changes
 
 - [Updating Dependencies](#70-updating-dependencies)

easypost/constant.py

@@ -1,6 +1,6 @@
 # flake8: noqa
 # Library version
-VERSION = "7.13.0"
+VERSION = "8.0.0"
 VERSION_INFO = [str(number) for number in VERSION.split(".")]
 
 # Client defaults

easypost/services/billing_service.py

@@ -9,7 +9,7 @@
     NO_BILLING_ERROR,
 )
 from easypost.easypost_object import convert_to_easypost_object
-from easypost.errors import PaymentError
+from easypost.errors import InvalidObjectError
 from easypost.models import Billing
 from easypost.requestor import (
     RequestMethod,
@@ -49,7 +49,7 @@ def retrieve_payment_methods(self, **params) -> Dict[str, Any]:
         )
 
         if response.get("id") is None:
-            raise PaymentError(message=NO_BILLING_ERROR)
+            raise InvalidObjectError(message=NO_BILLING_ERROR)
 
         return convert_to_easypost_object(response=response)
 
@@ -71,8 +71,8 @@ def _get_payment_method_info(self, priority: str = "primary") -> List[str]:
             elif payment_method_id.startswith("bank_"):
                 endpoint = "/bank_accounts"
             else:
-                raise PaymentError(message=INVALID_PAYMENT_METHOD_ERROR)
+                raise InvalidObjectError(message=INVALID_PAYMENT_METHOD_ERROR)
         else:
-            raise PaymentError(message=INVALID_PAYMENT_METHOD_ERROR)
+            raise InvalidObjectError(message=INVALID_PAYMENT_METHOD_ERROR)
 
         return [endpoint, payment_method_id]

setup.py

@@ -33,7 +33,7 @@
 
 setup(
     name="easypost",
-    version="7.13.0",
+    version="8.0.0",
     description="EasyPost Shipping API Client Library for Python",
     author="EasyPost",
     author_email="[email protected]",

tests/test_billing.py

@@ -3,7 +3,7 @@
 import pytest
 
 import easypost
-from easypost.errors import PaymentError
+from easypost.errors import InvalidObjectError
 
 
 @patch(
@@ -54,7 +54,7 @@ def test_billing_payment_method_delete_bank_account(mock_request, mock_payment_m
 @patch("easypost.services.billing_service.Requestor.request", return_value={"mock": "response"})
 def test_billing_payment_method_delete_invalid(mock_request, mock_payment_methods, prod_client):
     """Tests we raise an error when we receive an invalid payment method"""
-    with pytest.raises(PaymentError):
+    with pytest.raises(InvalidObjectError):
         _ = prod_client.billing.delete_payment_method(priority="primary")
 
 
@@ -65,7 +65,7 @@ def test_billing_payment_method_delete_invalid(mock_request, mock_payment_method
 @patch("easypost.services.billing_service.Requestor.request", return_value={"mock": "response"})
 def test_billing_payment_method_delete_bad_request(mock_request, mock_payment_methods, prod_client):
     """Tests we raise an error when we cannot retrieve a payment method."""
-    with pytest.raises(PaymentError):
+    with pytest.raises(InvalidObjectError):
         _ = prod_client.billing.delete_payment_method(priority="tertiary")
 
 
@@ -81,7 +81,7 @@ def test_billing_retrieve_payment_methods(mock_request, prod_client):
 @patch("easypost.services.billing_service.Requestor.request", return_value={"mock": "response"})
 def test_billing_retrieve_payment_methods_no_billing_setup(mock_request, prod_client):
     """Tests that we throw an error when we cannot retrieve payment methods due to no billing being setup."""
-    with pytest.raises(PaymentError) as error:
+    with pytest.raises(InvalidObjectError) as error:
         _ = prod_client.billing.retrieve_payment_methods()
 
     mock_request.assert_called_once()