.. Title: MyMagento .. Description: A Python package that wraps and extends the Magento 2 REST API .. Author: TDKorn

.. meta:: :title: MyMagento :description: A Python package that wraps and extends the Magento 2 REST API

.. |RTD| replace:: Explore the docs » .. _RTD: https://my-magento.readthedocs.io/en/latest/ .. |api_endpoint| replace:: API endpoint .. _api_endpoint: https://adobe-commerce.redoc.ly/2.3.7-admin/

.. raw:: html

.. image:: https://raw.githubusercontent.com/TDKorn/my-magento/v2.2.0/docs/source/_static/magento_orange.png :alt: Logo for MyMagento: Python Magento 2 REST API Wrapper :width: 15% .. raw:: html

MyMagento🛒

A Python package that wraps and extends the Magento 2 REST API |RTD|_ .. image:: https://img.shields.io/pypi/v/my-magento?color=eb5202 :target: https://pypi.org/project/my-magento/ :alt: PyPI Version .. image:: https://img.shields.io/badge/GitHub-my--magento-4f1abc :target: https://github.com/tdkorn/my-magento :alt: GitHub Repository .. image:: https://static.pepy.tech/personalized-badge/my-magento?period=total&units=none&left_color=grey&right_color=blue&left_text=Downloads :target: https://pepy.tech/project/my-magento .. image:: https://readthedocs.org/projects/my-magento/badge/?version=latest :target: https://my-magento.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status .. raw:: html

About MyMagento


.. raw:: html

   <table>
       <tr align="left">
           <th>

📝 What's MyMagento?

.. raw:: html

   </th>
   <tr><td>

``MyMagento`` is a highly interconnected package that wraps and extends the Magento 2 REST API,
providing a more intuitive and user-friendly interface to access and update your store.

.. raw:: html

   </td></tr>
   </table>

MyMagento simplifies interaction with the Magento 2 REST API
============================================================

If you've worked with the Magento 2 API, you'll know that not all endpoints are created equally.

``MyMagento`` aims to streamline your workflow by simplifying a
variety of commonly needed API operations.

...

Main Components
==================================

.. raw:: html

   <table>
       <tr align="left">
           <th>

💻 The |.~.Client|_

.. raw:: html

   </th>
   <tr><td>

* Handles all API interactions
* Supports multiple store views
* Provides access to all other package components

.. raw:: html

   </td></tr>
   </table>

.. raw:: html

   <table>
       <tr align="left">
           <th>

🔍 The |.~.SearchQuery|_ and Subclasses

.. raw:: html

   </th>
   <tr><td>

* |.~.execute|_ a search query on any endpoint
* Intuitive interface for `Building Custom Search Queries <https://my-magento.readthedocs.io/en/latest/interact-with-api.html#custom-queries>`_
* All predefined methods retrieve data using only 1-2 API requests

.. raw:: html

   </td></tr>
   </table>

.. raw:: html

   <table>
       <tr align="left">
           <th>

🧠 The |.~.Model|_ Subclasses

.. raw:: html

   </th>
   <tr><td>

* Wrap all API responses in the package
* Provide additional endpoint-specific methods to retrieve and update data

.. raw:: html

   </td></tr>
   </table>

...

Available Endpoints
======================

``MyMagento`` is compatible with every |api_endpoint|_

Endpoints are wrapped with a |.~.Model|_ and |.~.SearchQuery|_ subclass as follows:

.. csv-table::
   :header: "**Endpoint**", "**Client Shortcut**", "|.~.SearchQuery|_ **Subclass**", "|.~.Model|_ **Subclass**"

   "``orders``", "|..Client.orders|_", "|.~.OrderSearch|_", "|.~.Order|_"
   "``orders/items``", "|..Client.order_items|_", "|.~.OrderItemSearch|_", "|.~.OrderItem|_"
   "``invoices``", "|..Client.invoices|_", "|.~.InvoiceSearch|_", "|.~.Invoice|_"
   "``products``", "|..Client.products|_", "|.~.ProductSearch|_", "|.~.Product|_"
   "``products/attributes``", "|..Client.product_attributes|_", "|.~.ProductAttributeSearch|_", "|.~.ProductAttribute|_"
   "``categories``", "|..Client.categories|_", "|.~.CategorySearch|_", "|.~.Category|_"
   "``customers``", "|..Client.customers|_", "|.~.CustomerSearch|_", "|.~.Customer|_"
   "``endpoint``", "``Client.search('endpoint')``", "|.~.SearchQuery|_", "|.~.APIResponse|_"

