better-aws-tags 0.4.0__tar.gz → 0.6.0__tar.gz

better_aws_tags-0.6.0/.claude/rules/python.md

@@ -0,0 +1,12 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Python Rules
+
+## Naming
+
+- Never use type suffixes in variable names (`_list`, `_dict`, `_map`, `_str`, `_int`, etc.)
+- Bad: `users_list`, `config_dict`, `name_str`, `handler_map`, `count_int`
+- Good: `users`, `config`, `name`, `handlers`, `count`

better_aws_tags-0.6.0/CLAUDE.md

@@ -0,0 +1,101 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## EXTREMELY IMPORTANT
+
+- NEVER use bare `try...except` or `except Exception`. ALWAYS catch specific exceptions.
+- NEVER do defensive programming. Let code FAIL if there is an unhandled exception.
+- ALWAYS validate results of API calls (boto3, HTTP, etc.). Check the response to confirm the operation succeeded.
+
+## Build and Development Commands
+
+```bash
+make dev       # Run in development mode (uv run python -m better_aws_tags)
+make run       # Run debug script (uv run python -i debug_bats.py)
+make test      # Run tests on Python 3.10-3.13
+make lint      # Run ruff linter
+make fmt       # Format code with ruff
+make check     # Run lint and tests
+make build     # Build package
+make publish   # Build and publish to PyPI
+```
+
+Run a single test:
+```bash
+uv run pytest tests/test_dispatch.py::test_dispatch_supported_resource -v
+```
+
+## Architecture
+
+This library provides a unified API for AWS resource tagging that abstracts away the differences between AWS's various tagging APIs.
+
+### Core Flow
+
+1. **Entry points** (`src/better_aws_tags/tags.py`): `get_tags()` and `set_tags()` accept ARNs and optional boto3 session
+2. **Dispatch** (`tags.py:dispatch()`): Routes ARNs to appropriate handlers based on resource type
+3. **Handlers** (`src/better_aws_tags/handlers.py`): Execute AWS API calls
+
+### Handlers
+
+- `TaggingAPIHandler`: Uses Resource Groups Tagging API for resources in `SUPPORTED_RESOURCES`
+- `IAMRoleHandler`: IAM roles (`arn:aws:iam::*:role/*`)
+- `IAMUserHandler`: IAM users (`arn:aws:iam::*:user/*`)
+- `IAMPolicyHandler`: IAM policies (`arn:aws:iam::*:policy/*`)
+
+The `HANDLERS` dict maps `(service, resource_type)` tuples to handler classes for resources not covered by the Tagging API.
+
+### Handler Routing Logic
+
+The `dispatch()` function determines which handler to use:
+1. If CloudFormation resource type is in `SUPPORTED_RESOURCES` → `TaggingAPIHandler`
+2. If `(service, resource_type)` is in `HANDLERS` → specific handler
+3. Otherwise → raises `NotImplementedError`
+
+### Dependencies
+
+- `arnmatch`: Parses ARNs and extracts service, resource type, and CloudFormation resource type
+- `boto3`: AWS SDK for Python
+
+## Adding Support for New Resources
+
+1. **Run integration tests** to identify unsupported resources:
+   ```bash
+   uv run python tests/integration/check_coverage.py
+   ```
+
+2. **Get sample ARN** and parse with arnmatch:
+   ```python
+   from arnmatch import arnmatch
+   data = arnmatch(arn)
+   print('aws_service:', data.aws_service)
+   print('resource_type:', data.resource_type)
+   print('tagging_resource:', data.tagging_resource)
+   ```
+   If `tagging_resource` is not `None` and is in `SUPPORTED_RESOURCES` → TaggingAPIHandler works.
+   If `tagging_resource` is `None` → need custom handler or mark unsupported.
+
+3. **Check if boto client exists**:
+   ```python
+   client = data.client()
+   ```
+   If no client exists → resource is not taggable.
+
+4. **Check if tagging methods exist**:
+   ```python
+   tag_methods = [m for m in dir(client) if 'tag' in m.lower()]
+   ```
+   If no tag methods → add to `unsupported_resources.py`.
+
+5. **Test if tagging works for this resource type**:
+   ```python
+   client.list_tags_for_resource(resourceArn=arn)  # or similar
+   ```
+   If fails with "invalid resource" → add to `unsupported_resources.py`.
+
+6. **If taggable, write a handler**:
+   - Create `src/better_aws_tags/handlers/{service}.py`
+   - Implement `get_tags` and `set_tags` methods
+   - Register in `handlers/__init__.py` with `(service, resource_type)` key
+
+7. **Re-run integration tests** to verify coverage.

{better_aws_tags-0.4.0 → better_aws_tags-0.6.0}/Makefile

@@ -19,6 +19,10 @@ test: ## Run tests on all Python versions
 	uv run --python 3.12 pytest -v
 	uv run --python 3.13 pytest -v
 
+.PHONY: test-integration
+test-integration: ## Run integration tests (requires AWS credentials)
+	uv run python tests/integration/check_coverage.py
+
 .PHONY: lint
 lint: ## Run linter
 	uv run ruff check .

