Authentication types are used to secure endpoints. They can be attached to endpoints
via the authentication parameter.

Example:
    clearskies.endpoints.RestfulApi(
        model_class=User,
        authentication=clearskies.authentication.SecretBearer(
            environment_key="API_SECRET"
        )
    )

Validators are used to validate model data before saving. They can be attached
to columns via the validators parameter.

Example:
    name = columns.String(validators=[Required(), MinLength(3)])

DI inject helpers are used to inject dependencies into your classes. They provide
special injection behaviors beyond simple class instantiation.

Example:
    class MyService:
        def __init__(self, utcnow: clearskies.di.inject.Utcnow):
            self.utcnow = utcnow

Args:
    column_type: The name of the column type (e.g. "String", "Integer", "BelongsToId").

Args:
    endpoint_type: The name of the endpoint type (e.g. "RestfulApi", "Create", "List").

Args:
    backend_type: The name of the backend type (e.g. "MemoryBackend", "CursorBackend", "ApiBackend").

Args:
    context_type: The name of the context type (e.g. "Cli", "WsgiRef", "Wsgi").

Args:
    auth_type: The auth type name (e.g. "SecretBearer", "JWKS", "SecretBasic").

Args:
    validator_type: The validator type name (e.g. "Required", "Unique", "Email").

Args:
    exception_type: The exception type name (e.g. "InputError", "AuthenticationError").

Args:
    inject_type: The inject type name (e.g. "ByClass", "Utcnow").

Args:
    cursor_type: The cursor type name.

Args:
    io_type: The input/output type name.

Args:
    config_type: The config type name.

Args:
    client_type: The client type name.

Args:
    secret_type: The secret type name.

Args:
    header_type: The security header type name.

Args:
    query_type: The query type name.

Args:
    result_type: The query result type name.

Args:
    func_name: The functional utility name.

Args:
    concept: The concept to explain. One of: model, endpoint, backend, column, context, di,
             authentication, autodoc, query, validator, schema, save_lifecycle, state_machine,
             declarative_programming, infrastructure_neutral, testing, authorization, error_handling,
             input_handling, endpoint_groups, routing, responses, migrations, advanced_columns,
             advanced_queries, configuration, logging, caching, async, state_machine_advanced,
             secrets_backend.

Args:
    name: The model class name in PascalCase (e.g. "User", "OrderProduct").
    columns: List of column definitions. Each dict has:
        - name (str): Column name
        - type (str): Column type (e.g. "String", "Integer", "Uuid", "BelongsToId")
        - options (dict, optional): Keyword arguments for the column constructor
    backend_type: Backend class name (default: "MemoryBackend").
    backend_options: Keyword arguments for the backend constructor.
    id_column_name: The name of the id column (default: "id").
    hooks: Optional list of hook methods to include stubs for (e.g. ["pre_save", "post_save", "save_finished"]).

Args:
    endpoint_type: Type of endpoint (e.g. "RestfulApi", "List", "Create", "Get", "Update", "Delete", "Callable").
    model_name: The model class name to use with this endpoint.
    url: The URL path for the endpoint (optional).
    readable_column_names: List of column names that are returned in the response.
    writeable_column_names: List of column names the client can set.
    sortable_column_names: List of column names the client can sort by.
    searchable_column_names: List of column names the client can search by.
    default_sort_column_name: The default column to sort by.
    authentication: Authentication configuration (e.g. 'clearskies.authentication.SecretBearer(environment_key="MY_SECRET")').
    extra_options: Additional keyword arguments for the endpoint constructor.

Args:
    context_type: The context type (e.g. "Cli", "WsgiRef", "Wsgi").
    endpoint_code: The endpoint expression to wrap (e.g. output from generate_endpoint).
    classes: List of model class names to register with DI.
    modules: List of module names to register with DI.
    bindings: Dictionary of name → value DI bindings.

Args:
    url: The URL prefix for all endpoints in the group.
    endpoints: List of endpoint configurations. Each dict has:
        - type (str): Endpoint type (e.g. "RestfulApi", "Callable", "List")
        - model_name (str): Model class name (for model-based endpoints)
        - url (str): URL path for this endpoint
        - readable_column_names (list[str], optional): Readable columns
        - writeable_column_names (list[str], optional): Writeable columns
        - sortable_column_names (list[str], optional): Sortable columns
        - searchable_column_names (list[str], optional): Searchable columns
        - default_sort_column_name (str, optional): Default sort column
        - request_methods (list[str], optional): Allowed HTTP methods (for Callable)
        - extra_options (dict, optional): Additional endpoint options
    authentication: Authentication configuration for all endpoints in the group
        (e.g. 'clearskies.authentication.SecretBearer(environment_key="MY_SECRET")').