...

⚙ Installing MyMagento

To install using pip::

pip install my-magento

Please note that MyMagento requires Python >= 3.10

...

📚 Documentation


Full documentation can be found on `ReadTheDocs <https://my-magento.readthedocs.io/en/latest/>`_

|

QuickStart: Login with MyMagento

MyMagento uses the |.~.Client|_ class to handle all interactions with the API.

.. raw:: html

💡 Tip .. raw:: html
See `Get a Magento 2 REST API Token With MyMagento `_ for full details on generating an access token .. raw:: html

Setting the Login Credentials

Creating a |.~.Client|_ requires a domain, username, and password at minimum.

.. code-block:: python

domain = 'website.com' username ='username' password = 'password'

If you're using a local installation of Magento you'll need to set local=True. Your domain should look like this:

.. code-block:: python

domain = '127.0.0.1/path/to/magento'

...

Getting a |.~.Client|_

Option 1: Initialize a |.~.Client|_ Directly ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

  from magento import Client

  >>> api = Client(domain, username, password, **kwargs)

Option 2: Call |.~.getapi| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

  import magento

  >>> api = magento.get_api(**kwargs)

|..getapi| takes the same keyword arguments as the |.~.Client|_

If the domain, username, or password are missing, it will attempt to use the following environment variables:

.. code-block:: python

import os

os.environ['MAGENTO_DOMAIN'] = domain os.environ['MAGENTO_USERNAME']= username os.environ['MAGENTO_PASSWORD']= password

...

Getting an |.~.ACCESSTOKEN|

Unless you specify login=False, the |.~.Client| will automatically call |.~.authenticate| once initialized:

.. code-block:: python

api.authenticate()

Performing a |.~.search|_


.. |api_endpoints| replace:: API endpoint
.. _api_endpoints: https://adobe-commerce.redoc.ly/2.3.7-admin/

The |..Client.search|_ method lets you |.~.execute|_ a query on
any |api_endpoints|_

It creates a |.~.SearchQuery|_ for the endpoint,
allowing you to retrieve data about

* An individual item (ex. |.~.SearchQuery.by_id|_)
* A list of items (ex. |.~.SearchQuery.by_list|_)
* Any search criteria you desire (see `Building Custom Search Queries <https://my-magento.readthedocs.io/en/latest/interact-with-api.html#custom-queries>`_)

...

Example: |.~.search|_ an endpoint |.~.by_id|_
=====================================================

.. code-block:: python

    # Query the "invoices" endpoint (also: api.invoices)
    >>> api.search("invoices").by_id(1)

    <Magento Invoice: "#000000001"> for <Magento Order: "#000000001" placed on 2022-11-01 03:27:33>

Example: |.~.search|_ an endpoint |.~.by_list|_
=======================================================

.. code-block:: python

    # Retrieve invoices from a list of invoice ids
    >>> ids = list(range(1,101))
    >>> api.invoices.by_list("entity_id", ids)

    [<Magento Invoice: "#000000001"> for <Magento Order: "#000000001" placed on 2022-11-01 03:27:33>, ...]

...

Search Results: The |.~.Model|_ Classes

.. |the_models| replace:: the magento.models subpackage .. _the_models: models.html

These classes make the API response data easier to work with.

They also provide endpoint-specific methods to update store data and search for related items.

Example: Retrieving every |.~.Order| containing a |.~.Product|

Let's retrieve a |.~.Product|_ using |.~.ProductSearch.bysku|

.. code-block:: python

product = api.products.by_sku("24-MB01")

We can search for orders containing this product in multiple ways:

.. code-block:: python

# Using the Product itself
>>> product.get_orders()

[<Magento Order: "#000000003" placed on 2022-12-21 08:09:33>, ... ]

# Using an OrderSearch
>>> api.orders.by_product(product)
>>> api.orders.by_product_id(product.id)
>>> api.orders.by_sku(product.sku)

