Show a deprecation notice that points to lstk aws

.github/workflows/integration.yml

@@ -17,7 +17,8 @@ jobs:
     strategy:
       matrix:
         include:
-          - { python-version: '3.13', awscli-version: "1.41.0", region: us-west-1, access-key-id: '000000000001'}
+          # boto3 must match the botocore version that this awscli version pins
+          - { python-version: '3.13', awscli-version: "1.41.0", boto3-version: "1.39.0", region: us-west-1, access-key-id: '000000000001'}
           - { python-version: '3.13', region: us-west-1, access-key-id: 'test'}
           - { python-version: '3.12', region: us-east-1, access-key-id: 'test'}
           - { python-version: '3.11', region: us-east-1, access-key-id: 'test'}
@@ -46,7 +47,7 @@ jobs:
 
       - name: Install specific version of awscli
         if: ${{ matrix.awscli-version }}
-        run: pip install "awscli==${{ matrix.awscli-version }}"
+        run: pip install "awscli==${{ matrix.awscli-version }}" "boto3==${{ matrix.boto3-version }}"
 
       - name: Check aws-cli version
         run: |

README.md

@@ -2,6 +2,16 @@
 
 [![PyPI version][pypi-version]][pypi]
 
+> [!WARNING]
+> **`awslocal` is deprecated. Use `lstk aws` instead.**
+>
+> `awslocal` no longer receives updates.
+>
+> - Get started with `lstk`, the new LocalStack CLI: [docs.localstack.cloud/.../lstk](https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/)
+> - Switch your scripts and CI workflows to `lstk aws`: [docs.localstack.cloud/.../lstk/migration](https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/migration/#infrastructure-as-code)
+>
+> `lstk aws` does not install the AWS CLI for you. If you used `awscli-local[ver1]` to install it, [install the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) separately before you switch.
+
 This package provides the `awslocal` command, which is a thin wrapper around the `aws`
 command line interface for use with [LocalStack](https://github.com/localstack/localstack).
 
@@ -23,7 +33,7 @@ Note that the command above also installs the latest version of the underlying A
 pip install awscli-local
 ```
 
-**Note:** Automatic installation of AWS CLI version 2 is currently not supported yet (at the time of writing there is no official pypi package for `v2` available), but the `awslocal` technically also works with AWS CLI v2 (see [this section](#Limitations) for more details).
+**Note:** Automatic installation of AWS CLI version 2 is not supported, because there is no official PyPI package for `v2`. `awslocal` still works with AWS CLI v2 if you install it yourself (see [this section](#Limitations) for more details).
 
 ## Usage
 
@@ -51,6 +61,7 @@ You can use the following environment variables for configuration:
   Useful when you have LocalStack bound to a different host (e.g., within docker-compose).
 * `LOCALSTACK_HOST` (deprecated): A <hostname>:<port> variable defining where to find LocalStack (default: localhost:4566).
 * `USE_SSL` (deprecated): Whether to use SSL when connecting to LocalStack (default: False).
+* `DISABLE_DEPRECATION_NOTICE`: Set to `1` to hide the deprecation notice (default: unset).
 
 ## Completion
 
@@ -97,6 +108,7 @@ pip install https://github.com/boto/botocore/archive/v2.zip https://github.com/a
 
 ## Change Log
 
+* v0.23.0: Print a deprecation notice that points to `lstk aws`
 * v0.22.2: Display full stack traces only in `--debug` mode; non-debug runs now show concise error messages, consistent with `awscli` behavior.
 * v0.22.1: Fix issue with cfn package and cfn deploy with awscli >= 1.41.9
 * v0.22.0: Use fallback for endpoint detection. Should prevent most cases of `Unable to find LocalStack endpoint for service ...`

bin/awslocal

@@ -34,6 +34,10 @@ ENV_VARS_TO_PASS = ['PATH', 'PYTHONPATH', 'SYSTEMROOT', 'HOME', 'TERM', 'PAGER']
 # service names without endpoints
 NO_ENDPOINT_SERVICES = ('help', 'configure')
 
+LSTK_DOCS_URL = 'https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/'
+LSTK_MIGRATION_URL = (
+    'https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/migration/#infrastructure-as-code')
+
 from localstack_client import config  # noqa: E402
 
 
@@ -59,6 +63,34 @@ def usage():
     print(__doc__.strip())
 
 
+def print_deprecation_notice():
+    """Point users to 'lstk aws'. Goes to stderr to keep stdout clean."""
+    if os.environ.get('DISABLE_DEPRECATION_NOTICE', '').lower().strip() in ('1', 'true'):
+        return
+
+    separator = '=' * 76
+    message = '\n'.join([
+        separator,
+        "  WARNING: 'awslocal' is deprecated. Use 'lstk aws' instead.",
+        separator,
+        '',
+        "  'awslocal' no longer receives updates.",
+        '',
+        "  Get started with 'lstk', the new LocalStack CLI:",
+        '  %s' % LSTK_DOCS_URL,
+        '',
+        "  Switch your scripts and CI workflows to 'lstk aws':",
+        '  %s' % LSTK_MIGRATION_URL,
+        '',
+        separator,
+        '',
+        "Continuing with 'awslocal'...",
+        '',
+    ])
+    # flush now, since the aws CLI may replace this process next
+    print(message, file=sys.stderr, flush=True)
+
+
 def run(cmd, env=None):
     """
     Replaces this process with the AWS CLI process, with the given command and environment
@@ -81,6 +113,7 @@ def awscli_is_v1():
 
 
 def main():
+    print_deprecation_notice()
     if len(sys.argv) > 1 and sys.argv[1] == '-h':
         return usage()
     try:

setup.py

@@ -16,7 +16,7 @@
 
     setup(
         name='awscli-local',
-        version='0.22.2',
+        version='0.23.0',
         description=description,
         long_description=README,
         long_description_content_type='text/markdown',

tests/bin/test.deprecation.bats

@@ -0,0 +1,19 @@
+#!/usr/bin/env bats
+
+@test "deprecation notice goes to stderr" {
+  run bash -c "awslocal --version 2>&1 >/dev/null"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"WARNING: 'awslocal' is deprecated. Use 'lstk aws' instead."* ]]
+}
+
+@test "deprecation notice stays out of stdout" {
+  run bash -c "awslocal --version 2>/dev/null"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"deprecated"* ]]
+}
+
+@test "deprecation notice can be turned off" {
+  run bash -c "DISABLE_DEPRECATION_NOTICE=1 awslocal --version 2>&1"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"'awslocal' is deprecated"* ]]
+}