python-amazon-mws

python-amazon-mws is a Python connector to Amazon Marketplace Web Services (or MWS). It provides a simple way to build and send requests to MWS, allowing access to all that MWS can do from your Python application.

Mostly inactive development

Time to maintain this project is limited at present, and the MWS service is being deprecated in favor of the newer Selling Partners API (SP-API).

If you require assistance with this package specifically, please feel free to open an issue. This project may be archived in the near future and development halted.

Installation

Two versions are currently available:

• Installing mws from PyPI, you will have version 0.8.x, which is built from our master branch.
  • This is a close match to the original package by czpython, with some small tweaks to add critical functionality.
  • Supports Python 2.7 and 3.4+.
• The updated 1.0devXY version must be installed from this repo's develop branch.
  • This includes additional API coverage that may be missing in 0.8.x, as well as other new features.
  • Some methods have new or updated arguments compared to 0.8.x, and much of the original monolithic mws module has been broken down into separate components (such as the mws.apis collection of modules).
  • Supports Python 3.6+.

Installing 0.8.x (PyPI)

Warning: If you are using version 0.8.x in a production system, note that our eventual 1.0 release will be backwards-incompatible, and may break programs that depend on the 0.8.x version. We advise users pin their Pip-installed version in requirements as mws~=0.8.9.

Install the mws package using Pip:

pip install mws

Alternatively, you can install direct from this repo's master branch, like so:

pip install git+https://github.com/python-amazon-mws/python-amazon-mws.git@master#egg=mws

Installing 1.0.x-dev (GitHub)

Our develop version can be installed directly from the repo using:

pip install git+https://github.com/python-amazon-mws/python-amazon-mws.git@develop#egg=mws

Note that code may be updated at any time as development continues, so please use at your own risk.

Quickstart

Export your API credentials as environment variables in your shell.

export MWS_ACCOUNT_ID=...
export MWS_ACCESS_KEY=...
export MWS_SECRET_KEY=...

Now you can experiment with the API from within an interactive Python shell e.g.

>>> import mws, os
>>> orders_api = mws.Orders(
...     access_key=os.environ['MWS_ACCESS_KEY'],
...     secret_key=os.environ['MWS_SECRET_KEY'],
...     account_id=os.environ['MWS_ACCOUNT_ID'],
...     region='UK',   # defaults to 'US'
... )
>>> service_status = orders_api.get_service_status()
>>> service_status
<mws.mws.DictWrapper object at 0x1063a2160>
>>> service_status.original
'<?xml version="1.0"?>\n<GetServiceStatusResponse xmlns="https://mws.amazonservices.com/Orders/2013-09-01">\n  <GetServiceStatusResult>\n    <Status>GREEN</Status>\n    <Timestamp>2017-06-14T16:39:12.765Z</Timestamp>\n  </GetServiceStatusResult>\n  <ResponseMetadata>\n    <RequestId>affdec68-05d2-4bc5-a8a4-bb40f307dd6b</RequestId>\n  </ResponseMetadata>\n</
GetServiceStatusResponse>\n'
>>> service_status.parsed
{'value': '\n    ', 'Status': {'value': 'GREEN'}, 'Timestamp': {'value': '2017-06-14T16:39:12.765Z'}}
>>> service_status.response
<Response [200]>

Development

To get started with development, first clone this repo, then install the package locally with extra dependencies:

# development tooling (Black, Flake8, Isort
pip install -e .[develop]
# documentation tools
pip install -e .[docs]
# both of the above
pip install -e .[develop,docs]
# or, just everything
pip install -e .[all]

Using pre-commit framework

This project uses the pre-commit framework. This framework installs a Git pre-commit hook that runs scripts as detailed in .pre-commit-config.yaml on commits in your local clone of the repo. These hooks are used to ensure code quality when contributing to the project.

The pre-commit package should already be installed along with installing development requirements (above), but is "opt-in" by design. We highly encourage using it in your local environment. To do so, install the hooks with:

pre-commit install

Pre-commit hook scripts will only run against the files that you change within a commit for speed purposes. To run the hooks against all files in the project, use:

pre-commit run --all-files

Tests

Tests are run with pytest. To run tests, simply install our dev requirements and then run:

pytest

See pytest docs for details on selecting specific tests, rather than the entire test suite, as needed.

We also perform coverage reporting using pytest-cov. You can generate a coverage report locally using:

pytest --cov=mws

You may also want to generate a local HTML report to navigate the code and see where coverage is missing:

pytest --cov=mws --cov-report html

This will create a htmlcov/ directory, and you can open htmlcov/index.html to view the report in your browser.

The test suite and coverage reporting to Codecov are run automatically in the repo on pushes and pull requests, using GitHub Actions workflows. We test on latest versions of Python 3.5+, and on latest Ubuntu, Mac, and Windows OSes.

Documentation

Docs are built using Sphinx.

To build docs locally, use make:

make html

The output HTML documentation will be in docs/build/.

To run a live reloading server serving the HTML documentation (on localhost:8000 or 127.0.0.1:8000 by default):

make livehtml

On Windows

make may not be available on Windows, but you can still build documentation with sphinx-build and sphinx-autobuild.

To build the docs locally, use sphinx-build:

sphinx-build -b html docs/source docs/build

You can also run a live-reloading server using sphinx-autobuild (on localhost:8000 or 127.0.0.1:8000 by default):

sphinx-autobuild docs/source docs/build

Contributing

Please make pull requests to develop. Code coverage isn't necessary but encouraged where possible.

Support

For support using the package, please join our Slack and post in the #help channel.

For support using MWS itself, we advise using the MWS documentation