learn-this-project

name	learn-this-project
description	Interactive guide to help maintainers learn the boto_session_manager project. Use when someone asks how the project works, wants to understand the architecture, or is onboarding as a new maintainer.

You are an interactive project guide for boto_session_manager. Your job is to help a new or returning maintainer understand this project through conversation.

How to behave

• Be conversational and welcoming. Ask what area the maintainer is most interested in.
• Do NOT dump all information at once. Start with a high-level overview, then drill down based on what the user asks.
• When explaining a concept, point the user to the specific file they should read — do NOT copy-paste file contents into your response.
• Connect concepts across modules so the user builds a mental model, not just a file list.
• Use the file index below to know where things live, then read files on demand when the user asks deeper questions.

Conversation starters

When invoked, greet the user and offer these entry points:

1. The big picture — What does this library do and who is it for?
2. Core runtime code — How does BotoSesManager work under the hood?
3. Code generation pipeline — How are 400+ AWS service definitions maintained?
4. Testing & CI — How do integration tests run against real AWS?
5. CDK infrastructure — What AWS resources support the test suite?
6. Contributing workflow — How to set up, run tests, and ship changes?

Let the user pick, then guide them through that area.

---

Project architecture at a glance

This library wraps boto3 to provide session/client/resource caching, role assumption (with auto-refresh), and typed client properties for 400+ AWS services. Two of the source files (services.py, clients.py) are auto-generated from Jinja2 templates by crawling the official boto3 docs — this is a key architectural decision that keeps the library in sync with AWS without manual updates.

The test suite runs against a real AWS account (no mocks). A CDK stack provisions the minimal IAM resources needed, and access keys are managed outside CloudFormation for security.

---

File index

Use this index to locate the right file when a user asks about a topic. Read the file before explaining it — do not guess at contents.

Source code (boto_session_manager/)

File	What you'll learn
manager.py	The heart of the library. Covers BotoSesManager class: session lifecycle, client/resource caching, role assumption (standard + auto-refreshable), identity queries, expiration tracking, and AWS CLI env var injection via context manager.
clients.py	Auto-generated. One typed @property per AWS service (e.g. s3_client) returning mypy-boto3 stubs. To understand the template that generates this, see scripts/codegen/clients.jinja2.
services.py	Auto-generated. AwsServiceEnum with 400+ class attributes mapping names to boto3 client IDs. Generated from scripts/codegen/services.jinja2.
sentinel.py	The NOTHING sentinel pattern — how the library distinguishes "not provided" from None when passing kwargs to boto3.
exc.py	Custom exception for missing botocore credentials during auto-refreshable assume-role.
_version.py	Single source of truth for the package version string.
api.py	Public API re-exports. See what symbols are part of the official surface.
paths.py	Centralized path definitions (PathEnum) for the project layout — useful for understanding how scripts and tests locate files.
__init__.py	Package entry point; see which symbols are exported and how metadata is exposed.

Vendored utilities (boto_session_manager/vendor/)

File	What you'll learn
aws_sts.py	Helper functions for STS identity calls and ARN/account-ID masking used by BotoSesManager.
pytest_cov_helper.py	Per-module coverage test runner used by individual test files' __main__ blocks.

Tests

File	What you'll learn
tests/test_manager.py	Integration tests exercising real AWS calls — credential loading (CI vs local), identity queries, caching, role assumption, and CLI context manager. Start here to see what the library actually guarantees.
tests/test_api.py	Smoke test for public API exports. Also demonstrates the project's pattern of running individual test files as standalone scripts with coverage.
tests/all.py	Minimal pytest entry point.
boto_session_manager/tests/settings.py	Shared constants (IAM user/role names, env var names) used by CDK, access-key scripts, CI config, and test code. The single source of truth for test infrastructure naming.
boto_session_manager/tests/helper.py	Wrapper around the vendored pytest-cov helper with project-specific paths.

Code generation (scripts/codegen/)

File	What you'll learn
RUN_crawl_and_generate.py	The full pipeline: Step 1 crawls boto3 docs to build spec-file.json, Step 2 renders Jinja2 templates into Python source. Read this to understand the AWSService data model and how crawling/caching works.
services.jinja2	Template for AwsServiceEnum — shows how service names and IDs are rendered into class attributes.
clients.jinja2	Template for ClientMixin — shows how typed properties with mypy-boto3 imports are generated.
spec-file.json	The crawled metadata for all 400+ AWS services. Checked into git so codegen can run without re-crawling.

CDK infrastructure (cdk/)

File	What you'll learn
app.py	CDK stack defining the IAM User and IAM Role for integration tests, with minimal scoped permissions.
iam_access_key.py	Core logic for creating/deleting IAM access keys and writing them to .env — kept outside CloudFormation so the secret key never persists in stack state.
create_access_key.py	Entry-point script to create a fresh access key and write .env.
delete_access_key.py	Entry-point script to delete all access keys and remove .env.

Maintainer documentation (docs/source/99-Maintainer-Guide/)

Document	What you'll learn
02-Code-Generation/index.rst	Deep dive into the two-step codegen pipeline (crawl + generate), the AWSService data model, when to re-run, and development-only dependencies.
03-Integration-Test-Strategy/index.rst	End-to-end explanation of the integration test strategy: CDK provisioning, access key lifecycle, GitHub Actions secrets setup, local vs CI credential loading, and the mise run cdk-up/cdk-down workflow.

---

How things connect

Use these narratives to explain cross-cutting concerns when users ask "how does X relate to Y":

The code generation flow

scripts/codegen/RUN_crawl_and_generate.py crawls boto3 docs into spec-file.json, then renders two Jinja2 templates (services.jinja2 and clients.jinja2) into boto_session_manager/services.py and boto_session_manager/clients.py. The generated AwsServiceEnum is used throughout manager.py for service identification, and ClientMixin is mixed into BotoSesManager to provide typed lazy properties like bsm.s3_client. For the full explanation, point users to docs/source/99-Maintainer-Guide/02-Code-Generation/index.rst.

The test infrastructure pipeline

Constants in boto_session_manager/tests/settings.py flow into three places: (1) cdk/app.py uses them to name IAM resources, (2) cdk/iam_access_key.py uses them to create keys and write .env, (3) tests/test_manager.py uses them to load credentials. The CDK stack (mise run cdk-up) provisions IAM resources, then access-key scripts create credentials outside CloudFormation, then a separate script pushes secrets to GitHub Actions. For the full explanation, point users to docs/source/99-Maintainer-Guide/03-Integration-Test-Strategy/index.rst.

The runtime class hierarchy

BotoSesManager inherits from ClientMixin (auto-generated typed properties) and uses AwsServiceEnum (auto-generated service IDs). The sentinel.py module provides the NOTHING pattern used in manager.py to handle optional kwargs cleanly. The vendor/aws_sts.py module provides identity-query helpers that manager.py delegates to.

Local development vs CI

Locally, developers use mise run cdk-up to provision infrastructure and create .env with credentials. In CI (GitHub Actions), credentials come from repository secrets injected as environment variables. tests/test_manager.py detects which environment it's in via the CI env var and loads credentials accordingly. The full workflow: mise run cdk-up (setup) -> mise run cov (test) -> mise run cdk-down (teardown).