arnmatch 2026.2.4

Parse AWS ARNs into structured data (2000+ resource types)

arnmatch

Parse AWS ARNs into structured data.

Overview

Working with AWS at scale raises questions that are surprisingly hard to answer:

1. What resource does this ARN represent? - ARN formats vary across services with no consistent parsing rules
2. What ARN formats exist? - No single source documents all valid ARN patterns
3. What resource types exist on AWS? - Scattered across 300+ service documentation pages
4. What CloudFormation type maps to this ARN? - No direct ARN-to-CFN mapping exists

arnmatch answers these questions by:

• Parsing ARNs into structured components (service, region, account, resource type, resource ID)
• Providing a complete index of 2000+ resource types from 300+ AWS services
• Mapping ARNs to CloudFormation resource types (e.g., arn:aws:lambda:...:function:X → AWS::Lambda::Function)

Patterns are auto-generated from AWS Service Authorization Reference.

Features

• Zero runtime dependencies
• 300+ AWS services, 2000+ resource types
• Patterns auto-generated from AWS official documentation
• CLI and library interface
• CloudFormation resource type mapping
• Boto3 SDK service name mapping

Installation

pip install arnmatch

Quick Start

CLI

$ arnmatch "arn:aws:lambda:us-east-1:123456789012:function:my-function"
aws_service: lambda
aws_sdk_service: lambda
aws_sdk_services: lambda
aws_region: us-east-1
aws_account: 123456789012
resource_type: function
resource_id: my-function
resource_name: my-function
cloudformation_resource: AWS::Lambda::Function

Library

from arnmatch import arnmatch

result = arnmatch("arn:aws:lambda:us-east-1:123456789012:function:my-function")

result.aws_service            # "lambda"
result.aws_region             # "us-east-1"
result.aws_account            # "123456789012"
result.resource_type          # "function"
result.resource_id            # "my-function"
result.resource_name          # "my-function"
result.cloudformation_resource  # "AWS::Lambda::Function"
result.aws_sdk_service        # "lambda"

# Get a boto3 client for the service
client = result.client()
client.get_function(FunctionName=result.resource_name)

API Reference

arnmatch(arn: str) -> ARN

Parse an ARN string and return structured data.

Raises ARNError if the ARN format is invalid or no pattern matches.

ARN

Dataclass with parsed ARN components:

Field	Type	Description
aws_partition	str	AWS partition (aws, aws-cn, aws-us-gov)
aws_service	str	AWS service name
aws_region	str	AWS region (may be empty for global resources)
aws_account	str	AWS account ID
resource_type	str	Canonical resource type from AWS docs
resource_types	list[str]	All known names for this resource type
attributes	dict[str, str]	All captured attributes from the ARN
aws_sdk_service	str | None	Primary boto3 client name
cloudformation_resource	str | None	CloudFormation resource type

Properties:

Property	Description
resource_id	Resource identifier (prefers attributes ending in Id, then Name, then last attribute)
resource_name	Resource name (prefers attributes ending in Name, falls back to resource_id)
aws_sdk_services	List of boto3 client names (e.g., ['elb', 'elbv2'] for elasticloadbalancing)

Methods:

Method	Description
client(session=None)	Returns a boto3 client for the resource's service. Pass an optional boto3.Session or uses default. Raises ValueError if no SDK mapping exists.

ARNError

Exception raised when ARN parsing fails. Inherits from ValueError.

Development

Prerequisites: uv

make lint       # Run ruff linter
make test       # Run pytest tests
make check      # Run lint and test
make generate   # Regenerate patterns from AWS docs
make build      # Build wheel and tarball
make publish    # Build and upload to PyPI

Versioning

CalVer format YYYY.MM.MICRO (e.g., 2026.2.0).