Returns the full file content for a working clearskies application.

Args:
    project_name: The name of the project/application.
    models: List of model definitions. Each dict has:
        - name (str): Model class name in PascalCase
        - columns (list[dict]): Column definitions (same format as generate_model)
        - backend_type (str, optional): Backend type (default: "MemoryBackend")
        - id_column_name (str, optional): Id column name (default: "id")
        - url (str, optional): URL path for the REST API
        - readable_column_names (list[str], optional): Readable columns
        - writeable_column_names (list[str], optional): Writeable columns
        - sortable_column_names (list[str], optional): Sortable columns
        - searchable_column_names (list[str], optional): Searchable columns
        - default_sort_column_name (str, optional): Default sort column
    context_type: The context type to use (default: "WsgiRef").
    endpoint_type: Endpoint type to use (default: "RestfulApi").

This is a convenience tool that generates a model, a RestfulApi endpoint, and a context
in a single file ready to run.

Args:
    model_name: Model class name in PascalCase (e.g. "User").
    columns: List of column definitions. Each dict has:
        - name (str): Column name
        - type (str): Column type
        - options (dict, optional): Column constructor options
    url: URL path (default: auto-generated from model name).
    backend_type: Backend type (default: "MemoryBackend").
    backend_options: Backend constructor options.
    authentication: Authentication expression.
    context_type: Context type (default: "WsgiRef").

Use this when you need to create models with BelongsTo, HasMany, or ManyToMany relationships.

Args:
    models: List of model definitions. Each dict has:
        - name (str): Model class name
        - columns (list[dict]): Column definitions
        - backend_type (str, optional): Backend type
        - id_column_name (str, optional): Id column name

Shows installation status, version, and all discovered components
with their descriptions and parameters.

Args:
    module_name: The module name (e.g. "clearskies-aws", "clearskies-graphql", "clearskies-snyk").

Args:
    module_name: The module name (e.g. "clearskies-aws", "clearskies-graphql", "clearskies-snyk",
                 "clearskies-gitlab", "clearskies-cortex", "clearskies-akeyless-custom-producer").

Lists all components in a module, optionally filtered by category,
with their descriptions and constructor parameters.

Args:
    module_name: The module name (e.g. "clearskies-aws")
    category: Optional category filter (e.g. "backends", "contexts", "models")

Args:
    component_type: The component category (e.g. "backends", "contexts", "models")

Args:
    module_name: The module name to check

Analyze a ClearSkies v1 project and generate migration report.

Args:
    project_path: Path to the v1 project directory

Returns:
    Dictionary containing:
    - models: List of discovered models
    - handlers: List of discovered handlers
    - errors: List of parsing errors
    - warnings: List of migration warnings
    - complexity: Migration complexity assessment

Generate v2 code from a v1 project.

This tool analyzes a v1 codebase and generates v2-compatible code.
Use dry_run=True to preview changes without writing files.

Args:
    project_path: Path to the v1 project directory
    output_path: Path where v2 code should be generated
    dry_run: If True, don't write files (default: True)

Returns:
    Dictionary containing:
    - files: List of files to create/modify
    - breaking_changes: List of breaking changes
    - warnings: List of warnings
    - manual_steps: List of manual steps required

Map a v1 code snippet to its v2 equivalent.

Useful for understanding how specific v1 patterns translate to v2.

Args:
    v1_code_snippet: The v1 code to convert
    context: Context hint ('model', 'handler', 'di', 'general')

Returns:
    Dictionary containing:
    - v2_code: Converted v2 code
    - breaking_changes: List of breaking changes
    - notes: Migration notes

Explain how a specific concept changed between v1 and v2.

Args:
    concept: The concept to explain. Options:
        - 'model': Model definition changes
        - 'handler': Handler → Endpoint changes
        - 'di': Dependency injection changes
        - 'columns': Column definition changes
        - 'application': Application → Context changes
        - 'backend': Backend configuration changes
        - 'type_hints': Type hint requirements

Returns:
    Detailed explanation of the changes

Get a comprehensive checklist for v1 to v2 migration.

Returns:
    Dictionary with migration phases and tasks