API Reference

LoginHooks

class piccolo_api.shared.auth.hooks.LoginHooks(pre_login: Optional[List[PreLoginHook]] = None, login_success: Optional[List[LoginSuccessHook]] = None, login_failure: Optional[List[LoginFailureHook]] = None)[source]

Allows you to run custom logic during login. A hook can be a function or coroutine.

Here’s an example using session_login:

def check_ban_list(username: str, **kwargs):
    '''
    An example `pre_login` hook.
    '''
    if username in ('nuisance', 'pest'):
        return 'This account has been temporarily suspended'.


async def log_success(username: str, user_id: int, **kwargs):
    '''
    An example `login_success` hook.
    '''
    await my_logging_service.record(
        f'{username} just logged in'
    )


async def log_failure(username: str, **kwargs):
    '''
    An example `login_failure` hook.
    '''
    await my_logging_service.record(f'{username} could not login')
    return (
        'To reset your password go <a href="/password-reset/">here</a>.'
    )


login_endpoint = session_login(
    hooks=LoginHooks(
        pre_login=[check_ban_list],
        login_success=[log_success],
        login_failure=[log_failure],
    )
)

If any of the hooks return a string, the login process is aborted, and the login template is shown again, containing the string as a warning message. The string can contain HTML such as links, and it will be rendered correctly.

All of the example hooks above accept **kwargs - this is recommended just in case more data is passed to the hooks in future Piccolo API versions.

Parameters
  • pre_login – A list of function and / or coroutines, which accept the username as a string.

  • login_success – A list of function and / or coroutines, which accept the username as a string, and the user ID as an integer. If a string is returned, the login process stops before a session is created.

  • login_failure – A list of function and / or coroutines, which accept the username as a string.

CAPTCHA

class piccolo_api.shared.auth.captcha.Captcha(form_html: str, token_field: str, validator: Union[Callable[[str], Optional[str]], Callable[[str], Awaitable[Optional[str]]]])[source]

Used to create CAPTCHAs for adding bot protection to endpoints. This is a generic class for implementing your own CAPTCHA. Out of the box support is provided for hcaptcha and recaptcha_v2, so you should only need to use this class directly if doing something custom.

Parameters
  • form_html – Any HTML which needs inserting into the form to make the CAPTCHA work.

  • validator – A callback (either an async or normal function), which is passed the CAPTCHA token, and is used to verify with the CAPTCHA provider’s API that the token is valid. To indicate that validation has failed, return a string containing an error message which will be shown to the user.

piccolo_api.shared.auth.captcha.hcaptcha(site_key: str, secret_key: str) Captcha[source]

Can be used along with Piccolo endpoints to incorporate hCaptcha.

Parameters
  • site_key – Provided by hCaptcha.

  • secret_key – Provided by hCaptcha.

piccolo_api.shared.auth.captcha.recaptcha_v2(site_key: str, secret_key: str) Captcha[source]

Can be used along with Piccolo endpoints to incorporate reCAPTCHA.

Parameters
  • site_key – Provided by reCAPTCHA.

  • secret_key – Provided by reCAPTCHA.

Styles

class piccolo_api.shared.auth.styles.Styles(background_color: str = '#EEF2F5', foreground_color: str = 'white', text_color: str = 'black', error_text_color: str = 'red', button_color: str = '#419EF8', button_text_color: str = 'white', border_color: str = 'rgba(0, 0, 0, 0.2)')[source]

Used to set CSS styles in endpoints such as session_login, session_logout, and register.

Each of the values must be valid CSS.