better-aws-tags 0.1.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

better_aws_tags/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.1.0"
+__version__ = "0.3.1"
 
 from .tags import get_tags as get_tags
 from .tags import set_tags as set_tags

better_aws_tags/arnparse.py

@@ -0,0 +1,139 @@
+"""ARN parsing utilities."""
+
+import re
+from typing import NamedTuple
+
+REGEX_RESOURCE_TYPE = re.compile(r"^[a-zA-Z0-9-]+$")
+
+class ResourceNotFound(Exception):
+    def __init__(self, service, resource):
+        super().__init__(f"Cannot determine resource format for service {service}: {resource}")
+
+class ARN(NamedTuple):
+    partition: str
+    service: str
+    region: str
+    account: str
+    resource_type: str | None
+    resource_id: str
+    resource_name: str
+
+
+class Resource(NamedTuple):
+    resource_type: str | None
+    resource_id: str
+    resource_name: str
+
+
+def find_resource(service, resource):
+    separators = resource.count("/") + resource.count(":")
+    segments = [s for segment in resource.split("/") for s in segment.split(":")]
+    prefix = segments[0]
+    suffix = resource[len(prefix) + 1:]
+
+    if service == "apigateway":
+        if separators == 2:
+            return Resource(segments[1], segments[2], segments[2])
+        else:
+            raise ResourceNotFound(service, resource)
+    elif service == "autoscaling":
+        if segments[0] == "autoScalingGroup" and segments[2] == "autoScalingGroupName":
+            return Resource(segments[0], segments[1], segments[3])
+        else:
+            raise ResourceNotFound(service, resource)
+    elif service == "cloudformation":
+        if separators == 2:
+            return Resource(segments[0], segments[2], segments[1])
+        else:
+            raise ResourceNotFound(service, resource)
+    elif service == "cloudwatch":
+        if prefix == "alarm":
+            return Resource(prefix, suffix, suffix)
+        else:
+            raise ResourceNotFound(service, resource)
+    elif service == "elasticloadbalancing":
+        if prefix == "loadbalancer":
+            if separators == 3:
+                return Resource(f"{segments[0]}/{segments[1]}", segments[3], segments[2])
+            elif separators == 1:
+                return Resource(segments[0], segments[1], segments[1])
+            else:
+                raise ResourceNotFound(service, resource)
+        elif prefix == "targetgroup":
+            if separators == 2:
+                return Resource(prefix, segments[2], segments[1])
+            else:
+                raise ResourceNotFound(service, resource)
+        else:
+            raise ResourceNotFound(service, resource)
+    elif service == "logs":
+        if prefix == "log-group":
+            return Resource(prefix, suffix, suffix)
+        else:
+            raise ResourceNotFound(service, resource)
+    elif service == "secretsmanager":
+        if prefix == "secret":
+            return Resource(prefix, suffix, suffix)
+        else:
+            raise ResourceNotFound(service, resource)
+    elif service == "ssm":
+        if prefix == "parameter":
+            return Resource(prefix, "/" + suffix, "/" + suffix)
+        else:
+            raise ResourceNotFound(service, resource)
+    elif service == "wafv2":
+        if prefix == "global":
+            return Resource(f"{segments[0]}/{segments[1]}", segments[2], segments[2])
+        elif prefix == "regional":
+            return Resource(f"{segments[0]}/{segments[1]}", segments[3], segments[2])
+        else:
+            raise ResourceNotFound(service, resource)
+    elif separators == 1:
+        return Resource(segments[0], segments[1], segments[1])
+    elif separators == 0:
+        return Resource(None, segments[0], segments[0])
+    else:
+        raise ResourceNotFound(service, resource)
+
+
+def arnparse(arn):
+    """Parse an ARN string into components."""
+    parts = arn.split(":", 5)
+    if len(parts) != 6:
+        raise ValueError(f"Invalid ARN format: {arn}")
+
+    if parts[0] != "arn":
+        raise ValueError(f"ARN must start with 'arn': {arn}")
+
+    _, partition, service, region, account, resource = parts
+
+    # Global services - no region, no account
+    if service in {"s3", "route53"}:
+        if region or account:
+            raise ValueError(f"Service {service} must have empty region and account: {arn}")
+
+    # Global services - no region, has account
+    if service in {"cloudfront", "iam"}:
+        if region:
+            raise ValueError(f"Service {service} must have empty region: {arn}")
+        if not account:
+            raise ValueError(f"Service {service} must have account: {arn}")
+
+    # Regional services - has region, no account
+    if service in {"apigateway"}:
+        if not region:
+            raise ValueError(f"Service {service} must have region: {arn}")
+        if account:
+            raise ValueError(f"Service {service} must have empty account: {arn}")
+
+    resource = find_resource(service, resource)
+
+    return ARN(
+        partition=partition,
+        service=service,
+        region=region,
+        account=account,
+        resource_type=resource.resource_type,
+        resource_id=resource.resource_id,
+        resource_name=resource.resource_name,
+    )

