Merge branch 'add-ruff-and-uv' into implement-offers-v2

Author: sergioteula

.github/workflows/check.yml

@@ -10,6 +10,24 @@ permissions:
   pull-requests: read
 
 jobs:
+  changelog:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Check CHANGELOG was updated
+        run: |
+          if git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -q "^CHANGELOG.md$"; then
+            echo "✅ CHANGELOG.md was updated"
+          else
+            echo "❌ ERROR: CHANGELOG.md was not updated"
+            echo "Please add your changes to the CHANGELOG.md file"
+            exit 1
+          fi
+
   check:
     runs-on: ubuntu-latest
     env:
@@ -56,8 +74,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version:
-          ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14", "3.15"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14", "3.15"]
 
     steps:
       - uses: actions/checkout@v5

.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Create Release
+
+on:
+    workflow_dispatch:
+
+permissions:
+    contents: write
+
+jobs:
+    release:
+        runs-on: ubuntu-latest
+        if: github.ref == 'refs/heads/master'
+
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@v5
+
+            - name: Extract version and notes from CHANGELOG
+              id: changelog
+              run: |
+                  # Extract version from first ## [x.x.x] header
+                  VERSION=$(grep -m1 -oP '## \[\K[0-9]+\.[0-9]+\.[0-9]+' CHANGELOG.md)
+                  echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+                  # Extract release notes (content between first and second ## headers)
+                  NOTES=$(awk '/^## \['"$VERSION"'\]/{flag=1; next} /^## \[/{flag=0} flag' CHANGELOG.md)
+
+                  # Handle multiline output
+                  {
+                    echo "notes<<EOF"
+                    echo "$NOTES"
+                    echo "EOF"
+                  } >> $GITHUB_OUTPUT
+
+            - name: Check if tag already exists
+              id: check_tag
+              run: |
+                  if git rev-parse "v${{ steps.changelog.outputs.version }}" >/dev/null 2>&1; then
+                    echo "exists=true" >> $GITHUB_OUTPUT
+                  else
+                    echo "exists=false" >> $GITHUB_OUTPUT
+                  fi
+
+            - name: Create Release
+              if: steps.check_tag.outputs.exists == 'false'
+              uses: softprops/action-gh-release@v2
+              with:
+                  tag_name: ${{ steps.changelog.outputs.version }}
+                  name: v${{ steps.changelog.outputs.version }}
+                  body: ${{ steps.changelog.outputs.notes }}
+                  draft: false
+                  prerelease: false
+
+            - name: Skip release (tag exists)
+              if: steps.check_tag.outputs.exists == 'true'
+              run: |
+                  echo "⚠️ Tag v${{ steps.changelog.outputs.version }} already exists. Skipping release creation."
+                  exit 1

.pre-commit-config.yaml

@@ -52,3 +52,10 @@ repos:
         entry: "bash -c 'set -a && source .env 2>/dev/null; set +a && uv run pytest -rs --cov=amazon_paapi'"
         types_or: [python]
         pass_filenames: false
+
+      - id: version-check
+        name: Check version consistency
+        language: system
+        entry: uv run python scripts/check_version.py
+        files: (CHANGELOG\.md|pyproject\.toml|docs/conf\.py)$
+        pass_filenames: false

.readthedocs.yml

@@ -1,22 +1,21 @@
-# .readthedocs.yaml
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
-# Required
 version: 2
 
-# Build documentation in the docs/ directory with Sphinx
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
 sphinx:
-   configuration: docs/conf.py
+  configuration: docs/conf.py
 
-# Optionally build your docs in additional formats such as PDF
 formats:
-   - pdf
+  - pdf
 
-# Optionally set the version of Python and requirements required to build your docs
 python:
-   version: 3
-   install:
-     - method: pip
-       path: .
-     - requirements: docs/requirements.txt
+  install:
+    - method: pip
+      path: .
+    - requirements: docs/requirements.txt

CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [5.1.0] - 2026-01-11
+
+### Added
+
+- Integration tests with real Amazon API calls
+- Type hints throughout the codebase using `Literal` types for country codes
+- `.env.template` file for easier development setup
+- Code style guide for AI assistants (`.agent/rules/code-style-guide.md`)
+- Pre-commit hooks with Ruff integration
+- Version consistency check script (`scripts/check_version.py`)
+- Manual release workflow (`release.yml`) that creates GitHub releases from CHANGELOG
+- CI check to ensure CHANGELOG is updated in every PR
+
+### Changed
+
+- **BREAKING**: Minimum Python version raised from 3.7 to 3.9
+- Migrated from `setup.py` to `pyproject.toml` for project configuration
+- Replaced multiple linters (Flake8, isort, Black, Pylint) with Ruff
+- Replaced Docker-based development environment with `uv` package manager
+- Consolidated coverage, mypy, and pytest configuration into `pyproject.toml`
+- Renamed test files to use `_test.py` suffix instead of `test_` prefix
+- Updated GitHub Actions workflows to use `uv` instead of Docker
+- Improved docstrings across the codebase
+- Completely rewritten README with clearer structure and examples
+- Updated Read the Docs configuration to v2 format with modern Sphinx versions
+
+### Removed
+
+- `setup.py` - replaced by `pyproject.toml`
+- `.coveragerc` - configuration moved to `pyproject.toml`
+- `.flake8` - replaced by Ruff configuration in `pyproject.toml`
+- Docker development environment (`docker/`, `docker-compose.yml`)
+- Legacy shell scripts (`scripts/` directory)
+- Custom git hooks (`.githooks/`) - replaced by pre-commit

README.md

@@ -1,118 +1,129 @@
-# Amazon Product Advertising API 5.0 wrapper for Python
+# Python Amazon PAAPI
 
