Release 4.1.0

alexdlaird-bot[bot] · web-flow · commit 4094f7565e4c · 2026-05-03T14:46:19.000Z
### Added

- Python 3.13 support.

### Changed

- `amazoncaptcha` is now an optional dependency. Install with `pip install amazon-orders[captcha]` to enable Captcha auto-solve (only compatible with Python &lt;=3.12. When not installed, Captcha challenges fall back to manual entry.

### Deprecated

- Captcha auto-solve via `amazoncaptcha` is likely to be removed in the future, since Amazon has continued to phase out OCR-style Captchas in favor of WAF.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -30,6 +30,8 @@ jobs:
         os: [ ubuntu-latest, macos-latest, windows-latest ]
         python-version: [ "3.12" ]
         include:
+          - python-version: "3.13"
+            os: ubuntu-latest
           - python-version: "3.11"
             os: ubuntu-latest
           - python-version: "3.9"
@@ -51,6 +53,31 @@ jobs:
       - name: Test
         run: make test
 
+  build-captcha:
+    name: Build (3.12, [captcha] extra)
+
+    env:
+      FORCE_COLOR: 1
+      PYTHONUNBUFFERED: 1
+      PYTHONDONTWRITEBYTECODE: 1
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install jpeg
+        run: sudo apt-get install -y libjpeg-dev zlib1g-dev
+      - name: Install with [captcha] extra
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[dev,captcha]"
+      - name: Test
+        run: python -m pytest -v --ignore=tests/integration
+
   validate:
     name: Validate
     uses: ./.github/workflows/validate.yml
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -17,7 +17,6 @@ on:
 
 permissions:
   contents: write
-  pull-requests: read
 
 jobs:
   prereq:
@@ -26,11 +25,9 @@ jobs:
       bump_type: ${{ inputs.bump_type }}
       version_file: 'amazonorders/__init__.py'
       version_pattern: 's/^__version__ = ".*"/__version__ = "${VERSION}"/'
-      additional_bump_command: |
-        sed -i "s/==${OLD_VERSION}/==${NEW_VERSION}/g" docs/index.rst
-        grep -q "==${NEW_VERSION}" docs/index.rst || { echo "::error::Version bump failed in docs/index.rst"; exit 1; }
-        sed -i "s/==${OLD_VERSION}/==${NEW_VERSION}/g" README.md
-        grep -q "==${NEW_VERSION}" README.md || { echo "::error::Version bump failed in README.md"; exit 1; }
+      additional_bump_files: |
+        docs/index.rst
+        README.md
       repo_slug: alexdlaird/amazon-orders
     secrets:
       bot_app_id: ${{ secrets.RELEASE_BOT_APP_ID }}
@@ -98,8 +95,6 @@ jobs:
     needs: [prereq, release]
     if: always() && needs.prereq.result == 'success'
     uses: alexdlaird/.github/.github/workflows/release-cleanup.yml@main
-    with:
-      squash_boundary: ${{ needs.prereq.outputs.squash_boundary }}
     secrets:
       bot_app_id: ${{ secrets.RELEASE_BOT_APP_ID }}
       bot_private_key: ${{ secrets.RELEASE_BOT_PRIVATE_KEY }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,14 +4,32 @@ All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased](https://github.com/alexdlaird/amazon-orders/compare/4.0.19...HEAD)
+## [Unreleased](https://github.com/alexdlaird/amazon-orders/compare/4.1.0...HEAD)
+
+## [4.1.0](https://github.com/alexdlaird/amazon-orders/compare/4.0.19...4.1.0) - 2026-05-03
+
+### Added
+
+- Python 3.13 support.
+
+### Changed
+
+- `amazoncaptcha` is now an optional dependency. Install with `pip install amazon-orders[captcha]` to enable Captcha auto-solve (only compatible with Python <=3.12. When not installed, Captcha challenges fall back to manual entry.
+
+### Deprecated
+
+- Captcha auto-solve via `amazoncaptcha` is likely to be removed in the future, since Amazon has continued to phase out OCR-style Captchas in favor of WAF.
 
 ## [4.0.19](https://github.com/alexdlaird/amazon-orders/compare/4.0.18...4.0.19) - 2026-04-29
 
 ### Added
 
 - Build and stability improvements.
 
+### Added
+
+- Build and stability improvements.
+
 ## [4.0.18](https://github.com/alexdlaird/amazon-orders/compare/4.0.17...4.0.18) - 2025-12-06
 
 ### Added
diff --git a/README.md b/README.md
@@ -25,9 +25,20 @@ pip install amazon-orders --upgrade
 
 That's it! `amazon-orders` is now available as a package to your Python projects and from the command line.
 
-If pinning, be sure to use a wildcard for the [minor version](https://semver.org/) (ex. `==4.0.*`, not `==4.0.19`) to
+If pinning, be sure to use a wildcard for the [minor version](https://semver.org/) (ex. `==4.0.*`, not `==4.1.0`) to
 ensure you always get the latest stable release.
 
+To enable Captcha auto-solve on Python <=3.12 (via the optional [`amazoncaptcha`](https://pypi.org/project/amazoncaptcha/)
+dependency), install with the `captcha` extra:
+
+```sh
+pip install "amazon-orders[captcha]" --upgrade
+```
+
+Without this extra, Captcha challenges fall back to manual entry. `amazoncaptcha` is not available on Python 3.13+;
+see [Captcha Blocking Login](https://amazon-orders.readthedocs.io/troubleshooting.html#captcha-blocking-login) for
+details.
+
 ## Basic Usage
 
 You'll use [`AmazonSession`](https://amazon-orders.readthedocs.io/api.html#amazonorders.session.AmazonSession) to
diff --git a/SECURITY.md b/SECURITY.md
@@ -4,8 +4,8 @@
 
 | Version | Supported          |
 |---------|--------------------|
-| 4.0.x   | :white_check_mark: |
-| < 4.0   | :x:                |
+| 4.1.x   | :white_check_mark: |
+| < 4.1   | :x:                |
 
 ## Reporting a Vulnerability
 
diff --git a/amazonorders/__init__.py b/amazonorders/__init__.py
@@ -1,3 +1,3 @@
 __copyright__ = "Copyright (c) 2024-2025 Alex Laird"
 __license__ = "MIT"
-__version__ = "4.0.19"
+__version__ = "4.1.0"
diff --git a/amazonorders/forms.py b/amazonorders/forms.py
@@ -9,10 +9,14 @@
 
 import pyotp
 from PIL import Image
-from amazoncaptcha import AmazonCaptcha
 from bs4 import Tag
 from requests import Response
 
+try:
+    from amazoncaptcha import AmazonCaptcha
+except ImportError:  # pragma: no cover
+    AmazonCaptcha = None  # type: ignore[assignment, misc]
+
 from amazonorders import util
 from amazonorders.conf import AmazonOrdersConfig
 from amazonorders.exception import AmazonOrdersAuthError, AmazonOrdersError
@@ -26,7 +30,9 @@ class AuthForm(ABC):
     """
     The base class of an authentication ``<form>`` that can be submitted.
 
-    The base implementation will attempt to auto-solve Captcha. If this fails, it will
+    The base implementation will attempt to auto-solve Captcha when the optional
+    ``amazoncaptcha`` dependency is installed (``pip install amazon-orders[captcha]``,
+    available on Python <=3.12 only). If auto-solve is unavailable or fails, it will
     use the default image view to show the Captcha prompt, and it will also pass the
     image URL to :func:`~amazonorders.session.IODefault.prompt` as ``img_url``.
     """
@@ -131,13 +137,22 @@ def _solve_captcha(self,
                 "Call AuthForm.select_form() first."
             )  # pragma: no cover
 
-        captcha_response = AmazonCaptcha.fromlink(url).solve()
+        if AmazonCaptcha is not None:
+            captcha_response = AmazonCaptcha.fromlink(url).solve()
+        else:
+            captcha_response = None
+
         if not captcha_response or captcha_response.lower() == "not solved":
             img_response = self.amazon_session.session.get(url)
             img = Image.open(BytesIO(img_response.content))
             img.show()
 
-            self.amazon_session.io.echo("Info: The Captcha couldn't be auto-solved.")
+            if AmazonCaptcha is None:
+                self.amazon_session.io.echo(
+                    "Info: Captcha auto-solve is unavailable. Install with "
+                    "`pip install amazon-orders[captcha]` to enable it (only compatible with Python <=3.12.")
+            else:
+                self.amazon_session.io.echo("Info: The Captcha couldn't be auto-solved.")
 
             captcha_response = self.amazon_session.io.prompt("Enter the characters shown in the image",
                                                              img_url=url)
diff --git a/docs/index.rst b/docs/index.rst
@@ -44,7 +44,7 @@ using ``pip``:
 
 That's it! ``amazon-orders`` is now available as a package to your Python projects and from the command line.
 
-If pinning, be sure to use a wildcard for the `minor version <https://semver.org/>`_ (ex. ``==4.0.*``, not ``==4.0.19``)
+If pinning, be sure to use a wildcard for the `minor version <https://semver.org/>`_ (ex. ``==4.0.*``, not ``==4.1.0``)
 to ensure you always get the latest stable release.
 
 Basic Usage
diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst
@@ -47,6 +47,23 @@ and still other—like `Amazon's puzzle-based WAF Captchas <https://docs.aws.ama
 —require JavaScript and can't be solved at all by ``amazon-orders`` and block it from being able to log in (see `issue #45 <https://github.com/alexdlaird/amazon-orders/issues/45>`_
 for more details).
 
+Auto-solving of legacy text-based Captchas is provided by the `amazoncaptcha <https://pypi.org/project/amazoncaptcha/>`_
+library, which is an optional dependency. To enable it on **Python <=3.12**, install with the ``captcha``
+extra:
+
+.. code-block:: shell
+
+    pip install amazon-orders[captcha]
+
+.. note::
+
+   The ``[captcha]`` extra is **only available on Python <=3.12+**. ``amazoncaptcha`` pins ``pillow<9.6.0``, which is
+   incompatible with Python 3.13 until that constraint is lifted from the upstream dependency.
+
+When this extra is not installed, Captcha challenges fall back to manually entering the
+solution. As Amazon has largely phased out this style of Captcha in favor of WAF, auto-solve may be removed
+entirely in a future major release.
+
 To attempt to fully automate login, you need to minimize how often (if at all) you are presented with Captcha
 challenges. There is no perfect workaround to this, as when and how challenges are presented is at the discretion of
 Amazon, but there are at least a few ways you can try to reduce the likelihood you will be presented with
diff --git a/pyproject.toml b/pyproject.toml
@@ -10,7 +10,7 @@ requires-python = ">=3.9"
 dependencies = [
     "click>=7.1",
     "requests>=2.23",
-    "amazoncaptcha>=0.4",
+    "Pillow>=9.0.1",
     "beautifulsoup4>=4.12",
     "PyYAML>=5.1",
     "python-dateutil>=2.8",
@@ -27,18 +27,23 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 
 [project.optional-dependencies]
+captcha = [
+    "amazoncaptcha>=0.4",
+]
 dev = [
     "pytest",
     "coverage[toml]",
     "flake8",
     "flake8-pyproject",
     "pep8-naming",
     "responses",
-    "lxml"
+    "lxml",
+    "amazoncaptcha>=0.4; python_version < '3.13'",
 ]
 integration = [
     "pytest-rerunfailures",
diff --git a/tests/unit/test_session.py b/tests/unit/test_session.py
@@ -13,6 +13,13 @@
 from amazonorders.session import AmazonSession
 from tests.unittestcase import UnitTestCase
 
+try:
+    import amazoncaptcha  # noqa: F401
+
+    HAS_AMAZONCAPTCHA = True
+except ImportError:
+    HAS_AMAZONCAPTCHA = False
+
 
 class TestSession(UnitTestCase):
     def setUp(self):
@@ -285,6 +292,7 @@ def test_amazon_blocks_auth(self):
         self.assertIn("The page https://www.amazon.com/ap/signin returned 503. Amazon had an issue on "
                       "their end, or may be temporarily blocking your requests.", str(cm.exception))
 
+    @unittest.skipUnless(HAS_AMAZONCAPTCHA, "amazoncaptcha optional dependency not installed")
     @responses.activate
     def test_captcha_1(self):
         # GIVEN
@@ -357,6 +365,7 @@ def test_captcha_1(self):
         self.assertEqual(1, resp4.call_count)
         self.assertEqual(1, resp5.call_count)
 
+    @unittest.skipUnless(HAS_AMAZONCAPTCHA, "amazoncaptcha optional dependency not installed")
     @responses.activate
     def test_captcha_2(self):
         # GIVEN
@@ -416,6 +425,7 @@ def test_captcha_2(self):
         self.assertEqual(1, resp5.call_count)
         self.given_login_responses_success()
 
+    @unittest.skipUnless(HAS_AMAZONCAPTCHA, "amazoncaptcha optional dependency not installed")
     @responses.activate
     def test_captcha_3(self):
         # GIVEN
@@ -514,9 +524,12 @@ def test_captcha_1_hard(self, show_mock, input_mock):
         self.assertEqual(1, resp1.call_count)
         self.assertEqual(1, resp2.call_count)
         self.assertEqual(1, resp3.call_count)
-        self.assertEqual(2, resp4.call_count)
+        # When amazoncaptcha is installed, the image URL is fetched twice (once by the solver,
+        # once by the manual-prompt fallback); without it, only the fallback fetch happens.
+        self.assertEqual(2 if HAS_AMAZONCAPTCHA else 1, resp4.call_count)
         self.assertEqual(1, resp5.call_count)
 
+    @unittest.skipUnless(HAS_AMAZONCAPTCHA, "amazoncaptcha optional dependency not installed")
     @responses.activate
     def test_captcha_loop_retries_exhausted(self):
         # GIVEN