better_aws_tags/handlers.py

@@ -0,0 +1,134 @@
+from abc import ABC, abstractmethod
+
+import boto3
+
+from .arnparse import arnparse
+
+class Handler(ABC):
+    @classmethod
+    @abstractmethod
+    def get_tags(cls, session, arns):
+        pass
+
+    @classmethod
+    @abstractmethod
+    def set_tags(cls, session, arns, tags):
+        pass
+
+
+class IAMHandler(Handler):
+    """Handler for IAM resources using dedicated IAM tagging API."""
+
+    @classmethod
+    def get_tags(cls, session, arns):
+        if not arns:
+            raise ValueError("At least one ARN must be provided to get_tags.")
+
+        client = session.client("iam")
+        result = {}
+
+        for arn in arns:
+            arn_data = arnparse(arn)
+            resource_type = arn_data.resource_type
+            resource_name = arn_data.resource_name
+
+            if resource_type == "role":
+                response = client.list_role_tags(RoleName=resource_name)
+            elif resource_type == "user":
+                response = client.list_user_tags(UserName=resource_name)
+            elif resource_type == "policy":
+                response = client.list_policy_tags(PolicyArn=arn)
+            elif resource_type == "instance-profile":
+                response = client.list_instance_profile_tags(InstanceProfileName=resource_name)
+            else:
+                response = None
+
+            if response:
+                result[arn] = {t["Key"]: t["Value"] for t in response["Tags"]}
+            else:
+                result[arn] = None
+
+        return result
+
+    @classmethod
+    def set_tags(cls, session, arns, tags):
+        if not arns:
+            raise ValueError("At least one ARN must be provided to set_tags.")
+
+        client = session.client("iam")
+        result = {}
+        payload = [{"Key": k, "Value": v} for k, v in tags.items()]
+
+        for arn in arns:
+            arn_data = arnparse(arn)
+            resource_type = arn_data.resource_type
+            resource_name = arn_data.resource_name
+
+            try:
+                if resource_type == "role":
+                    response = client.tag_role(RoleName=resource_name, Tags=payload)
+                elif resource_type == "user":
+                    response = client.tag_user(UserName=resource_name, Tags=payload)
+                elif resource_type == "policy":
+                    response = client.tag_policy(PolicyArn=arn, Tags=payload)
+                elif resource_type == "instance-profile":
+                    response = client.tag_instance_profile(InstanceProfileName=resource_name, Tags=payload)
+                else:
+                    result[arn] = None
+                    continue
+            except client.exceptions.NoSuchEntityException:
+                result[arn] = None
+                continue
+
+            result[arn] = response["ResponseMetadata"]["HTTPStatusCode"] == 200
+
+        return result
+
+
+class TaggingAPIHandler(Handler):
+    @classmethod
+    def get_tags(cls, session, arns):
+        if not arns:
+            raise ValueError("At least one ARN must be provided to get_tags.")
+
+        client = session.client("resourcegroupstaggingapi")
+        result = {}
+
+        # https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/API_GetResources.html
+        batch_size = 100
+        for i in range(0, len(arns), batch_size):
+            batch = arns[i : i + batch_size]
+            response = client.get_resources(ResourceARNList=batch)
+            response = response["ResourceTagMappingList"]
+            for arn in batch:
+                if arn in response:
+                    result[arn] = {
+                        t["Key"]: t["Value"] for t in response[arn].get("Tags", [])
+                    }
+                else:
+                    result[arn] = None
+        return result
+
+    @classmethod
+    def set_tags(cls, session, arns, tags):
+        if not arns:
+            raise ValueError("At least one ARN must be provided to set_tags.")
+
+        if len(tags) == 0:
+            raise ValueError("At least one tag must be provided to set_tags.")
+
+        if len(tags) > 50:
+            raise ValueError("A maximum of 50 tags can be set at once.")
+
+        client = session.client("resourcegroupstaggingapi")
+        result = {}
+
+        # https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/API_TagResources.html
+        batch_size = 20
+        for i in range(0, len(arns), batch_size):
+            batch = arns[i : i + batch_size]
+            response = client.tag_resources(ResourceARNList=batch, Tags=tags)
+            for arn in batch:
+                result[arn] = arn not in response["FailedResourcesMap"]
+
+        return result

better_aws_tags/tags.py

@@ -2,38 +2,44 @@
 
 import boto3
 
