Nov 26, 2024 · Nov 21, 2024 · Nov 21, 2024 · Nov 21, 2024 · Nov 21, 2024 · Nov 22, 2024
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
 name: Build sphinx documentation

 on:
  push:
    paths:
      - 'docs/**'
    branches:
      - main
  workflow_dispatch:

 jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
    - uses: actions/checkout@v3

    - name: Install uv
      uses: astral-sh/setup-uv@v3

    - name: Install project
      run: |
        make install-dev

    - name: Generate docs
      run:
        make sphinx-docs

    - name: Upload artifacts
      uses: actions/upload-artifact@v4
      with:
        name: html-docs
        path: docs/_build/html/

    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      if: github.ref == 'refs/heads/main'
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: docs/_build/html
diff --git a/Makefile b/Makefile
 generate:## Generate the code from the OpenAPI specs
 ./bin/generate.sh

 sphinx-docs:## Generate the documentation; uses the sphinx-generated Makefile in docs to clean and build html
 ($(VENV_RUN); sphinx-apidoc --implicit-namespaces -o docs localstack-sdk-python/localstack)
 $(MAKE) -C docs clean
 $(MAKE) -C docs html

 format:
 ($(VENV_RUN); python -m ruff format --exclude packages .; python -m ruff check --output-format=full --exclude packages --fix .)

diff --git a/docs/Makefile b/docs/Makefile
 # Minimal makefile for Sphinx documentation
 # Mostly use by the project Makefile to access the clean and html targets
 #

 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build

 # Put it first so that "make" without argument is like "make help".
 help:
 @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

 .PHONY: help Makefile

 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_static/localstack-horizontal.png b/docs/_static/localstack-horizontal.png
diff --git a/docs/conf.py b/docs/conf.py
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html

 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

 import os
 import sys

 sys.path.insert(0, os.path.abspath("../localstack-sdk-python/localstack"))


 def _get_version() -> str:
    with open(os.path.abspath("../VERSION"), "r") as f:
        version = f.read()
        return version


 project = "LocalStack Python SDK"
 copyright = "2024, LocalStack Team"
 author = "LocalStack Team"
 release = _get_version()

 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

 # enable auto-doc extension
 extensions = ["sphinx.ext.autodoc"]

 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]


 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

 html_theme = "alabaster"
 html_static_path = ["_static"]

 html_sidebars = {
    "**": [
        "about.html",
        "searchfield.html",
        "navigation.html",
    ]
 }

 html_theme_options = {
    "extra_nav_links": {
        "Source": "https://github.com/localstack/localstack-sdk-python",
        "Issues": "https://github.com/localstack/localstack-sdk-python/issues",
        "PyPI": "https://pypi.org/project/localstack-sdk-python/",
    },
    "description": "Python SDK to interact with LocalStack developer endpoints",
    "github_user": "localstack",
    "github_repo": "localstack-sdk-python",
 }
diff --git a/docs/index.rst b/docs/index.rst
 .. image:: _static/localstack-horizontal.png
    :align: center
    :target: https://localstack.cloud

 This is the documentation for the Python
 `LocalStack's SDK <https://github.com/localstack/localstack-sdk-python>`_.

 LocalStack offers a number of developer endpoints to programmatically interact
 with LocalStack's features.

 The complete OpenAPI spec can be found in the
 `OpenAPI repository <https://github.com/localstack/openapi>`_.

 Installation
 ------------

 We recommend to user virtual environments to manage the dependencies of your project.

 To create and activate a virtual environment inside your project run:

 .. code-block:: shell

  python3 -m venv venv

 You can activate the correspondent provider with:

 .. code-block:: shell

    . venv/bin/activate

 With the activated environment, use the following command to install the LocalStack Python SDK.

 .. code-block:: shell

  pip install localstack-sdk-python

 Getting Started
 ---------------

 To learn about the basic SDK concepts and see how you can use it, please have a look at our
 official `LocalStack documentation <https://docs.localstack.cloud/user-guide/tools/localstack-sdk/python/>`_.

 API Reference
 -------------

 If you are looking for information on a specific function, class or
 method, this part of the documentation is for you.

 .. toctree::
   :maxdepth: 1

   modules
