Use the following guide to assist in the upgrade process of the easypost-python library between major versions.
- Upgrading from 8.x to 9.0
- Upgrading from 7.x to 8.0
- Upgrading from 6.x to 7.0
- Upgrading from 5.x to 6.0
Likelihood of Impact: High
EasyPost now offers Carbon Neutral shipments by default for free! Because of this, there is no longer a need to specify if you want to offset the carbon footprint of a shipment.
The with_carbon_offset parameter of the create, buy, and regenerate_rates shipment functions has been removed.
This is a high-impact change for those using EndShippers, as the signature for the create and buy shipment functions have changed. You will need to inspect these callsites to ensure that the EndShipper parameter is being passed in the correct place.
Likelihood of Impact: Low
The create_and_buy batch endpoint has been deprecated, and the create_and_buy Batch service function has been removed.
The correct procedure is to first create a batch and then purchase it with two separate API calls.
NOTICE: v8 is deprecated.
Likelihood of Impact: High
Python 3.7 Required
easypost-python now requires Python 3.7 or greater.
Dependencies
All dependencies had minor version bumps.
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:
# 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.
Likelihood of Impact: High
There are ~2 dozen new error types that extend either ApiError or EasyPostError.
New ApiErrors (extends EasyPostError):
ApiErrorEncodingErrorExternalApiErrorForbiddenErrorGatewayTimeoutErrorHttpErrorInternalServerErrorInvalidRequestErrorJsonErrorMethodNotAllowedErrorNotFoundErrorPaymentErrorRateLimitErrorRedirectErrorServiceUnavailableErrorTimeoutErrorUnauthorizedErrorUnknownApiError
New EasyPostErrors (extends builtin Exception):
EasyPostErrorEndOfPaginationErrorFilteringErrorInvalidObjectErrorInvalidParameterErrorMissingParameterErrorSignatureVerificationError
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.
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.
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().
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)
NOTICE: v7 is deprecated.
Likelihood of Impact: High
Python 3.6 Required
easypost-python now requires Python 3.6 or greater and has dropped support for Python 2.
Dependencies
All dependencies had minor version bumps.
Previously the shipment.lowest_rate() function expected a comma separated string list of filter criteria (carriers and services). These params have been corrected to expect an actual list object.
# Previous expectation
shipment.lowest_rate(carriers="USPS,FedEx", services="...")
# Current expectation
shipment.lowest_rate(carriers=["USPS", "FedEx"], services=["..."])Likelihood of Impact: Medium
The HTTP method used for the get_rates endpoint at the API level has changed from POST to GET and will only retrieve rates for a shipment instead of regenerating them. A new /rerate endpoint has been introduced to replace this functionality; In this library, you can now call the shipment.regenerate_rates() method to regenerate rates. Due to the logic change, the get_rates method has been removed since a Shipment inherently already has rates associated.
NOTICE: v6 is deprecated.
Likelihood of Impact: High
Dependencies
Bumps the requests library from v1 to v2.
Likelihood of Impact: High
All POST and PUT request bodies are now JSON encoded instead of form-encoded. You may see subtle inconsistencies to how certain data types were previously sent to the API. We have taken steps to mitigate and test against these edge cases.