-
-def get_tags(
-    arn: str | list[str],
-    session: boto3.Session | None = None,
-) -> dict[str, str] | dict[str, dict[str, str]]:
-    """Get tags for one or more AWS resources.
-
-    Args:
-        arn: Single ARN or list of ARNs.
-        session: Optional boto3 session. Uses default if not provided.
-
-    Returns:
-        Single ARN: {"Key": "Value", ...}
-        Multiple ARNs: {"arn1": {"Key": "Value"}, "arn2": {...}}
-    """
-    raise NotImplementedError
-
-
-def set_tags(
-    arn: str | list[str],
-    tags: dict[str, str],
-    session: boto3.Session | None = None,
-) -> bool | dict[str, bool]:
-    """Set tags on one or more AWS resources.
-
-    Args:
-        arn: Single ARN or list of ARNs.
-        tags: Tags to set (merged with existing).
-        session: Optional boto3 session. Uses default if not provided.
-
-    Returns:
-        Single ARN: True if successful.
-        Multiple ARNs: {"arn1": True, "arn2": False, ...}
-    """
-    raise NotImplementedError
+from .arnparse import arnparse
+from .handlers import IAMHandler, TaggingAPIHandler
+
+
+def get_tags(arns, session=None):
+    """Get tags for AWS resources."""
+    session = session or boto3.Session()
+    handlers = dispatch(arns)
+    results = {}
+    for handler, handler_arns in handlers.items():
+        r = handler.get_tags(session, handler_arns)
+        results.update(r)
+    return results
+
+
+def set_tags(arns, tags, session=None):
+    """Set tags on AWS resources."""
+    session = session or boto3.Session()
+    handlers = dispatch(arns)
+    results = {}
+    for handler, handler_arns in handlers.items():
+        r = handler.set_tags(session, handler_arns, tags)
+        results.update(r)
+    return results
+
+
+def dispatch(arns):
+    """Group ARNs by handler."""
+    handler_to_arns = {}
+    for arn in arns:
+        arn_data = arnparse(arn)
+
+        if arn_data.service == "iam":
+            handler = IAMHandler
+        else:
+            handler = TaggingAPIHandler
+
+        if handler not in handler_to_arns:
+            handler_to_arns[handler] = []
+        handler_to_arns[handler].append(arn)
+    return handler_to_arns

better_aws_tags-0.3.1.dist-info/METADATA

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: better-aws-tags
+Version: 0.3.1
+Summary: A unified Python interface for managing AWS resource tags
+Author-email: Andrey Gubarev <andrey@andreygubarev.com>
+Requires-Python: >=3.10
+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, tag validation, and error reporting automatically.
+
+## Getting Started
+
+```python
+import better_aws_tags as bats
+```

better_aws_tags-0.3.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+better_aws_tags/__init__.py,sha256=87A8zTFvL5OLAXjtykxq_4lY3vpk1pDoVH8jDNwIX6E,101
+better_aws_tags/arnparse.py,sha256=QiA9sRBY7QgO52V0truzzHfmlQCgJzWHaZOcIo8M9Ac,4865
+better_aws_tags/handlers.py,sha256=VKQsr0I6Y03myNUlpK-xxqx0sFLRCw31mQwv-kvlyy0,4611
+better_aws_tags/tags.py,sha256=pdgA1J_gMxnhyCNlPPAK4VisVZvPNWZO403yPAVbmWk,1182
+better_aws_tags-0.3.1.dist-info/METADATA,sha256=co22UISTduJp7qCLYfgIhfqZ-W6bxsBhfbHMoQL_geA,743
+better_aws_tags-0.3.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+better_aws_tags-0.3.1.dist-info/RECORD,,

better_aws_tags-0.1.0.dist-info/METADATA

@@ -1,18 +0,0 @@
-Metadata-Version: 2.4
-Name: better-aws-tags
-Version: 0.1.0
-Summary: Add your description here
-Author-email: Andrey Gubarev <mylokin@me.com>
-Requires-Python: >=3.13
-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, tag validation, and error reporting automatically.
-
-## Getting Started
-
-```python
-import better_aws_tags as bats
-```

better_aws_tags-0.1.0.dist-info/RECORD

@@ -1,5 +0,0 @@
-better_aws_tags/__init__.py,sha256=MQmqM7lNoABNMF1HjG_aZP5H3zdIqTNCuXOKffs7S1k,101
-better_aws_tags/tags.py,sha256=K8LsVZiTPUhNoCfX4VKCRCuaEl1JD9vH-Ua7ttJDku0,1019
-better_aws_tags-0.1.0.dist-info/METADATA,sha256=fuzHeGAnslOzhf_wWrOsbOYuB3YEdXUsY7gFlHTVLA0,700
-better_aws_tags-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-better_aws_tags-0.1.0.dist-info/RECORD,,