Discovery

Discovery happens during CDK synthesis. The CDK integration resolves lambda_path from the directory where the CDK process is run, walks that directory recursively with os.walk, and considers files whose names end in .py. Each candidate is parsed with Python's ast module.

The source is inspected as a tree; it is not imported. The implementation does not execute module top-level code or call a handler during synth. This keeps discovery independent from application imports and avoids running application side effects merely to produce infrastructure.

What becomes a handler

The current AST inspection looks at top-level def functions. A function is a route only when it has a recognized direct-name HTTP decorator: GET, POST, PUT, DELETE, or ANY, called with one non-empty string path. Each handler must have exactly one HTTP decorator; a second one raises ValueError.

The relationship is therefore:

Python file → module/index path → function name → Lambda handler entry point

For example, with the default SourceLayout.ROOT, lambdas/users/handler.py and lambda_handler become the package entry directory lambdas, module path users.handler, and handler users.handler.lambda_handler. The file path also contributes to generated resource identifiers. See Source layouts for the packaging boundary rules and examples.

Files without decorators are skipped. Files containing only configuration, authorization, permission, or other non-HTTP decorators do not create a Lambda route. Nested functions, methods inside classes, classes themselves, and async def functions are not discovered by the current implementation. Attribute-form decorators and other decorator expressions that are not direct names are ignored by the AST layer for route discovery. Invalid recognized route arguments raise an error rather than becoming a route.

Static decorator arguments

Called decorators are represented from AST nodes and their arguments are converted with ast.literal_eval. Consequently, values used by the supported decorators must be statically interpretable literals, such as strings, numbers, booleans, lists, tuples, dictionaries, or None. Names, function calls, f-strings, and attribute expressions cannot be evaluated by this step and are rejected for the validated decorator forms. Use a literal alias in the decorator and put the actual CDK object in a LambdaApiConfig registry.

This is an inspection limitation, not a general Python limitation. For the complete route and layout behavior, use the source layout guide and the HTTP decorator reference.