diff --git a/docs/modules.rst b/docs/modules.rst
 API Reference
 =============

 .. toctree::
   :maxdepth: 4

   localstack.sdk
diff --git a/localstack-sdk-python/localstack/sdk/aws/client.py b/localstack-sdk-python/localstack/sdk/aws/client.py
 import json

 from localstack.clients import BaseClient
 from localstack.sdk.api.aws_api import AwsApi
 from localstack.sdk.clients import BaseClient
 from localstack.sdk.models import (
    Message,
    SesSentEmail,


 class AWSClient(BaseClient):
    """
    The client to interact with all the LocalStack's AWS endpoints.
    These endpoints offer specific features in addition to the ones offered by the AWS services. For instance,
    access all the messages withing a SQS without the side effect of deleting them.
    """

    def __init__(self, **kwargs) -> None:
        super().__init__(**kwargs)
        self._client = AwsApi(self._api_client)
    ########

    def list_sqs_messages(self, account_id: str, region: str, queue_name: str) -> list[Message]:
        """
        Lists all the SQS messages in a given queue in a specific account id and region, without any side effect.

        :param account_id: the account id of the queue
        :param region: the region of the queue
        :param queue_name: the name of the queue
        :return: the list of messages in the queue
        """
        response = self._client.list_sqs_messages_with_http_info(
            account_id=account_id, region=region, queue_name=queue_name
        )
        return _from_sqs_query_to_json(json.loads(response.raw_data))

    def list_sqs_messages_from_queue_url(self, queue_url) -> list[Message]:
    def list_sqs_messages_from_queue_url(self, queue_url: str) -> list[Message]:
        """
        Lists all the SQS messages in a given queue, without any side effect.

        :param queue_url: the URL of the queue
        :return: the list of messages in the queue
        """
        response = self._client.list_all_sqs_messages_with_http_info(queue_url=queue_url)
        return _from_sqs_query_to_json(json.loads(response.raw_data))

    def get_ses_messages(
        self, id_filter: str | None = None, email_filter: str | None = None
    ) -> list[SesSentEmail]:
        """
        Returns all the in-memory saved SES messages. They can be filtered by message ID and/or message source.

        :param id_filter: the message id used as filter for the SES messages
        :param email_filter: the message source filter
        :return: a list of email sent with SES
        """
        response = self._client.get_ses_messages(id=id_filter, email=email_filter)
        return response.messages

    def discard_ses_messages(self, id_filter: str | None = None) -> None:
        """
        Clears all SES messages. An ID filter can be provided to delete only a specific message.

        :param id_filter: the id filter
        :return: None
        """
        return self._client.discard_ses_messages(id=id_filter)

    ########
        account_id: str = "000000000000",
        region: str = "us-east-1",
    ) -> SNSSMSMessagesResponse:
        """
        Returns all SMS messages published to a phone number.

        :param phone_number: the phone number to which the messages have been published. If not specified, all messages
            are returned.
        :param account_id: the AWS Account ID from which the messages have been published. '000000000000' by default
        :param region:  the AWS region from which the messages have been published. us-east-1 by default
        :return:
        """
        return self._client.get_sns_sms_messages(
            phone_number=phone_number, account_id=account_id, region=region
        )
        account_id: str = "000000000000",
        region: str = "us-east-1",
    ) -> None:
        """
        Discards all SMS messages published to a phone number.

        :param phone_number: the phone number to which the messages have been published. If not specified, all messages
            are deleted.
        :param account_id: the AWS Account ID from which the messages have been published. '000000000000' by default
        :param region:  the AWS region from which the messages have been published. us-east-1 by default
        :return: None
        """
        return self._client.discard_sns_sms_messages(
            phone_number=phone_number, account_id=account_id, region=region
        )
        account_id: str = "000000000000",
        region: str = "us-east-1",
    ) -> SNSPlatformEndpointResponse:
        """
        Returns all the messages published to a platform endpoint.

        :param endpoint_arn: the ARN to which the messages have been published. If not specified, will return all the
            messages.
        :param account_id: the AWS Account ID from which the messages have been published. 000000000000 if not specified
        :param region: the AWS region from which the messages have been published. us-east-1 by default
        :return: a response with the list of messages and the queried region
        """
        return self._client.get_sns_endpoint_messages(
            endpoint_arn=endpoint_arn, account_id=account_id, region=region
        )
        account_id: str = "000000000000",
        region: str = "us-east-1",
    ) -> None:
        """
        Discards all the messaged published to a platform endpoint.

        :param endpoint_arn: the ARN to which the messages have been published. If not specified, will discard all the
            messages.
        :param account_id: the AWS Account ID from which the messages have been published. 000000000000 if not specified
        :param region: the AWS region from which the messages have been published. us-east-1 by default
        :return: None
        """
        return self._client.discard_sns_endpoint_messages(
            endpoint_arn=endpoint_arn, account_id=account_id, region=region
        )
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,41 @@
		name: Build sphinx documentation

		on:
		push:
		paths:
		- 'docs/**'
		branches:
		- main
		workflow_dispatch:

		jobs:
		build:
		runs-on: ubuntu-latest
		permissions:
		contents: write
		steps:
		- uses: actions/checkout@v3

		- name: Install uv
		uses: astral-sh/setup-uv@v3

		- name: Install project
		run: \|
		make install-dev

		- name: Generate docs
		run:
		make sphinx-docs

		- name: Upload artifacts
		uses: actions/upload-artifact@v4
		with:
		name: html-docs
		path: docs/_build/html/

		- name: Deploy
		uses: peaceiris/actions-gh-pages@v3
		if: github.ref == 'refs/heads/main'
		with:
		github_token: ${{ secrets.GITHUB_TOKEN }}
		publish_dir: docs/_build/html
