Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitd0ee406

Browse files
committed
Adding docstrings and introducing sphinx draft (#12)
1 parent2c81a97 commitd0ee406

File tree

16 files changed

+681
-35
lines changed

16 files changed

+681
-35
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name:Build sphinx documentation
2+
3+
on:
4+
push:
5+
paths:
6+
-'docs/**'
7+
branches:
8+
-main
9+
workflow_dispatch:
10+
11+
jobs:
12+
build:
13+
runs-on:ubuntu-latest
14+
permissions:
15+
contents:write
16+
steps:
17+
-uses:actions/checkout@v3
18+
19+
-name:Install uv
20+
uses:astral-sh/setup-uv@v3
21+
22+
-name:Install project
23+
run:|
24+
make install-dev
25+
26+
-name:Generate docs
27+
run:
28+
source .venv/bin/activate
29+
make sphinx-docs
30+
31+
-name:Upload artifacts
32+
uses:actions/upload-artifact@v4
33+
with:
34+
name:html-docs
35+
path:docs/_build/html/
36+
37+
-name:Deploy
38+
uses:peaceiris/actions-gh-pages@v3
39+
if:github.ref == 'refs/heads/main'
40+
with:
41+
github_token:${{ secrets.GITHUB_TOKEN }}
42+
publish_dir:docs/_build/html

‎Makefile‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,11 @@ clean-generated:## Cleanup generated code
2323
generate:## Generate the code from the OpenAPI specs
2424
./bin/generate.sh
2525

26+
sphinx-docs:## Generate the documentation; uses the sphinx-generated Makefile in docs to clean and build html
27+
($(VENV_RUN); sphinx-apidoc --implicit-namespaces -o docs localstack-sdk-python/localstack)
28+
$(MAKE) -C docs clean
29+
$(MAKE) -C docs html
30+
2631
format:
2732
($(VENV_RUN); python -m ruff format --exclude packages.; python -m ruff check --output-format=full --exclude packages --fix .)
2833

‎docs/Makefile‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Minimal makefile for Sphinx documentation
2+
# Mostly use by the project Makefile to access the clean and html targets
3+
#
4+
5+
# You can set these variables from the command line, and also
6+
# from the environment for the first two.
7+
SPHINXOPTS ?=
8+
SPHINXBUILD ?= sphinx-build
9+
SOURCEDIR = .
10+
BUILDDIR = _build
11+
12+
# Put it first so that "make" without argument is like "make help".
13+
help:
14+
@$(SPHINXBUILD) -Mhelp"$(SOURCEDIR)""$(BUILDDIR)"$(SPHINXOPTS)$(O)
15+
16+
.PHONY: help Makefile
17+
18+
# Catch-all target: route all unknown targets to Sphinx using the new
19+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
20+
%: Makefile
21+
@$(SPHINXBUILD) -M$@"$(SOURCEDIR)""$(BUILDDIR)"$(SPHINXOPTS)$(O)
116 KB
Loading

‎docs/conf.py‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
importos
10+
importsys
11+
12+
sys.path.insert(0,os.path.abspath("../localstack-sdk-python/localstack"))
13+
14+
15+
def_get_version()->str:
16+
withopen(os.path.abspath("../VERSION"),"r")asf:
17+
version=f.read()
18+
returnversion
19+
20+
21+
project="LocalStack Python SDK"
22+
copyright="2024, LocalStack Team"
23+
author="LocalStack Team"
24+
release=_get_version()
25+
26+
# -- General configuration ---------------------------------------------------
27+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
28+
29+
# enable auto-doc extension
30+
extensions= ["sphinx.ext.autodoc"]
31+
32+
templates_path= ["_templates"]
33+
exclude_patterns= ["_build","Thumbs.db",".DS_Store"]
34+
35+
36+
# -- Options for HTML output -------------------------------------------------
37+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
38+
39+
html_theme="alabaster"
40+
html_static_path= ["_static"]
41+
42+
html_sidebars= {
43+
"**": [
44+
"about.html",
45+
"searchfield.html",
46+
"navigation.html",
47+
]
48+
}
49+
50+
html_theme_options= {
51+
"extra_nav_links": {
52+
"Source":"https://github.com/localstack/localstack-sdk-python",
53+
"Issues":"https://github.com/localstack/localstack-sdk-python/issues",
54+
"PyPI":"https://pypi.org/project/localstack-sdk-python/",
55+
},
56+
"description":"Python SDK to interact with LocalStack developer endpoints",
57+
"github_user":"localstack",
58+
"github_repo":"localstack-sdk-python",
59+
}

‎docs/index.rst‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
..image::_static/localstack-horizontal.png
2+
:align:center
3+
:target:https://localstack.cloud
4+
5+
This is the documentation for the Python
6+
`LocalStack's SDK<https://github.com/localstack/localstack-sdk-python>`_.
7+
8+
LocalStack offers a number of developer endpoints to programmatically interact
9+
with LocalStack's features.
10+
11+
The complete OpenAPI spec can be found in the
12+
`OpenAPI repository<https://github.com/localstack/openapi>`_.
13+
14+
Installation
15+
------------
16+
17+
We recommend to user virtual environments to manage the dependencies of your project.
18+
19+
To create and activate a virtual environment inside your project run:
20+
21+
..code-block::shell
22+
23+
python3 -m venv venv
24+
25+
You can activate the correspondent provider with:
26+
27+
..code-block::shell
28+
29+
. venv/bin/activate
30+
31+
With the activated environment, use the following command to install the LocalStack Python SDK.
32+
33+
..code-block::shell
34+
35+
pip install localstack-sdk-python
36+
37+
Getting Started
38+
---------------
39+
40+
To learn about the basic SDK concepts and see how you can use it, please have a look at our
41+
official `LocalStack documentation<https://docs.localstack.cloud/user-guide/tools/localstack-sdk/python/>`_.
42+
43+
API Reference
44+
-------------
45+
46+
If you are looking for information on a specific function, class or
47+
method, this part of the documentation is for you.
48+
49+
..toctree::
50+
:maxdepth:1
51+
52+
modules

‎docs/modules.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
API Reference
2+
=============
3+
4+
..toctree::
5+
:maxdepth:4
6+
7+
localstack.sdk

‎localstack-sdk-python/localstack/sdk/aws/client.py‎

Lines changed: 71 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
importjson
22

3-
fromlocalstack.clientsimportBaseClient
43
fromlocalstack.sdk.api.aws_apiimportAwsApi
4+
fromlocalstack.sdk.clientsimportBaseClient
55
fromlocalstack.sdk.modelsimport (
66
Message,
77
SesSentEmail,
@@ -36,6 +36,12 @@ def _from_sqs_query_to_json(xml_dict: dict) -> list[Message]:
3636

3737

3838
classAWSClient(BaseClient):
39+
"""
40+
The client to interact with all the LocalStack's AWS endpoints.
41+
These endpoints offer specific features in addition to the ones offered by the AWS services. For instance,
42+
access all the messages withing a SQS without the side effect of deleting them.
43+
"""
44+
3945
def__init__(self,**kwargs)->None:
4046
super().__init__(**kwargs)
4147
self._client=AwsApi(self._api_client)
@@ -45,12 +51,26 @@ def __init__(self, **kwargs) -> None:
4551
########
4652

4753
deflist_sqs_messages(self,account_id:str,region:str,queue_name:str)->list[Message]:
54+
"""
55+
Lists all the SQS messages in a given queue in a specific account id and region, without any side effect.
56+
57+
:param account_id: the account id of the queue
58+
:param region: the region of the queue
59+
:param queue_name: the name of the queue
60+
:return: the list of messages in the queue
61+
"""
4862
response=self._client.list_sqs_messages_with_http_info(
4963
account_id=account_id,region=region,queue_name=queue_name
5064
)
5165
return_from_sqs_query_to_json(json.loads(response.raw_data))
5266

53-
deflist_sqs_messages_from_queue_url(self,queue_url)->list[Message]:
67+
deflist_sqs_messages_from_queue_url(self,queue_url:str)->list[Message]:
68+
"""
69+
Lists all the SQS messages in a given queue, without any side effect.
70+
71+
:param queue_url: the URL of the queue
72+
:return: the list of messages in the queue
73+
"""
5474
response=self._client.list_all_sqs_messages_with_http_info(queue_url=queue_url)
5575
return_from_sqs_query_to_json(json.loads(response.raw_data))
5676

@@ -61,10 +81,23 @@ def list_sqs_messages_from_queue_url(self, queue_url) -> list[Message]:
6181
defget_ses_messages(
6282
self,id_filter:str|None=None,email_filter:str|None=None
6383
)->list[SesSentEmail]:
84+
"""
85+
Returns all the in-memory saved SES messages. They can be filtered by message ID and/or message source.
86+
87+
:param id_filter: the message id used as filter for the SES messages
88+
:param email_filter: the message source filter
89+
:return: a list of email sent with SES
90+
"""
6491
response=self._client.get_ses_messages(id=id_filter,email=email_filter)
6592
returnresponse.messages
6693

6794
defdiscard_ses_messages(self,id_filter:str|None=None)->None:
95+
"""
96+
Clears all SES messages. An ID filter can be provided to delete only a specific message.
97+
98+
:param id_filter: the id filter
99+
:return: None
100+
"""
68101
returnself._client.discard_ses_messages(id=id_filter)
69102

70103
########
@@ -77,6 +110,15 @@ def get_sns_sms_messages(
77110
account_id:str="000000000000",
78111
region:str="us-east-1",
79112
)->SNSSMSMessagesResponse:
113+
"""
114+
Returns all SMS messages published to a phone number.
115+
116+
:param phone_number: the phone number to which the messages have been published. If not specified, all messages
117+
are returned.
118+
:param account_id: the AWS Account ID from which the messages have been published. '000000000000' by default
119+
:param region: the AWS region from which the messages have been published. us-east-1 by default
120+
:return:
121+
"""
80122
returnself._client.get_sns_sms_messages(
81123
phone_number=phone_number,account_id=account_id,region=region
82124
)
@@ -87,6 +129,15 @@ def discard_sns_sms_messages(
87129
account_id:str="000000000000",
88130
region:str="us-east-1",
89131
)->None:
132+
"""
133+
Discards all SMS messages published to a phone number.
134+
135+
:param phone_number: the phone number to which the messages have been published. If not specified, all messages
136+
are deleted.
137+
:param account_id: the AWS Account ID from which the messages have been published. '000000000000' by default
138+
:param region: the AWS region from which the messages have been published. us-east-1 by default
139+
:return: None
140+
"""
90141
returnself._client.discard_sns_sms_messages(
91142
phone_number=phone_number,account_id=account_id,region=region
92143
)
@@ -97,6 +148,15 @@ def get_sns_endpoint_messages(
97148
account_id:str="000000000000",
98149
region:str="us-east-1",
99150
)->SNSPlatformEndpointResponse:
151+
"""
152+
Returns all the messages published to a platform endpoint.
153+
154+
:param endpoint_arn: the ARN to which the messages have been published. If not specified, will return all the
155+
messages.
156+
:param account_id: the AWS Account ID from which the messages have been published. 000000000000 if not specified
157+
:param region: the AWS region from which the messages have been published. us-east-1 by default
158+
:return: a response with the list of messages and the queried region
159+
"""
100160
returnself._client.get_sns_endpoint_messages(
101161
endpoint_arn=endpoint_arn,account_id=account_id,region=region
102162
)
@@ -107,6 +167,15 @@ def discard_sns_endpoint_messages(
107167
account_id:str="000000000000",
108168
region:str="us-east-1",
109169
)->None:
170+
"""
171+
Discards all the messaged published to a platform endpoint.
172+
173+
:param endpoint_arn: the ARN to which the messages have been published. If not specified, will discard all the
174+
messages.
175+
:param account_id: the AWS Account ID from which the messages have been published. 000000000000 if not specified
176+
:param region: the AWS region from which the messages have been published. us-east-1 by default
177+
:return: None
178+
"""
110179
returnself._client.discard_sns_endpoint_messages(
111180
endpoint_arn=endpoint_arn,account_id=account_id,region=region
112181
)

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp