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.
⚡ Development update - v1.0dev15 ⚡
We're working on new features in the run-up to releasing v1.0. If you are using the latest develop
branch version of the package, you can help us test these new features in your own environment.
Changes
- Dependencies have been updated: you may need to re-install requirements when upgrading.
DictWrapper
andDataWrapper
are deprecated, and will be removed in v1.1.- Starting in v1.0,
mws.response.MWSResponse
will be returned from all requests, instead.
- Starting in v1.0,
ObjectDict
and its aliasobject_dict
are deprecated, and will be removed in v1.1.- The
.parsed
interface ofDictWrapper
andDataWrapper
is preserved inMWSResponse
, but will return an instance ofmws.utils.collections.DotDict
instead ofObjectDict
.DotDict
is a more general-purpose object that subclassesdict
and provides a similar interface, while still allowing keys to be accessed as attributes. New features of this object include the ability to assign values to existing keys, and anydict
assigned to a key in aDotDict
will automatically be wrapped in its ownDotDict
with no need for additional processing.
- The
XML2Dict
and its aliasxml2dict
are deprecated, and will be removed in v1.1.- We will no longer perform XML parsing with our own methods. Instead, we are adding a dependency to
xmltodict
, which performs the same task a bit more cleanly. - Parsed content will no longer include superfluous extra dictionaries with
value
keys. If your code looks for thevalue
key, you may start seeing errors when testing new features.
- We will no longer perform XML parsing with our own methods. Instead, we are adding a dependency to
Testing new features.
All features related to deprecations in v1.0dev15 are locked behind a feature flag. Unless you explicitly set the feature flag as follows, your application should operate the same as before this update.
If your application worked on a prior develop
version and breaks when upgrading to v1.0dev15, please raise an issue so we may investigate.
To enable and test the new features, first instantiate your API class as normal, then set _use_feature_mwsresponse
to True
on the API instance:
from mws import Orders
api = Orders(...)
api._use_feature_mwsresponse = True
# Requests can be sent as normal:
response = api.list_orders()
# `response` should be an instance of `MWSResponse`,
# instead of the deprecated `DictWrapper` or `DataWrapper`.
# Use `.parsed` as before:
for order in response.parsed.Orders.Order:
print(order.AmazonOrderId)
# etc.
With this flag set, any request made through api
will be wrapped in the new MWSResponse
object; XML content will be parsed by the xmltodict
dependency; and response.parsed
will return a DotDict
instance with your parsed data.
Note: While
MWSResponse
maintains the same.parsed
interface, other interfaces have changed compared toDictWrapper
andDataWrapper
. For instance,DictWrapper.original
returned the original bytes of the response; whereasMWSResponse.original
returns the originalrequests.Response
instance. This provides better access to the full range of that response's data. So, to get the bytes content, you can useMWSResponse.original.content
.
Additionally,
MWSResponse
includes shortcut methods to some of the properties ofrequests.Response
, including.content
,.text
,.status_code
,.headers
, etc. So, you can useMWSResponse.content
as an equivalent to callingMWSResponse.original.content
.
More details will be provided in a documentation update, coming soon.
⚡ Thank you! ⚡
Installation
Two versions are currently available:
- Installing
mws
from PyPI, you will have version 0.8.x, which is built from ourmaster
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 themws.apis
collection of modules). - Supports Python 3.5+.
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
All dependencies for developing on python-amazon-mws
, including testing and documentation building, can be installed using:
pip install -r requirements-dev.txt
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