Original file line number	Diff line number	Diff line change
Expand Up		@@ -23,6 +23,11 @@ clean-generated:## Cleanup generated code
		generate:## Generate the code from the OpenAPI specs
		./bin/generate.sh

		sphinx-docs:## Generate the documentation; uses the sphinx-generated Makefile in docs to clean and build html
		($(VENV_RUN); sphinx-apidoc --implicit-namespaces -o docs localstack-sdk-python/localstack)
Copy link Member alexrashedNov 26, 2024 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. question: ‏Should this maybe also just use the sphinx "catch all make target" in line 20 of the Makefile in the docs folder?
		$(MAKE) -C docs clean
		$(MAKE) -C docs html

		format:
		($(VENV_RUN); python -m ruff format --exclude packages .; python -m ruff check --output-format=full --exclude packages --fix .)

Expand Down
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,21 @@
		# Minimal makefile for Sphinx documentation
		# Mostly use by the project Makefile to access the clean and html targets
		#

		# You can set these variables from the command line, and also
		# from the environment for the first two.
		SPHINXOPTS ?=
		SPHINXBUILD ?= sphinx-build
		SOURCEDIR = .
		BUILDDIR = _build

		# Put it first so that "make" without argument is like "make help".
		help:
		@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

		.PHONY: help Makefile

		# Catch-all target: route all unknown targets to Sphinx using the new
		# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
		%: Makefile
		@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,59 @@
		# Configuration file for the Sphinx documentation builder.
		#
		# For the full list of built-in configuration values, see the documentation:
		# https://www.sphinx-doc.org/en/master/usage/configuration.html

		# -- Project information -----------------------------------------------------
		# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

		import os
		import sys

		sys.path.insert(0, os.path.abspath("../localstack-sdk-python/localstack"))


		def _get_version() -> str:
		with open(os.path.abspath("../VERSION"), "r") as f:
		version = f.read()
		return version


		project = "LocalStack Python SDK"
		copyright = "2024, LocalStack Team"
		author = "LocalStack Team"
		release = _get_version()

		# -- General configuration ---------------------------------------------------
		# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

		# enable auto-doc extension
		extensions = ["sphinx.ext.autodoc"]

		templates_path = ["_templates"]
		exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]


		# -- Options for HTML output -------------------------------------------------
		# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

		html_theme = "alabaster"
		html_static_path = ["_static"]

		html_sidebars = {
		"**": [
		"about.html",
		"searchfield.html",
		"navigation.html",
		]
		}

		html_theme_options = {
		"extra_nav_links": {
		"Source": "https://github.com/localstack/localstack-sdk-python",
		"Issues": "https://github.com/localstack/localstack-sdk-python/issues",
		"PyPI": "https://pypi.org/project/localstack-sdk-python/",
		},
		"description": "Python SDK to interact with LocalStack developer endpoints",
		"github_user": "localstack",
		"github_repo": "localstack-sdk-python",
		}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,52 @@
		.. image:: _static/localstack-horizontal.png
		:align: center
		:target: https://localstack.cloud

		This is the documentation for the Python
		`LocalStack's SDK <https://github.com/localstack/localstack-sdk-python>`_.

		LocalStack offers a number of developer endpoints to programmatically interact
		with LocalStack's features.

		The complete OpenAPI spec can be found in the
		`OpenAPI repository <https://github.com/localstack/openapi>`_.

		Installation
		------------

		We recommend to user virtual environments to manage the dependencies of your project.

		To create and activate a virtual environment inside your project run:

		.. code-block:: shell

		python3 -m venv venv

		You can activate the correspondent provider with:

		.. code-block:: shell

		. venv/bin/activate

		With the activated environment, use the following command to install the LocalStack Python SDK.

		.. code-block:: shell

		pip install localstack-sdk-python

		Getting Started
		---------------

		To learn about the basic SDK concepts and see how you can use it, please have a look at our
		official `LocalStack documentation <https://docs.localstack.cloud/user-guide/tools/localstack-sdk/python/>`_.

		API Reference
		-------------

		If you are looking for information on a specific function, class or
		method, this part of the documentation is for you.

		.. toctree::
		:maxdepth: 1

		modules
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,7 @@
		API Reference
		=============

		.. toctree::
		:maxdepth: 4

		localstack.sdk
