Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/shipengine/shipengine-python
The official Python SDK for ShipEngine API
https://github.com/shipengine/shipengine-python
address-normalization address-validation api dhl-api fedex-api package-tracking python rest-api sdk shipengine shipment-tracking shipping-api shipping-label shipping-rates tracking-number ups-api usps-api
Last synced: 11 days ago
JSON representation
The official Python SDK for ShipEngine API
- Host: GitHub
- URL: https://github.com/shipengine/shipengine-python
- Owner: ShipEngine
- License: apache-2.0
- Created: 2021-03-01T17:28:18.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-01-12T20:04:16.000Z (10 months ago)
- Last Synced: 2024-04-14T10:48:14.200Z (7 months ago)
- Topics: address-normalization, address-validation, api, dhl-api, fedex-api, package-tracking, python, rest-api, sdk, shipengine, shipment-tracking, shipping-api, shipping-label, shipping-rates, tracking-number, ups-api, usps-api
- Language: Python
- Homepage: https://www.shipengine.com/docs/
- Size: 399 KB
- Stars: 8
- Watchers: 16
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://shipengine.com)
ShipEngine Python SDK
=====================
[](https://coveralls.io/github/ShipEngine/shipengine-python?branch=main)
- The official Python module for ShipEngine API.
Quick Start
===========
Install `shipengine` via `pip`:
```bash
pip install shipengine
```
- The only configuration requirement is providing an [API Key](https://www.shipengine.com/docs/auth/#api-keys "ShipEngine Authentication Docs").
> The following assumes that you have already set the `SHIPENGINE_API_KEY` environment variable with your API Key using `os.environ["SHIPENGINE_API_KEY"] = ""`.
Instantiate ShipEngine Class
----------------------------
```python
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`.
```python
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](./docs/addresses_validate_example.md) - 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](./docs/create_label_from_rate_id_example.md) - 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](./docs/create_label_from_shipment.md) - Purchase a label created from shipment details.
- [get_rates_from_shipment](./docs/get_rates_from_shipment_example.md) - Fetch rates from shipment details to shop the best shipping rate for your package.
- [list_carriers](./docs/list_carriers_example.md) - Lists the carrier accounts connected to your SHipEngine account.
- [track_package_by_label_id](./docs/track_package_by_label_id_example.md) - 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](./docs/track_package_by_carrier_code_and_tracking_number_example.md) - 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](./docs/void_label_by_label_id_example.md) - 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`:
```bash
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:
```bash
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 ` or
`poetry add -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:
```bash
poetry export -f requirements.txt --output requirements.txt --without-hashes --dev
```
## Pre-Commit Hooks
We are using [Pre-Commit](https://pre-commit.com/) 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.
```bash
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:
```bash
poetry run pytest
```
OR via `Tox`:
```bash
poetry run tox
```
Linting
-------
You can run the `linting environment` in **Tox** using this commandi:
```bash
poetry tox -e lint
```