ShipEngine Python SDK

• The official Python module for ShipEngine API.

Quick Start

Install shipengine via pip:

pip install shipengine

• The only configuration requirement is providing an API Key.

The following assumes that you have already set the SHIPENGINE_API_KEY environment variable with your API Key using os.environ["SHIPENGINE_API_KEY"] = "<YOUR_API_KEY_HERE>".

Instantiate ShipEngine Class

import os

from shipengine import ShipEngine

api_key = os.getenv("SHIPENGINE_API_KEY")

shipengine = ShipEngine(api_key)

• You can also pass in a dictionary containing configuration options instead of just passing in a string that is your API Key.

import os

from shipengine import ShipEngine

api_key = os.getenv("SHIPENGINE_API_KEY")

shipengine = ShipEngine(
    {"api_key": api_key, "page_size": 75, "retries": 3, "timeout": 10}
)

Methods

• addresses_validate - Indicates whether the provided address is valid. If the address is valid, the method returns a normalized version of the address based on the standards of the country in which the address resides.
• create_label_from_rate_id - Purchase a label by rate_id. When using the get_rates_from_shipment method, you can use one of the returned rate_id values with this method to purchase a label against a given rate.
• create_label_from_shipment - Purchase a label created from shipment details.
• get_rates_from_shipment - Fetch rates from shipment details to shop the best shipping rate for your package.
• list_carriers - Lists the carrier accounts connected to your SHipEngine account.
• track_package_by_label_id - Track a package by label_id, the preferred way to track shipments if you crate shipping labels using ShipEngine. This method returns the all tracking events for a given shipment.
• track_package_by_carrier_code_and_tracking_number - Track a package by carrier_code and tracking_number. This method returns the all tracking events for a given shipment.
• void_label_by_label_id - Void a shipping label you created using ShipEngine by its label_id. This method returns an object that indicates the status of the void label request.

Class Objects

• ShipEngine - A configurable entry point to the ShipEngine API SDK, this class provides convenience methods for various ShipEngine API Services.

Contributing

Local Development

You will need to install Python3.7 if you do not have it locally, before working on this project.

This project uses Poetry to manage project dependencies, build steps, and publishing to PYPI.

You can use the following curl command to download Poetry from your terminal is you are on osx / linux / bashonwindows:

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -

• Once you have Poetry installed you need to install the projects dependencies with this command from the project root:

bin/setup

• This script will install all dependencies specified in pyproject.toml via Poetry and install the pre-commit hooks this project uses.

Adding dependencies to the project

If your changes require you to install a python package/module using poetry add <some package> or poetry add <some package> -D for a dev dependency. You will also need to run the following command to regenerate a requirements.txt file that includes the newly added dependencies:

poetry export -f requirements.txt --output requirements.txt --without-hashes --dev

Pre-Commit Hooks

We are using Pre-Commit to enforce formatting, lint rules, and code analysis so that this repo is always in good health.

• Pre-Commit is installed and initialized when you run bin/setup from the project root as outlined above.

• If you choose not to use Poetry and prefer pip you can simply run pip install -r requirements.txt To be able to commit & push a PR to the repo after making changes locally, you will need to install pre-commit which is a tool that runs tests, linting, formatting, and code analysis on your changes.

pre-commit install

Note: The checks run in pre-commit hooks are the same checks run in CI in our GitHub Actions.

Testing

You can run the tests in the tests/ directory using Pytest in the Poetry environment like this:

poetry run pytest

OR via Tox:

poetry run tox

Linting

You can run the linting environment in Tox using this commandi:

poetry tox -e lint