tha-aws-runner 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,36 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: ["main"]
6
+ pull_request:
7
+
8
+ jobs:
9
+ test:
10
+ runs-on: ubuntu-latest
11
+ strategy:
12
+ matrix:
13
+ python-version: ["3.10", "3.11", "3.12", "3.13"]
14
+
15
+ steps:
16
+ - uses: actions/checkout@v4
17
+
18
+ - name: Install uv
19
+ uses: astral-sh/setup-uv@v4
20
+ with:
21
+ version: "latest"
22
+
23
+ - name: Set up Python ${{ matrix.python-version }}
24
+ run: uv python install ${{ matrix.python-version }}
25
+
26
+ - name: Install dependencies
27
+ run: uv sync --extra dev --python ${{ matrix.python-version }}
28
+
29
+ - name: Lint
30
+ run: uv run ruff check src/ tests/
31
+
32
+ - name: Test
33
+ run: uv run pytest
34
+
35
+ - name: Type check
36
+ run: uv run mypy src/
@@ -0,0 +1,58 @@
1
+ name: Publish
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - "v*"
7
+
8
+ jobs:
9
+ build:
10
+ runs-on: ubuntu-latest
11
+ steps:
12
+ - uses: actions/checkout@v4
13
+
14
+ - name: Install uv
15
+ uses: astral-sh/setup-uv@v4
16
+
17
+ - name: Build
18
+ run: uv build
19
+
20
+ - name: Upload dist
21
+ uses: actions/upload-artifact@v4
22
+ with:
23
+ name: dist
24
+ path: dist/
25
+
26
+ publish-testpypi:
27
+ needs: build
28
+ runs-on: ubuntu-latest
29
+ environment: testpypi
30
+ permissions:
31
+ id-token: write
32
+ steps:
33
+ - name: Download dist
34
+ uses: actions/download-artifact@v4
35
+ with:
36
+ name: dist
37
+ path: dist/
38
+
39
+ - name: Publish to TestPyPI
40
+ uses: pypa/gh-action-pypi-publish@release/v1
41
+ with:
42
+ repository-url: https://test.pypi.org/legacy/
43
+
44
+ publish-pypi:
45
+ needs: publish-testpypi
46
+ runs-on: ubuntu-latest
47
+ environment: pypi
48
+ permissions:
49
+ id-token: write
50
+ steps:
51
+ - name: Download dist
52
+ uses: actions/download-artifact@v4
53
+ with:
54
+ name: dist
55
+ path: dist/
56
+
57
+ - name: Publish to PyPI
58
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,218 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[codz]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ # Distribution / packaging
10
+ .Python
11
+ build/
12
+ develop-eggs/
13
+ dist/
14
+ downloads/
15
+ eggs/
16
+ .eggs/
17
+ lib/
18
+ lib64/
19
+ parts/
20
+ sdist/
21
+ var/
22
+ wheels/
23
+ share/python-wheels/
24
+ *.egg-info/
25
+ .installed.cfg
26
+ *.egg
27
+ MANIFEST
28
+
29
+ # PyInstaller
30
+ # Usually these files are written by a python script from a template
31
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
32
+ *.manifest
33
+ *.spec
34
+
35
+ # Installer logs
36
+ pip-log.txt
37
+ pip-delete-this-directory.txt
38
+
39
+ # Unit test / coverage reports
40
+ htmlcov/
41
+ .tox/
42
+ .nox/
43
+ .coverage
44
+ .coverage.*
45
+ .cache
46
+ nosetests.xml
47
+ coverage.xml
48
+ *.cover
49
+ *.py.cover
50
+ .hypothesis/
51
+ .pytest_cache/
52
+ cover/
53
+
54
+ # Translations
55
+ *.mo
56
+ *.pot
57
+
58
+ # Django stuff:
59
+ *.log
60
+ local_settings.py
61
+ db.sqlite3
62
+ db.sqlite3-journal
63
+
64
+ # Flask stuff:
65
+ instance/
66
+ .webassets-cache
67
+
68
+ # Scrapy stuff:
69
+ .scrapy
70
+
71
+ # Sphinx documentation
72
+ docs/_build/
73
+
74
+ # PyBuilder
75
+ .pybuilder/
76
+ target/
77
+
78
+ # Jupyter Notebook
79
+ .ipynb_checkpoints
80
+
81
+ # IPython
82
+ profile_default/
83
+ ipython_config.py
84
+
85
+ # pyenv
86
+ # For a library or package, you might want to ignore these files since the code is
87
+ # intended to run in multiple environments; otherwise, check them in:
88
+ # .python-version
89
+
90
+ # pipenv
91
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
92
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
93
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
94
+ # install all needed dependencies.
95
+ # Pipfile.lock
96
+
97
+ # UV
98
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
99
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
100
+ # commonly ignored for libraries.
101
+ # uv.lock
102
+
103
+ # poetry
104
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
105
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
106
+ # commonly ignored for libraries.
107
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
108
+ # poetry.lock
109
+ # poetry.toml
110
+
111
+ # pdm
112
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
113
+ # pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
114
+ # https://pdm-project.org/en/latest/usage/project/#working-with-version-control
115
+ # pdm.lock
116
+ # pdm.toml
117
+ .pdm-python
118
+ .pdm-build/
119
+
120
+ # pixi
121
+ # Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
122
+ # pixi.lock
123
+ # Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
124
+ # in the .venv directory. It is recommended not to include this directory in version control.
125
+ .pixi
126
+
127
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
128
+ __pypackages__/
129
+
130
+ # Celery stuff
131
+ celerybeat-schedule
132
+ celerybeat.pid
133
+
134
+ # Redis
135
+ *.rdb
136
+ *.aof
137
+ *.pid
138
+
139
+ # RabbitMQ
140
+ mnesia/
141
+ rabbitmq/
142
+ rabbitmq-data/
143
+
144
+ # ActiveMQ
145
+ activemq-data/
146
+
147
+ # SageMath parsed files
148
+ *.sage.py
149
+
150
+ # Environments
151
+ .env
152
+ .envrc
153
+ .venv
154
+ env/
155
+ venv/
156
+ ENV/
157
+ env.bak/
158
+ venv.bak/
159
+
160
+ # Spyder project settings
161
+ .spyderproject
162
+ .spyproject
163
+
164
+ # Rope project settings
165
+ .ropeproject
166
+
167
+ # mkdocs documentation
168
+ /site
169
+
170
+ # mypy
171
+ .mypy_cache/
172
+ .dmypy.json
173
+ dmypy.json
174
+
175
+ # Pyre type checker
176
+ .pyre/
177
+
178
+ # pytype static type analyzer
179
+ .pytype/
180
+
181
+ # Cython debug symbols
182
+ cython_debug/
183
+
184
+ # PyCharm
185
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
186
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
187
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
188
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
189
+ # .idea/
190
+
191
+ # Abstra
192
+ # Abstra is an AI-powered process automation framework.
193
+ # Ignore directories containing user credentials, local state, and settings.
194
+ # Learn more at https://abstra.io/docs
195
+ .abstra/
196
+
197
+ # Visual Studio Code
198
+ # Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
199
+ # that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
200
+ # and can be added to the global gitignore or merged into this file. However, if you prefer,
201
+ # you could uncomment the following to ignore the entire vscode folder
202
+ # .vscode/
203
+ # Temporary file for partial code execution
204
+ tempCodeRunnerFile.py
205
+
206
+ # Ruff stuff:
207
+ .ruff_cache/
208
+
209
+ # PyPI configuration file
210
+ .pypirc
211
+
212
+ # Marimo
213
+ marimo/_static/
214
+ marimo/_lsp/
215
+ __marimo__/
216
+
217
+ # Streamlit
218
+ .streamlit/secrets.toml
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Nathan Wright
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,141 @@
1
+ Metadata-Version: 2.4
2
+ Name: tha-aws-runner
3
+ Version: 0.1.0
4
+ Summary: A Tabular Helper API library that wraps common AWS services (DynamoDB, SSM) with a typed, consistent interface built on boto3.
5
+ Project-URL: Homepage, https://github.com/tha-guy-nate/tha-aws-runner
6
+ Project-URL: Issues, https://github.com/tha-guy-nate/tha-aws-runner/issues
7
+ Author: Nate Wright
8
+ License: MIT
9
+ License-File: LICENSE
10
+ Keywords: aws,boto3,dynamodb,helper,ssm,tabular
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Topic :: Utilities
19
+ Classifier: Typing :: Typed
20
+ Requires-Python: >=3.10
21
+ Requires-Dist: boto3>=1.34
22
+ Requires-Dist: tqdm>=4.66
23
+ Provides-Extra: dev
24
+ Requires-Dist: moto[dynamodb,ssm,sts]>=5.0; extra == 'dev'
25
+ Requires-Dist: mypy>=1.10; extra == 'dev'
26
+ Requires-Dist: pytest>=8; extra == 'dev'
27
+ Requires-Dist: ruff>=0.5; extra == 'dev'
28
+ Description-Content-Type: text/markdown
29
+
30
+ # tha-aws-runner
31
+
32
+ [![CI](https://github.com/tha-guy-nate/tha-aws-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/tha-guy-nate/tha-aws-runner/actions/workflows/ci.yml)
33
+
34
+ A Tabular Helper API library that wraps common AWS services (DynamoDB, S3, SSM) with a typed, consistent interface built on boto3.
35
+
36
+ ## Install
37
+
38
+ ```bash
39
+ pip install tha-aws-runner
40
+ ```
41
+
42
+ ## Quick start
43
+
44
+ ```python
45
+ from tha_aws_runner import ThaDdb, ThaS3, ThaSSM
46
+
47
+ # DynamoDB — batch fetch by partition key
48
+ ddb = ThaDdb(region="us-east-1")
49
+ records = ddb.fetch_by_pk("my_table", ["pk1", "pk2"], key_name="id", key_type="S")
50
+ # {"pk1": {"name": "Alice"}, "pk2": {"not_found": True}}
51
+
52
+ # DynamoDB — update a single attribute
53
+ result = ddb.update_by_pk("my_table", "pk1", "id", "S", "status", "S", "active")
54
+ # {"pk": "pk1", "status": "updated", "old": {...}}
55
+
56
+ # S3 — upload bytes or a local file (bucket+key or S3 URI)
57
+ s3 = ThaS3(region="us-east-1")
58
+ s3.upload_file("my-bucket", "data/file.csv", data=b"col1,col2\n1,2")
59
+ s3.upload_file("my-bucket", "data/file.csv", local_path="/tmp/file.csv")
60
+ s3.upload_file(uri="s3://my-bucket/data/file.csv", data=b"col1,col2\n1,2")
61
+
62
+ # S3 — download to memory or a local file (bucket+key or S3 URI)
63
+ result = s3.download_file("my-bucket", "data/file.csv")
64
+ # {"bucket": "my-bucket", "key": "data/file.csv", "status": "downloaded", "bytes": 13, "data": b"..."}
65
+ s3.download_file("my-bucket", "data/file.csv", local_path="/tmp/out.csv")
66
+ s3.download_file(uri="s3://my-bucket/data/file.csv", local_path="/tmp/out.csv")
67
+
68
+ # SSM — read a parameter
69
+ ssm = ThaSSM(region="us-east-1")
70
+ value = ssm.read_param("/my/app/secret", with_decryption=True)
71
+ ```
72
+
73
+ ## API
74
+
75
+ ### `ThaDdb`
76
+
77
+ ```python
78
+ ThaDdb(*, status_cb=None, mode="app", region=None, profile=None)
79
+ ```
80
+
81
+ | Method | Description |
82
+ |--------|-------------|
83
+ | `fetch_by_pk(table_name, partition_keys, *, fields=None, key_name=None, key_type=None, dynamodb=None)` | Batch-fetch items by partition key. Returns `dict[pk → record]`. Missing keys get `{"not_found": True}`. |
84
+ | `update_by_pk(table_name, partition_key, key_name, key_type, update_attr, update_type, update_value, *, increment_attr=None, dynamodb=None)` | Update a single attribute with conditional check. Returns `{"pk", "status", ...}` where status is `updated`, `skipped`, or `error`. |
85
+ | `batch_put(table_name, items, key_name, *, dynamodb=None)` | Write up to N items in 25-item chunks with retry. Returns `{"written": N}`. |
86
+ | `delete_by_pk(table_name, partition_key, key_name, key_type, *, dynamodb=None)` | Delete one item with existence check. Returns `{"pk", "status"}`. |
87
+
88
+ ### `ThaS3`
89
+
90
+ ```python
91
+ ThaS3(*, status_cb=None, mode="app", region=None, profile=None)
92
+ ```
93
+
94
+ | Method | Description |
95
+ |--------|-------------|
96
+ | `upload_file(bucket=None, key=None, *, uri=None, local_path=None, data=None, encoding="utf-8", s3=None)` | Upload a local file, raw bytes, or a string to S3. Provide `uri` or both `bucket`+`key`. Provide exactly one of `local_path` or `data`. Strings are encoded using `encoding`. Returns `{"bucket", "key", "status", "bytes"}`. |
97
+ | `download_file(bucket=None, key=None, *, uri=None, local_path=None, encoding=None, s3=None)` | Download an S3 object. Provide `uri` or both `bucket`+`key`. Without `local_path`, returns data in `result["data"]` as `str` (if `encoding` set) or `bytes`. With `local_path`, writes raw bytes to disk. Returns `{"bucket", "key", "status", "bytes"}`. |
98
+
99
+ ### `ThaSSM`
100
+
101
+ ```python
102
+ ThaSSM(*, status_cb=None, mode="app", region=None, profile=None)
103
+ ```
104
+
105
+ | Method | Description |
106
+ |--------|-------------|
107
+ | `read_param(path, *, with_decryption=False, ssm=None)` | Fetch a single SSM parameter value as a string. |
108
+
109
+ All methods set `self.rows` to their return value.
110
+
111
+ `mode="cli"` enables tqdm progress bars. `mode="app"` calls `status_cb(message)` instead.
112
+
113
+ ### Helpers
114
+
115
+ ```python
116
+ from tha_aws_runner import AWSClients, current_identity, parse_assumed_role_arn, cli_auth_check
117
+
118
+ # Get all boto3 clients from one session
119
+ clients = AWSClients(region="us-east-1", profile="my-profile")
120
+ s3 = clients.s3()
121
+
122
+ # Check the current AWS identity
123
+ identity, account_id, role_name, session_name = current_identity(region="us-east-1")
124
+
125
+ # Guard a script to the expected account/role
126
+ if not cli_auth_check(account_id, role_name, "123456789012", "my_role"):
127
+ raise SystemExit("Wrong AWS identity")
128
+ ```
129
+
130
+ ## Alternatives
131
+
132
+ - **[boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)** — the official AWS SDK; `tha-aws-runner` is a thin typed convenience layer on top of it
133
+ - **[aioboto3](https://github.com/terrycain/aioboto3)** — async boto3 wrapper for async applications
134
+ - **[pynamodb](https://pynamodb.readthedocs.io/)** — ORM-style DynamoDB wrapper with model definitions
135
+ - **[aws-lambda-powertools](https://docs.powertools.aws.dev/lambda/python/)** — utilities for Lambda functions including SSM parameter caching
136
+
137
+ `tha-aws-runner` is intentionally narrow: no ORM, no async, no Lambda-specific features — just a thin typed wrapper for the most common DynamoDB, S3, and SSM call patterns.
138
+
139
+ ## License
140
+
141
+ MIT
@@ -0,0 +1,112 @@
1
+ # tha-aws-runner
2
+
3
+ [![CI](https://github.com/tha-guy-nate/tha-aws-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/tha-guy-nate/tha-aws-runner/actions/workflows/ci.yml)
4
+
5
+ A Tabular Helper API library that wraps common AWS services (DynamoDB, S3, SSM) with a typed, consistent interface built on boto3.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ pip install tha-aws-runner
11
+ ```
12
+
13
+ ## Quick start
14
+
15
+ ```python
16
+ from tha_aws_runner import ThaDdb, ThaS3, ThaSSM
17
+
18
+ # DynamoDB — batch fetch by partition key
19
+ ddb = ThaDdb(region="us-east-1")
20
+ records = ddb.fetch_by_pk("my_table", ["pk1", "pk2"], key_name="id", key_type="S")
21
+ # {"pk1": {"name": "Alice"}, "pk2": {"not_found": True}}
22
+
23
+ # DynamoDB — update a single attribute
24
+ result = ddb.update_by_pk("my_table", "pk1", "id", "S", "status", "S", "active")
25
+ # {"pk": "pk1", "status": "updated", "old": {...}}
26
+
27
+ # S3 — upload bytes or a local file (bucket+key or S3 URI)
28
+ s3 = ThaS3(region="us-east-1")
29
+ s3.upload_file("my-bucket", "data/file.csv", data=b"col1,col2\n1,2")
30
+ s3.upload_file("my-bucket", "data/file.csv", local_path="/tmp/file.csv")
31
+ s3.upload_file(uri="s3://my-bucket/data/file.csv", data=b"col1,col2\n1,2")
32
+
33
+ # S3 — download to memory or a local file (bucket+key or S3 URI)
34
+ result = s3.download_file("my-bucket", "data/file.csv")
35
+ # {"bucket": "my-bucket", "key": "data/file.csv", "status": "downloaded", "bytes": 13, "data": b"..."}
36
+ s3.download_file("my-bucket", "data/file.csv", local_path="/tmp/out.csv")
37
+ s3.download_file(uri="s3://my-bucket/data/file.csv", local_path="/tmp/out.csv")
38
+
39
+ # SSM — read a parameter
40
+ ssm = ThaSSM(region="us-east-1")
41
+ value = ssm.read_param("/my/app/secret", with_decryption=True)
42
+ ```
43
+
44
+ ## API
45
+
46
+ ### `ThaDdb`
47
+
48
+ ```python
49
+ ThaDdb(*, status_cb=None, mode="app", region=None, profile=None)
50
+ ```
51
+
52
+ | Method | Description |
53
+ |--------|-------------|
54
+ | `fetch_by_pk(table_name, partition_keys, *, fields=None, key_name=None, key_type=None, dynamodb=None)` | Batch-fetch items by partition key. Returns `dict[pk → record]`. Missing keys get `{"not_found": True}`. |
55
+ | `update_by_pk(table_name, partition_key, key_name, key_type, update_attr, update_type, update_value, *, increment_attr=None, dynamodb=None)` | Update a single attribute with conditional check. Returns `{"pk", "status", ...}` where status is `updated`, `skipped`, or `error`. |
56
+ | `batch_put(table_name, items, key_name, *, dynamodb=None)` | Write up to N items in 25-item chunks with retry. Returns `{"written": N}`. |
57
+ | `delete_by_pk(table_name, partition_key, key_name, key_type, *, dynamodb=None)` | Delete one item with existence check. Returns `{"pk", "status"}`. |
58
+
59
+ ### `ThaS3`
60
+
61
+ ```python
62
+ ThaS3(*, status_cb=None, mode="app", region=None, profile=None)
63
+ ```
64
+
65
+ | Method | Description |
66
+ |--------|-------------|
67
+ | `upload_file(bucket=None, key=None, *, uri=None, local_path=None, data=None, encoding="utf-8", s3=None)` | Upload a local file, raw bytes, or a string to S3. Provide `uri` or both `bucket`+`key`. Provide exactly one of `local_path` or `data`. Strings are encoded using `encoding`. Returns `{"bucket", "key", "status", "bytes"}`. |
68
+ | `download_file(bucket=None, key=None, *, uri=None, local_path=None, encoding=None, s3=None)` | Download an S3 object. Provide `uri` or both `bucket`+`key`. Without `local_path`, returns data in `result["data"]` as `str` (if `encoding` set) or `bytes`. With `local_path`, writes raw bytes to disk. Returns `{"bucket", "key", "status", "bytes"}`. |
69
+
70
+ ### `ThaSSM`
71
+
72
+ ```python
73
+ ThaSSM(*, status_cb=None, mode="app", region=None, profile=None)
74
+ ```
75
+
76
+ | Method | Description |
77
+ |--------|-------------|
78
+ | `read_param(path, *, with_decryption=False, ssm=None)` | Fetch a single SSM parameter value as a string. |
79
+
80
+ All methods set `self.rows` to their return value.
81
+
82
+ `mode="cli"` enables tqdm progress bars. `mode="app"` calls `status_cb(message)` instead.
83
+
84
+ ### Helpers
85
+
86
+ ```python
87
+ from tha_aws_runner import AWSClients, current_identity, parse_assumed_role_arn, cli_auth_check
88
+
89
+ # Get all boto3 clients from one session
90
+ clients = AWSClients(region="us-east-1", profile="my-profile")
91
+ s3 = clients.s3()
92
+
93
+ # Check the current AWS identity
94
+ identity, account_id, role_name, session_name = current_identity(region="us-east-1")
95
+
96
+ # Guard a script to the expected account/role
97
+ if not cli_auth_check(account_id, role_name, "123456789012", "my_role"):
98
+ raise SystemExit("Wrong AWS identity")
99
+ ```
100
+
101
+ ## Alternatives
102
+
103
+ - **[boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)** — the official AWS SDK; `tha-aws-runner` is a thin typed convenience layer on top of it
104
+ - **[aioboto3](https://github.com/terrycain/aioboto3)** — async boto3 wrapper for async applications
105
+ - **[pynamodb](https://pynamodb.readthedocs.io/)** — ORM-style DynamoDB wrapper with model definitions
106
+ - **[aws-lambda-powertools](https://docs.powertools.aws.dev/lambda/python/)** — utilities for Lambda functions including SSM parameter caching
107
+
108
+ `tha-aws-runner` is intentionally narrow: no ORM, no async, no Lambda-specific features — just a thin typed wrapper for the most common DynamoDB, S3, and SSM call patterns.
109
+
110
+ ## License
111
+
112
+ MIT
@@ -0,0 +1,56 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "tha-aws-runner"
7
+ version = "0.1.0"
8
+ description = "A Tabular Helper API library that wraps common AWS services (DynamoDB, SSM) with a typed, consistent interface built on boto3."
9
+ readme = "README.md"
10
+ license = { text = "MIT" }
11
+ authors = [{ name = "Nate Wright" }]
12
+ requires-python = ">=3.10"
13
+ classifiers = [
14
+ "Programming Language :: Python :: 3",
15
+ "Programming Language :: Python :: 3.10",
16
+ "Programming Language :: Python :: 3.11",
17
+ "Programming Language :: Python :: 3.12",
18
+ "License :: OSI Approved :: MIT License",
19
+ "Operating System :: OS Independent",
20
+ "Intended Audience :: Developers",
21
+ "Topic :: Utilities",
22
+ "Typing :: Typed",
23
+ ]
24
+ keywords = ["aws", "boto3", "dynamodb", "ssm", "tabular", "helper"]
25
+ dependencies = [
26
+ "boto3>=1.34",
27
+ "tqdm>=4.66",
28
+ ]
29
+
30
+ [project.optional-dependencies]
31
+ dev = [
32
+ "pytest>=8",
33
+ "ruff>=0.5",
34
+ "mypy>=1.10",
35
+ "moto[dynamodb,ssm,sts]>=5.0",
36
+ ]
37
+
38
+ [project.urls]
39
+ Homepage = "https://github.com/tha-guy-nate/tha-aws-runner"
40
+ Issues = "https://github.com/tha-guy-nate/tha-aws-runner/issues"
41
+
42
+ [tool.hatch.build.targets.wheel]
43
+ packages = ["src/tha_aws_runner"]
44
+
45
+ [tool.ruff]
46
+ line-length = 100
47
+ target-version = "py310"
48
+
49
+ [tool.ruff.lint]
50
+ select = ["E", "F", "I", "B", "UP", "RUF"]
51
+
52
+ [tool.mypy]
53
+ ignore_missing_imports = true
54
+
55
+ [tool.pytest.ini_options]
56
+ testpaths = ["tests"]
@@ -0,0 +1,26 @@
1
+ """tha-aws-runner: typed boto3 wrapper for DynamoDB, S3, and SSM."""
2
+
3
+ from tha_aws_runner.aws_base import (
4
+ AWSBase,
5
+ AWSClients,
6
+ cli_auth_check,
7
+ current_identity,
8
+ parse_assumed_role_arn,
9
+ )
10
+ from tha_aws_runner.dynamodb import ThaDdb
11
+ from tha_aws_runner.errors import AwsError
12
+ from tha_aws_runner.s3 import ThaS3
13
+ from tha_aws_runner.ssm import ThaSSM
14
+
15
+ __version__ = "0.1.0"
16
+ __all__ = [
17
+ "AWSBase",
18
+ "AWSClients",
19
+ "AwsError",
20
+ "ThaDdb",
21
+ "ThaS3",
22
+ "ThaSSM",
23
+ "cli_auth_check",
24
+ "current_identity",
25
+ "parse_assumed_role_arn",
26
+ ]