===============================================================================
QuickStart
===============================================================================

This guide will help you get started with core-aws-cdk quickly.

Basic Usage
===============================================================================

Creating a Lambda Function
---------------------------------------

.. code-block:: python

    from aws_cdk import App, Environment
    from aws_cdk.aws_lambda import Code, Runtime
    from core_aws_cdk.stacks.lambdas import BaseLambdaStack

    app = App()
    stack = BaseLambdaStack(
        app,
        "MyLambdaStack",
        env=Environment(account="123456789", region="us-east-1")
    )

    stack.create_lambda(
        function_id="MyFunction",
        handler="index.handler",
        code=Code.from_asset("./lambda"),
        runtime=Runtime.PYTHON_3_12,
        function_name="my-function"
    )

    app.synth()

..

Creating an S3 Bucket
---------------------------------------

.. code-block:: python

    from core_aws_cdk.stacks.s3 import BaseS3Stack

    stack = BaseS3Stack(app, "MyS3Stack")

    bucket = stack.create_bucket(
        bucket_id="MyBucket",
        bucket_name="my-unique-bucket-name",
        versioned=True
    )

..

Creating SNS Topic with SQS Subscription
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from core_aws_cdk.stacks.sns import BaseSnsStack
    from core_aws_cdk.stacks.sqs import BaseSqsStack
    from aws_cdk.aws_sns_subscriptions import SqsSubscription

    # Create topic
    sns_stack = BaseSnsStack(app, "MySnsStack")
    topic = sns_stack.create_sns_topic(
        topic_id="MyTopic",
        topic_name="my-topic"
    )

    # Create queue
    sqs_stack = BaseSqsStack(app, "MySqsStack")
    queue = sqs_stack.create_sqs_queue(
        queue_id="MyQueue",
        queue_name="my-queue",
        with_dlq=True,
        dlq_id="MyQueueDLQ"
    )

    # Subscribe queue to topic
    topic.add_subscription(SqsSubscription(queue))

..

Lambda ZIP Packaging
---------------------------------------

For Lambda functions with custom dependencies:

.. code-block:: python

    from core_aws_cdk.stacks.lambdas import ZipAssetCode
    import pathlib

    code = ZipAssetCode(
        project_directory=pathlib.Path("/path/to/project"),
        work_dir=pathlib.Path("/path/to/lambda"),
        includes=["handler.py", "__init__.py"],
        include_project_folders=["commons"],
        debug=True
    )

    stack.create_lambda(
        function_id="MyFunction",
        handler="handler.lambda_handler",
        code=code,
        runtime=Runtime.PYTHON_3_12
    )

..

Testing Lambda Packaging
---------------------------------------

Test Lambda package creation locally:

.. code-block:: python

    # test.py
    from core_aws_cdk.stacks.lambdas import ZipAssetCode
    import pathlib

    result = ZipAssetCode(
        project_directory=pathlib.Path("/path/to/project"),
        work_dir=pathlib.Path("/path/to/lambda"),
        include_project_folders=["commons"],
        includes=["__init__.py", "handler.py", "docs"],
        debug=True
    )

    print(result.package_path.resolve())

..

Run the test:

.. code-block:: shell

    python test.py

..

Verify package contents:

.. code-block:: shell

    unzip -l /path/to/project/.build/lambda_XXXXX.zip

..

Next Steps
===============================================================================

* See :doc:`examples` for more complex architectures
* Read :doc:`testing` for information on testing your infrastructure
* Check :doc:`stacks` for complete API documentation
* Review :doc:`troubleshooting` for common issues