[<Magento Order: "#000000003" placed on 2022-12-21 08:09:33>, ... ]

Example: Retrieving all |.~.Product|\s and |.~.Invoice|\s for a |.~.Category|_

.. code-block:: python

>>> category = api.categories.by_name("Watches")
>>> category.get_products()
>>> category.get_invoices()

[<Magento Product: 24-MG04>, <Magento Product: 24-MG01>, <Magento Product: 24-MG03>, ... ]
[<Magento Invoice: "#000000004"> for <Magento Order: "#000000004" placed on 2022-11-14 03:27:33>, ... ]

Example: Updating the Thumbnail |.~.MediaEntry| of a |.~.Product|

.. code-block:: python

# Update product thumbnail label on specific store view

product.thumbnail.set_alt_text("bonjour", scope="FR") print(product.thumbnail)

<MediaEntry 3417 for <Magento Product: 24-MB01>: bonjour>

...

.. raw:: html

💡 Tip: Set the Store Scope .. raw:: html
If you have multiple store views, a ``store_code`` can be specified when retrieving/updating data * The \|..Client.scope\|_ is used by default - simply change it to switch store \|.~.views\|_ * Passing the ``scope`` keyword argument to \|..Client.url_for\|_, \|..Model.refresh\|_, and some Model update methods will temporarily override the Client scope .. raw:: html

...

.. _Custom Queries:

Building Custom Search Queries


In addition to the predefined methods, you can also build your own queries

* Simply |.~.add_criteria|_, |.~.restrict_fields|_, and |.~.execute|_ the search
* The |.~.since|_ and |.~.until|_ methods allow you to further filter your query by date

.. raw:: html

   <table>
       <tr align="left">
           <th>

📋 Example: Retrieve Orders Over $50 Placed Since the Start of 2023

.. raw:: html

   </th>
   <tr><td>

.. code-block:: python

 >>> api.orders.add_criteria(
 ...    field="grand_total",
 ...    value="50",
 ...    condition="gt"
 ... ).since("2023-01-01").execute()

 [<Magento Order: "#000000012" placed on 2023-01-02 05:19:55>, ...]

.. raw:: html

   </td></tr>
   </table>

...

Making Authorized Requests

You can use this URL to make an authorized |.~.get|, |.~.post|, |.~.put|, or |.~.delete| request.

Example: Making a |.~.get|_ Request

.. code-block:: python

Request the data for credit memo with id 7

url = api.url_for('creditmemo/7') response = api.get(url) print(response.json())

{'adjustment': 1.5, 'adjustment_negative': 0, 'adjustment_positive': 1.5, 'base_adjustment': 1.5, ... }

.. raw:: html

📝 Note .. raw:: html
A \|.~.search\|_ is simpler than making \|.~.get\|_ requests, as the result will be wrapped by \|.~.APIResponse\|_ or other \|.~.Model\|_ .. code-block:: python # Retrieve credit memo with id 7 using a search >>> memo = api.search("creditmemo").by_id(7) >>> print(memo.data) >>> print(memo) {'adjustment': 1.5, 'adjustment_negative': 0, 'adjustment_positive': 1.5, 'base_adjustment': 1.5, ... } .. raw:: html

📝 Note .. raw:: html

A |.~.search|_ is simpler than making |.~.get|_ requests, as the result will be wrapped by |.~.APIResponse|_ or other |.~.Model|_ .. code-block:: python # Retrieve credit memo with id 7 using a search >>> memo = api.search("creditmemo").by_id(7) >>> print(memo.data) >>> print(memo) {'adjustment': 1.5, 'adjustment_negative': 0, 'adjustment_positive': 1.5, 'base_adjustment': 1.5, ... } .. raw:: html

TDKorn / my-magento

readme

MyMagento🛒

Setting the Login Credentials

Getting a |.~.Client|_

Getting an |.~.ACCESSTOKEN|

Example: Retrieving every |.~.Order| containing a |.~.Product|

Example: Retrieving all |.~.Product|\s and |.~.Invoice|\s for a |.~.Category|_

Example: Updating the Thumbnail |.~.MediaEntry| of a |.~.Product|

Example: Making a |.~.get|_ Request

Request the data for credit memo with id 7