Concepts
- Service id: an unique identifier for a main service or sub service. For example
ec2
is for Elastic Computer Service,instances
is for EC2 instances. - Query str: a query str that could have space, dash, underscore for searching.
- AWSResoourceSearcher class: a utility class defines the behavior of
list resources
andfilter resources
, it always has a service_id associated with it. For example,ec2-instances
is used to matchEc2InstanceSearcher
class.
What happens when you enter a query
- You entered
aws iam-roles alice
in Alfred input box - Your input will be parsed as
main_service_id = iam, sub_service_id = roles, query_str = alice
- The AwsResourceSearcherRegistry use the service id
iam-roles
as a key to locate a custom AWS resource searcher class, this is what you need to implement. - In this example, the SearcherRegistry locates the IamRolesSearcher class.
- If you entered
aws iam-roles
, theIamRolesSearcher.list_res
method will be called and returns some data representing IAM role object. If you enteredaws iam-roles alice
, theIamRolesSearcher.filter_res(query_str="alice")
will be called and returns some IAM role data. - Eventually the
IamRolesSearcher.to_item(role)
will be called to convert the AWS resource data (in this case it is IAM role) intoAlfred Item
object that defines thetitle
,subtitle
,console_url
you see in the Alfred dropdown menu. - You will see the rendered item in the Alfred dropdown menu, and be able to do sub-sequence actions.
I use iam-roles
as example to walk through the step-by-step implementation tutorial.
- Find the
main_service_id
andsub_service_id
in console-urls.yml file. - Find the AWS Python SDK boto3 api call document in boto3 official document site. In this example, it is
list_roles(**kwargs)
- Create a python module with naming convention
${main_service_id}_${sub_service_id}.py
at aws_tools/search/aws_res. In this example, it is iam_roles.py. - Copy codes from
aws_res/ec2_instances.py
as a starting point.
- Define a simple data container class to simplify your code. In this example, it is
class Role
. - visually check the attributes you need from the boto3 response syntax, and declare the attribute like the syntax at class Role(ResData):
- custom the
def to_console_url(self):
method, it should return the AWS console url locate the resource. For regional resource it needs a{region}
placeholder in the f-string template. Example:https://console.aws.amazon.com/ec2/v2/home?region={region}#InstanceDetails:instanceId={inst_id}
- custom the
def to_large_text(self):
method, it returns large text to show when you hitcmd + L
. - custom the
def id(self):
property method, id should be the unique identifier of this data object. It allows you to deduplicate the object based on the id.
- Define a simple data container class to simplify your code. In this example, it is
- Define a
AWSResourceSearcher
subclass to implement thelist_res
andfilter_res
logic. In this example, it is class IamRolesSearcher. - define the
id
attribute, it is${main_service_id}.${sub_service_id}
. So the Searcher register can find it. - define the
simplify_response
method, it converts the boto3 response syntax into list of the data object. In this example, it isclass Role
- define the
list_res
method, it calls the boto3 api and returns list of data object to display in the Alfred dropdown menu. You can use@cache.memoize(expire=SettingValues.expire)
decorator to cache the output. - define the
filter_res
method, it calls the boto3 api and returns list of filtered data object to display in Alfred dropdown menu. You can also use the same decorator to cache the output. - define the
to_item
method, it converts the data object to an AlfredItemArgs
object representing an Alfred dropdown menu item.
- define the
- Define a
- Enable the Searcher:
- import this Searcher class in the register module and register it.
Follow this pattern and test the searcher with custom query_str
.
- Emoji: https://emojipedia.org/
- Symbol: https://emojipedia.org/symbols/