{better_aws_tags-0.4.0 → better_aws_tags-0.6.0}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: better-aws-tags
-Version: 0.4.0
+Version: 0.6.0
 Summary: A unified Python interface for managing AWS resource tags
 Author-email: Andrey Gubarev <andrey@andreygubarev.com>
 Requires-Python: >=3.10
+Requires-Dist: arnmatch>=2026.2.2
 Requires-Dist: boto3~=1.0
 Description-Content-Type: text/markdown
 
@@ -11,14 +12,29 @@ Description-Content-Type: text/markdown
 
 A unified Python interface for managing AWS resource tags.
 
-AWS provides multiple tagging APIs across services, including the Resource Groups Tagging API and service-specific implementations such as EC2, S3, and IAM. This library abstracts these differences behind a single API that accepts any valid ARN and handles service routing, tag validation, and error reporting automatically.
+AWS provides multiple tagging APIs across services, including the Resource Groups Tagging API and service-specific implementations such as EC2, S3, and IAM. This library abstracts these differences behind a single API that accepts any valid ARN and handles service routing automatically.
 
 ## Getting Started
 
 ```python
 import better_aws_tags as bats
+
+# Get tags for resources
+tags = bats.get_tags(["arn:aws:s3:::my-bucket", "arn:aws:iam::123456789012:role/my-role"])
+
+# Set tags on resources
+bats.set_tags(["arn:aws:s3:::my-bucket"], {"Environment": "prod", "Team": "platform"})
 ```
 
+## How It Works
+
+The library routes ARNs to the appropriate handler:
+
+1. Most resources use the **Resource Groups Tagging API** (1000+ supported resource types)
+2. Some IAM resources (roles, users, policies) require **IAM-specific APIs**
+
+This routing is transparent - just pass ARNs and the library handles the rest.
+
 ## Reference
 
 - https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/overview.html

{better_aws_tags-0.4.0 → better_aws_tags-0.6.0}/README.md

@@ -2,14 +2,29 @@
 
 A unified Python interface for managing AWS resource tags.
 
-AWS provides multiple tagging APIs across services, including the Resource Groups Tagging API and service-specific implementations such as EC2, S3, and IAM. This library abstracts these differences behind a single API that accepts any valid ARN and handles service routing, tag validation, and error reporting automatically.
+AWS provides multiple tagging APIs across services, including the Resource Groups Tagging API and service-specific implementations such as EC2, S3, and IAM. This library abstracts these differences behind a single API that accepts any valid ARN and handles service routing automatically.
 
 ## Getting Started
 
 ```python
 import better_aws_tags as bats
+
+# Get tags for resources
+tags = bats.get_tags(["arn:aws:s3:::my-bucket", "arn:aws:iam::123456789012:role/my-role"])
+
+# Set tags on resources
+bats.set_tags(["arn:aws:s3:::my-bucket"], {"Environment": "prod", "Team": "platform"})
 ```
 
+## How It Works
+
+The library routes ARNs to the appropriate handler:
+
+1. Most resources use the **Resource Groups Tagging API** (1000+ supported resource types)
+2. Some IAM resources (roles, users, policies) require **IAM-specific APIs**
+
+This routing is transparent - just pass ARNs and the library handles the rest.
+
 ## Reference
 
 - https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/overview.html

{better_aws_tags-0.4.0 → better_aws_tags-0.6.0}/pyproject.toml

@@ -8,6 +8,7 @@ authors = [
 ]
 requires-python = ">=3.10"
 dependencies = [
+    "arnmatch>=2026.2.2",
     "boto3~=1.0",
 ]
 
@@ -23,3 +24,4 @@ dev = [
     "pytest~=9.0",
     "ruff~=0.14",
 ]
+

better_aws_tags-0.4.0/scratchpad/tags/tagging_resources.py → better_aws_tags-0.6.0/scratchpad/get_supported_resources.py

@@ -76,12 +76,29 @@ def fetch_resource_types(
     return resource_types
 
 
+def generate_python(resource_types: list[str]) -> str:
+    """Generate Python module with SUPPORTED_RESOURCES constant."""
+    lines = [
+        '"""Resource types supported by AWS Resource Groups Tagging API."""',
+        "",
+        "SUPPORTED_RESOURCES: list[str] = [",
+    ]
+    for rt in resource_types:
+        lines.append(f'    "{rt}",')
+    lines.append("]")
+    lines.append("")
+    return "\n".join(lines)
+
+
 def main():
     resource_types = fetch_resource_types(query_type="TAG_FILTERS_1_0")
-    resource_types = list(sorted(set(resource_types)))
-    # resource_types = fetch_resource_types(query_type="CLOUDFORMATION_STACK_1_0")
-    with open("tagging_resource.json", "w") as f:
-        json.dump(resource_types, f, indent=2)
+    resource_types = sorted(set(resource_types))
+
+    output = generate_python(resource_types)
+    with open("supported_resources.py", "w") as f:
+        f.write(output)
+
+    print(f"Generated supported_resources.py with {len(resource_types)} resource types")
 
 
 if __name__ == "__main__":