What is the role of user_keyword?

[skinhc]

I haven't read the role of "user_keyword" for a long time.Can you help me with your answer?

[pyx]

The reason behind this optional user_keyword parameter is explained here
https://sanic-auth.readthedocs.io/en/latest/#sanic_auth.Auth.login_required

Basically, it provides a way to avoid retrieving the user object twice unnecessary in one hit.
If you think there is anything unclear in the documentation, please help me improve it.

[yurenchen000]

didn't understand the documentation very well, until checked the source code:

https://github.com/pyx/sanic-auth/blob/0.3.0/sanic_auth/__init__.py#L103

                if user_keyword is not None:
                    if user_keyword in kwargs:
                        raise RuntimeError(
                            'override user keyword %r in route' % user_keyword)
                    kwargs[user_keyword] = user
                resp = route(request, *args, **kwargs)

seems that:
user_keyword arg tell sanic-auth to pass user object to route as a kwarg.
// it's designed for avoid confict of (route handle function's) kwargs key (by customize it).

So

1. usage example will be:

@auth.login_required(user_keyword='user')
async def profile(request, user):
    return response.html(f'you are {user.name}')

or

@auth.login_required(user_keyword='test123')
async def profile(request, test123):
    return response.html(f'you are {test123.name}')

and

2. wrong usage examples:

// got err: an unexpected keyword argument

@auth.login_required(user_keyword='test123')
async def profile(request, user): 
    return response.html(f'you are {test123.name}')

or
// wrong usage examples
// got err: an unexpected keyword argument

@auth.login_required
async def profile(request, user): 
    return response.html(f'you are {test123.name}')

3. without user_keyword

have to read it again by youself.

@app.route('/test')
@auth.login_required
async def profile2(request):
    user2 = auth.current_user(request)
    return response.html(f'you are {user2.name}')

[pyx]

didn't understand the documentation very well, until checked the source code:

https://github.com/pyx/sanic-auth/blob/0.3.0/sanic_auth/__init__.py#L103

                if user_keyword is not None:
                    if user_keyword in kwargs:
                        raise RuntimeError(
                            'override user keyword %r in route' % user_keyword)
                    kwargs[user_keyword] = user
                resp = route(request, *args, **kwargs)

seems that: user_keyword arg tell sanic-auth to pass user object to route as a kwarg. // it's designed for avoid confict of (route handle function's) kwargs key (by customize it).

So

1. usage example will be:

@auth.login_required(user_keyword='user')
async def profile(request, user):
    return response.html(f'you are {user.name}')

or

@auth.login_required(user_keyword='test123')
async def profile(request, test123):
    return response.html(f'you are {test123.name}')

and

2. wrong usage examples:

// got err: an unexpected keyword argument

@auth.login_required(user_keyword='test123')
async def profile(request, user): 
    return response.html(f'you are {test123.name}')

or // wrong usage examples // got err: an unexpected keyword argument

@auth.login_required
async def profile(request, user): 
    return response.html(f'you are {test123.name}')

3. without user_keyword

have to read it again by youself.

@app.route('/test')
@auth.login_required
async def profile2(request):
    user2 = auth.current_user(request)
    return response.html(f'you are {user2.name}')

Thank you for the clarification, you are right:
I am assuming that a call to auth.current_user might have huge overhead (hitting database for example), might as well re-use it if needed.