Original file line number	Diff line number	Diff line change
		@@ -1,7 +1,7 @@
		import json

		from localstack.clients import BaseClient
		from localstack.sdk.api.aws_api import AwsApi
		from localstack.sdk.clients import BaseClient
		from localstack.sdk.models import (
		Message,
		SesSentEmail,
Expand DownExpand Up		@@ -36,6 +36,12 @@ def _from_sqs_query_to_json(xml_dict: dict) -> list[Message]:


		class AWSClient(BaseClient):
		"""
		The client to interact with all the LocalStack's AWS endpoints.
		These endpoints offer specific features in addition to the ones offered by the AWS services. For instance,
		access all the messages withing a SQS without the side effect of deleting them.
		"""

		def __init__(self, **kwargs) -> None:
		super().__init__(**kwargs)
		self._client = AwsApi(self._api_client)
Expand All		@@ -45,12 +51,26 @@ def __init__(self, **kwargs) -> None:
		########

		def list_sqs_messages(self, account_id: str, region: str, queue_name: str) -> list[Message]:
		"""
		Lists all the SQS messages in a given queue in a specific account id and region, without any side effect.

		:param account_id: the account id of the queue
		:param region: the region of the queue
		:param queue_name: the name of the queue
		:return: the list of messages in the queue
		"""
		response = self._client.list_sqs_messages_with_http_info(
		account_id=account_id, region=region, queue_name=queue_name
		)
		return _from_sqs_query_to_json(json.loads(response.raw_data))

		def list_sqs_messages_from_queue_url(self, queue_url) -> list[Message]:
		def list_sqs_messages_from_queue_url(self, queue_url: str) -> list[Message]:
		"""
		Lists all the SQS messages in a given queue, without any side effect.

		:param queue_url: the URL of the queue
		:return: the list of messages in the queue
		"""
		response = self._client.list_all_sqs_messages_with_http_info(queue_url=queue_url)
		return _from_sqs_query_to_json(json.loads(response.raw_data))

Expand All		@@ -61,10 +81,23 @@ def list_sqs_messages_from_queue_url(self, queue_url) -> list[Message]:
		def get_ses_messages(
		self, id_filter: str \| None = None, email_filter: str \| None = None
		) -> list[SesSentEmail]:
		"""
		Returns all the in-memory saved SES messages. They can be filtered by message ID and/or message source.

		:param id_filter: the message id used as filter for the SES messages
		:param email_filter: the message source filter
		:return: a list of email sent with SES
		"""
		response = self._client.get_ses_messages(id=id_filter, email=email_filter)
		return response.messages

		def discard_ses_messages(self, id_filter: str \| None = None) -> None:
		"""
		Clears all SES messages. An ID filter can be provided to delete only a specific message.

		:param id_filter: the id filter
		:return: None
		"""
		return self._client.discard_ses_messages(id=id_filter)

		########
Expand All		@@ -77,6 +110,15 @@ def get_sns_sms_messages(
		account_id: str = "000000000000",
		region: str = "us-east-1",
		) -> SNSSMSMessagesResponse:
		"""
		Returns all SMS messages published to a phone number.

		:param phone_number: the phone number to which the messages have been published. If not specified, all messages
		are returned.
		:param account_id: the AWS Account ID from which the messages have been published. '000000000000' by default
		:param region: the AWS region from which the messages have been published. us-east-1 by default
		:return:
		"""
		return self._client.get_sns_sms_messages(
		phone_number=phone_number, account_id=account_id, region=region
		)
Expand All		@@ -87,6 +129,15 @@ def discard_sns_sms_messages(
		account_id: str = "000000000000",
		region: str = "us-east-1",
		) -> None:
		"""
		Discards all SMS messages published to a phone number.

		:param phone_number: the phone number to which the messages have been published. If not specified, all messages
		are deleted.
		:param account_id: the AWS Account ID from which the messages have been published. '000000000000' by default
		:param region: the AWS region from which the messages have been published. us-east-1 by default
		:return: None
		"""
		return self._client.discard_sns_sms_messages(
		phone_number=phone_number, account_id=account_id, region=region
		)
Expand All		@@ -97,6 +148,15 @@ def get_sns_endpoint_messages(
		account_id: str = "000000000000",
		region: str = "us-east-1",
		) -> SNSPlatformEndpointResponse:
		"""
		Returns all the messages published to a platform endpoint.

		:param endpoint_arn: the ARN to which the messages have been published. If not specified, will return all the
		messages.
		:param account_id: the AWS Account ID from which the messages have been published. 000000000000 if not specified
		:param region: the AWS region from which the messages have been published. us-east-1 by default
		:return: a response with the list of messages and the queried region
		"""
		return self._client.get_sns_endpoint_messages(
		endpoint_arn=endpoint_arn, account_id=account_id, region=region
		)
Expand All		@@ -107,6 +167,15 @@ def discard_sns_endpoint_messages(
		account_id: str = "000000000000",
		region: str = "us-east-1",
		) -> None:
		"""
		Discards all the messaged published to a platform endpoint.

		:param endpoint_arn: the ARN to which the messages have been published. If not specified, will discard all the
		messages.
		:param account_id: the AWS Account ID from which the messages have been published. 000000000000 if not specified
		:param region: the AWS region from which the messages have been published. us-east-1 by default
		:return: None
		"""
		return self._client.discard_sns_endpoint_messages(
		endpoint_arn=endpoint_arn, account_id=account_id, region=region
		)
Expand Down