better-aws-tags 0.3.1__tar.gz → 0.5.0__tar.gz

better_aws_tags-0.5.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.3.1 → better_aws_tags-0.5.0}/.gitignore

@@ -1,4 +1,5 @@
 debug_*.py
+*.xlsx
 
 ### Python
 
@@ -199,9 +200,9 @@ cython_debug/
 .abstra/
 
 # Visual Studio Code
-#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
 #   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
 #   you could uncomment the following to ignore the entire vscode folder
 # .vscode/
 

better_aws_tags-0.5.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.4.0
+
+### Added
+
+- New `arnmatch` module for ARN pattern matching using regex patterns from AWS documentation
+- `arnmatch(arn)` function returns `ARNMatch` with parsed ARN components
+- `ARNMatch.resource_id` and `ARNMatch.resource_name` heuristics for extracting resource identifiers
+- Support for Resource Explorer type aliases (handles naming differences between AWS docs and Resource Explorer)
+- 2080 ARN patterns covering 355 AWS services
+
+## 0.3.1
+
+- Initial release with `get_tags` and `set_tags` functions

better_aws_tags-0.5.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.3.1 → better_aws_tags-0.5.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.5.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: better-aws-tags
+Version: 0.5.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
+
+# better-aws-tags
+
+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 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
+- https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/API_TagResources.html
+- https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/supported-services.html
+- https://docs.aws.amazon.com/ARG/latest/userguide/supported-resources.html
+
+AWS Resources and Resource Types:
+- https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html
+- https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_actions-resources-contextkeys.html

better_aws_tags-0.5.0/README.md

@@ -0,0 +1,37 @@
+# better-aws-tags
+
+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 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
+- https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/API_TagResources.html
+- https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/supported-services.html
+- https://docs.aws.amazon.com/ARG/latest/userguide/supported-resources.html
+
+AWS Resources and Resource Types:
+- https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html
+- https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_actions-resources-contextkeys.html

{better_aws_tags-0.3.1 → better_aws_tags-0.5.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.5.0/scratchpad/.gitignore

@@ -0,0 +1 @@
+*.json

better_aws_tags-0.5.0/scratchpad/get_supported_resources.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#     "boto3",
+#     "requests",
+# ]
+# ///
+"""
+Fetch resource types from undocumented AWS Resource Groups Tagging API endpoint.
+
+This endpoint returns the full list of resource types supported by the tagging API.
+"""
+
+import json
+
+import boto3
+from botocore.auth import SigV4Auth
+from botocore.awsrequest import AWSRequest
+import requests
+
+
+def fetch_resource_types_page(
+    query_type: str,
+    region: str,
+    credentials,
+    next_token: str | None = None,
+) -> dict:
+    """Fetch a single page of resource types."""
+    url = f"https://resource-groups.{region}.amazonaws.com/resource-types-list"
+
+    headers = {"Content-Type": "application/json"}
+    payload = {"QueryType": query_type, "MaxResults": 50}
+    if next_token:
+        payload["NextToken"] = next_token
+
+    body = json.dumps(payload)
+
+    request = AWSRequest(method="POST", url=url, headers=headers, data=body)
+    SigV4Auth(credentials, "resource-groups", region).add_auth(request)
+
+    response = requests.post(url, headers=dict(request.headers), data=body)
+    response.raise_for_status()
+
+    return response.json()
+
+
+def fetch_resource_types(
+    query_type,
+    region="us-east-1",
+) -> list[str]:
+    """
+    Fetch all resource types with pagination.
+
+    Args:
+        query_type: CLOUDFORMATION_STACK_1_0 or TAG_FILTERS_1_0
+        region: AWS region to query
+
+    Returns:
+        List of resource type strings
+    """
+    session = boto3.Session()
+    credentials = session.get_credentials()
+
+    resource_types = []
+    next_token = None
+
+    while True:
+        data = fetch_resource_types_page(query_type, region, credentials, next_token)
+        resource_types.extend(data.get("ResourceTypes", []))
+
+        next_token = data.get("NextToken")
+        if not next_token:
+            break
+
+    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 = 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__":
+    main()