-A simple Python wrapper for the [last version of the Amazon Product Advertising
-API](https://webservices.amazon.com/paapi5/documentation/quick-start/using-sdk.html).
-This module allows interacting with Amazon using the official API in an easier way.
+A simple Python wrapper for the [Amazon Product Advertising API 5.0](https://webservices.amazon.com/paapi5/documentation/). Easily interact with Amazon's official API to retrieve product information, search for items, and more.
 
 [![PyPI](https://img.shields.io/pypi/v/python-amazon-paapi?color=%231182C2&label=PyPI)](https://pypi.org/project/python-amazon-paapi/)
-[![Python](https://img.shields.io/badge/Python->3.9-%23FFD140)](https://www.python.org/)
+[![Python](https://img.shields.io/badge/Python-≥3.9-%23FFD140)](https://www.python.org/)
 [![License](https://img.shields.io/badge/License-MIT-%23e83633)](https://github.com/sergioteula/python-amazon-paapi/blob/master/LICENSE)
 [![Amazon API](https://img.shields.io/badge/Amazon%20API-5.0-%23FD9B15)](https://webservices.amazon.com/paapi5/documentation/)
-[![PyPI - Downloads](https://img.shields.io/pypi/dm/python-amazon-paapi?label=Installs)](https://pypi.org/project/python-amazon-paapi/)
+[![Downloads](https://img.shields.io/pypi/dm/python-amazon-paapi?label=Downloads)](https://pypi.org/project/python-amazon-paapi/)
 
 ## Features
 
-- Object oriented interface for simple usage.
-- Get information about a product through its ASIN or URL.
-- Get item variations or search for products on Amazon.
-- Get browse nodes information.
-- Get multiple results at once without the 10 items limitation from Amazon.
-- Configurable throttling to avoid requests exceptions.
-- Type hints to help you coding.
-- Support for [all available countries](https://github.com/sergioteula/python-amazon-paapi/blob/956f639b2ab3eab3f61644ae2ca8ae6500881312/amazon_paapi/models/regions.py#L1).
-- Ask for new features through the [issues](https://github.com/sergioteula/python-amazon-paapi/issues) section.
-- Join our [Telegram group](https://t.me/PythonAmazonPAAPI) for support or development.
-- Check the [documentation](https://python-amazon-paapi.readthedocs.io/en/latest/index.html) for reference.
+- 🎯 **Simple object-oriented interface** for easy integration
+- 🔍 **Product search** by keywords, categories, or browse nodes
+- 📦 **Product details** via ASIN or Amazon URL
+- 🔄 **Item variations** support (size, color, etc.)
+- 🌍 **20+ countries** supported ([full list](https://github.com/sergioteula/python-amazon-paapi/blob/master/amazon_paapi/models/regions.py))
+- ⚡ **Batch requests** to get multiple items without the 10-item limit
+- 🛡️ **Built-in throttling** to avoid API rate limits
+- 📝 **Full type hints** for better IDE support
 
 ## Installation
 
-You can install or upgrade the module with:
-
-    pip install python-amazon-paapi --upgrade
-
-## Usage guide
+```bash
+pip install python-amazon-paapi --upgrade
+```
 
-**Basic usage:**
+## Quick Start
 
 ```python
 from amazon_paapi import AmazonApi
+
+# Initialize the API (get credentials from Amazon Associates)
 amazon = AmazonApi(KEY, SECRET, TAG, COUNTRY)
+
+# Get product information by ASIN
 item = amazon.get_items('B01N5IB20Q')[0]
-print(item.item_info.title.display_value) # Item title
+print(item.item_info.title.display_value)
 ```
 
-**Get multiple items information:**
+## Usage Examples
+
+### Get Multiple Products
 
 ```python
 items = amazon.get_items(['B01N5IB20Q', 'B01F9G43WU'])
 for item in items:
-    print(item.images.primary.large.url) # Primary image url
-    print(item.offers.listings[0].price.amount) # Current price
+    print(item.images.primary.large.url)
+    print(item.offers.listings[0].price.amount)
 ```
 
-**Use URL insted of ASIN:**
+### Use Amazon URL Instead of ASIN
 
 ```python
 item = amazon.get_items('https://www.amazon.com/dp/B01N5IB20Q')
 ```
 
-**Get item variations:**
+### Search Products
 
 ```python
-variations = amazon.get_variations('B01N5IB20Q')
-for item in variations.items:
-    print(item.detail_page_url) # Affiliate url
+results = amazon.search_items(keywords='nintendo switch')
+for item in results.items:
+    print(item.item_info.title.display_value)
 ```
 
-**Search items:**
+### Get Product Variations
 
 ```python
-search_result = amazon.search_items(keywords='nintendo')
-for item in search_result.items:
-    print(item.item_info.product_info.color) # Item color
+variations = amazon.get_variations('B01N5IB20Q')
+for item in variations.items:
+    print(item.detail_page_url)
 ```
 
-**Get browse node information:**
+### Get Browse Node Information
 
 ```python
-browse_nodes = amazon.get_browse_nodes(['667049031', '599385031'])
-for browse_node in browse_nodes:
-    print(browse_node.display_name) # The name of the node
+nodes = amazon.get_browse_nodes(['667049031', '599385031'])
+for node in nodes:
+    print(node.display_name)
 ```
 
-**Get the ASIN from URL:**
+### Extract ASIN from URL
 
 ```python
 from amazon_paapi import get_asin
+
 asin = get_asin('https://www.amazon.com/dp/B01N5IB20Q')
+# Returns: 'B01N5IB20Q'
 ```
 
-**Throttling:**
+### Configure Throttling
 
-Throttling value represents the wait time in seconds between API calls, being the
-default value 1 second. Use it to avoid reaching Amazon request limits.
+Control the wait time between API calls to avoid rate limits:
 
 ```python
-amazon = AmazonApi(KEY, SECRET, TAG, COUNTRY, throttling=4)  # Makes 1 request every 4 seconds
-amazon = AmazonApi(KEY, SECRET, TAG, COUNTRY, throttling=0)  # No wait time between requests
+# Wait 4 seconds between requests
+amazon = AmazonApi(KEY, SECRET, TAG, COUNTRY, throttling=4)
+
+# No throttling (use with caution)
+amazon = AmazonApi(KEY, SECRET, TAG, COUNTRY, throttling=0)
 ```
 
-## Contribution
+## Documentation
 
-Creating pull requests for this repo is higly appreciated to add new features or solve
-bugs. To help during development process, githooks can be activated to run some scripts
-before pushing new commits. This will run checks for code format and tests, to ensure
-everything follows this repo guidelines. Use next command to activate them:
+- 📖 [Full Documentation](https://python-amazon-paapi.readthedocs.io/)
+- 📋 [Changelog](https://github.com/sergioteula/python-amazon-paapi/blob/master/CHANGELOG.md)
+- 💬 [Telegram Support Group](https://t.me/PythonAmazonPAAPI)
 
+## Contributing
+
+Contributions are welcome! To get started:
+
+1. Install [uv](https://docs.astral.sh/uv/) package manager
+2. Clone and set up the project:
+
+```bash
+git clone https://github.com/sergioteula/python-amazon-paapi.git
+cd python-amazon-paapi
+uv sync
+uv run pre-commit install
 ```
-git config core.hooksPath .githooks
-```
 
-The same checks will also run on the repo with GitHub Actions to ensure all tests pass
-before merge.
+3. Copy `.env.template` to `.env` and add your Amazon API credentials for integration tests.
+
+Pre-commit hooks will automatically run Ruff, mypy, and tests before each commit.
 
 ## License
 
-Copyright © 2026 Sergio Abad. See
-[license](https://github.com/sergioteula/python-amazon-paapi/blob/master/LICENSE) for
-details.
+MIT License © 2026 [Sergio Abad](https://github.com/sergioteula)

docs/conf.py

@@ -19,11 +19,11 @@
 # -- Project information -----------------------------------------------------
 
 project = "python-amazon-paapi"
-copyright = "2021, Sergio Abad"
+copyright = "2026, Sergio Abad"
 author = "Sergio Abad"
 
 # The full version, including alpha/beta/rc tags
-release = "4.2.0"
+release = "5.1.0"
 
 
 # -- General configuration ---------------------------------------------------
@@ -38,7 +38,7 @@
 autodoc_typehints = "none"
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
+# templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.