Metadata-Version: 2.4
Name: ebay_rest
Version: 1.1.0
Summary: Wraps the eBay REST APIs.
Author-email: Peter JOHN Matecsa <matecsaj@gmail.com>
License: MIT License
        
        Copyright (c) 2021 Peter JOHN Matecsa
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/matecsaj/ebay_rest
Project-URL: Repository, https://github.com/matecsaj/ebay_rest.git
Project-URL: Issues, https://github.com/matecsaj/ebay_rest/issues
Keywords: ebay,api,rest
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Topic :: Internet
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi
Requires-Dist: cryptography
Requires-Dist: requests
Requires-Dist: python-dateutil
Requires-Dist: six
Requires-Dist: urllib3
Provides-Extra: complete
Requires-Dist: playwright; extra == "complete"
Provides-Extra: dev
Requires-Dist: aiofiles; extra == "dev"
Requires-Dist: aiohttp; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: bs4; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: chardet; extra == "dev"
Requires-Dist: CurrencyConverter; extra == "dev"
Requires-Dist: pipreqs; extra == "dev"
Requires-Dist: setuptools; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Dynamic: license-file

# ebay_rest
A Python 3 pip package that wraps eBay’s REST APIs.

## Table of Contents
- [Installation](#installation)
  - [Basic Installation](#basic-installation)
  - [Complete Installation](#complete-installation)
- [Setup](#setup)
- [Usage](#usage)
- [FAQ](#faq)
- [Optimization & Performance](#optimization--performance)
- [Contributing](#contributing)
- [Legal](#legal)

---

## Installation

### Basic Installation
The basic installation provides core functionality without browser automation. It is lighter, easier to install, and sufficient for most use cases.

```bash
pip install ebay_rest
```

### Complete Installation
The complete installation includes browser automation for getting eBay user tokens.

```bash
pip install ebay_rest[complete]
```
After installing the package, install Playwright and Chromium:
```bash
playwright install chromium
```
**Note:** Playwright may require additional system dependencies. See [Playwright installation guide](https://playwright.dev/python/docs/intro) for details.

---

## Setup
Follow the setup instructions in the [example configuration file](https://github.com/matecsaj/ebay_rest/blob/main/ebay_rest_EXAMPLE.json).

---

## Usage
Here is a basic example of using `ebay_rest` to retrieve eBay's global site IDs and search for iPhones:

```python
from ebay_rest import API, DateTime, Error, Reference

print(f"eBay's official date and time is {DateTime.to_string(DateTime.now())}.\n")

print("All valid eBay global id values, also known as site ids.")
print(Reference.get_global_id_values(), '\n')

try:
    api = API(application='production_1', user='production_1', header='US')
except Error as error:
    print(f'Error {error.number} is {error.reason}  {error.detail}.\n')
else:
    try:
        print("The five least expensive iPhone things now for sale on-eBay:")        
        for record in api.buy_browse_search(q='iPhone', sort='price', limit=5):
            if 'record' not in record:
                pass    # TODO Refer to non-records, they contain optimization information.
            else:
                item = record['record']
                print(f"item id: {item['item_id']} {item['item_web_url']}")
    except Error as error:
        print(f'Error {error.number} is {error.reason} {error.detail}.\n')
    else:
        pass

print("\nClass documentation:")
print(help(API))    # Over a hundred methods are available!
print(help(DateTime))
print(help(Error))
print(help(Reference))
```

Look to the [unit tests](https://github.com/matecsaj/ebay_rest/blob/main/tests/test_ebay_rest.py) for more example code.


---

## FAQ

<details>
  <summary><strong>How are API results structured?</strong></summary>
  <ul>
    <li>Basic types: strings, integers, dates.</li>
    <li><code>dict</code> (objects): Groups related elements.</li>
    <li><code>list</code> (arrays): Repetitive structures with one or more elements.</li>
    <li>Optional elements may be omitted, mandatory elements are set to <code>None</code> if empty.</li>
  </ul>
</details>

<details>
  <summary><strong>How are paged API results handled?</strong></summary>
  <ul>
    <li>A Python <a href="https://www.python.org/dev/peps/pep-0255/">generator</a> is used instead of a list.</li>
    <li>Do <strong>not</strong> supply an "offset" parameter.</li>
    <li>"limit" controls how many records to retrieve.</li>
    <li>To retrieve all records, omit "limit." Be aware of eBay's 10,000 record count limit.</li>
  </ul>
</details>

<details>
  <summary><strong>Can the browser automation be avoided?</strong></summary>
  <p>Yes, reuse the refresh token after the first retrieval. Modify your <code>ebay_rest.json</code> file:</p>
  <pre>
"refresh_token": "your_refresh_token",
"refresh_token_expiry": "your_token_expiry"
  </pre>
</details>

<details>
  <summary><strong>Does this library support threading/multiprocessing?</strong></summary>
  <p>Threading is safe. Multiprocessing is untested (<a href="https://github.com/matecsaj/ebay_rest/issues/20">help wanted</a>).</p>
</details>

<details>
  <summary><strong>Why does eBay return "Internal Error"?</strong></summary>
  <p>Making repeated calls with the same parameters in a short time can trigger this error.</p>
</details>

---

## Optimization & Performance
To optimize API calls:
1. **Cache responses** to avoid redundant API calls.
2. **Use filters** to limit response data.
3. **Use generators** instead of lists for paged results.
4. **Utilize threading** (but be mindful of rate limits).
5. **Reuse the API instance** to avoid unnecessary authentication overhead.
6. **Optimize your network** (faster internet connection, lower latency).

---

## Contributing
Contributions are welcome! Please fork this repository and submit a pull request. Follow the coding standards outlined in [`CONTRIBUTING.md`](CONTRIBUTING.md).

---

## Legal
- Licensed under [MIT](https://github.com/matecsaj/ebay_rest/blob/main/LICENSE).
- "Python" is a trademark of the [Python Software Foundation](https://www.python.org/psf/).
- "eBay" is a trademark of [eBay Inc](https://www.ebay.com).
- This project is **not affiliated with or endorsed by eBay Inc.**

