• The official Python module for ShipEngine API.

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>".

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}
)

• 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_rate_estimate - Get a rate estimate given minimal shipment details (carrier IDs, origin/destination, and weight) without requiring a full shipment object.
• 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 create shipping labels using ShipEngine. This method returns 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 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.
• list_labels_by_tracking_number - List the labels associated with the given tracking number.

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

You will need to install Python3.10 or higher 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://install.python-poetry.org | python3 -

• 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.

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

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.

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

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

poetry tox -e lint

This project uses release-please to automate releases. When a PR is merged, release-please reads the commit history to determine the next version and open a release PR. When that release PR is merged, the package is automatically published to PyPI.

This only works if commit messages follow the Conventional Commits format:

<type>: <short description>

Common types and their effect on versioning:

PRs with non-conforming titles will cause release-please to skip that commit silently, potentially blocking future releases.