1111
1212def CheckPolicies (* policies : t .Union [str , PolicyType ]) -> t .Callable :
1313 """
14- ========= CONTROLLER AND ROUTE FUNCTION DECORATOR ==============
15- Decorates a controller or a route function with specific policy requirements
16- :param policies:
17- :return:
14+ Applies policy requirements to a controller or route function.
15+
16+ This decorator allows you to specify one or more policies that must be satisfied
17+ for the user to access the decorated endpoint. Policies can be either string
18+ identifiers or PolicyType objects.
19+
20+ Example:
21+ ```python
22+ @Controller()
23+ class UserController:
24+ @CheckPolicies('admin', RequireRole('manager'))
25+ def get_sensitive_data(self):
26+ return {'data': 'sensitive information'}
27+ ```
28+
29+ Args:
30+ *policies: Variable number of policy requirements. Can be strings or PolicyType objects.
31+ - String policies are resolved using the policy provider
32+ - PolicyType objects are evaluated directly
33+
34+ Returns:
35+ A decorator function that applies the policy requirements.
1836 """
1937
2038 def _decorator (target : t .Callable ) -> t .Union [t .Callable , t .Any ]:
@@ -26,9 +44,25 @@ def _decorator(target: t.Callable) -> t.Union[t.Callable, t.Any]:
2644
2745def Authorize () -> t .Callable :
2846 """
29- ========= CONTROLLER AND ROUTE FUNCTION DECORATOR ==============
30- Decorates a controller class or route function with `AuthorizationInterceptor`
31- :return:
47+ Enables authorization checks for a controller or route function.
48+
49+ This decorator adds the AuthorizationInterceptor which performs two main checks:
50+ 1. Verifies that the user is authenticated
51+ 2. Validates any policy requirements specified using @CheckPolicies
52+
53+ Example:
54+ ```python
55+ @Controller()
56+ @Authorize() # Enable authorization for all routes in controller
57+ class SecureController:
58+ @get('/')
59+ @CheckPolicies('admin') # Require admin policy
60+ def secure_endpoint(self):
61+ return {'message': 'secure data'}
62+ ```
63+
64+ Returns:
65+ A decorator function that enables authorization checks.
3266 """
3367
3468 return set_meta (constants .ROUTE_INTERCEPTORS , [AuthorizationInterceptor ])
@@ -39,13 +73,34 @@ def AuthenticationRequired(
3973 openapi_scope : t .Optional [t .List ] = None ,
4074) -> t .Callable :
4175 """
42- ========= CONTROLLER AND ROUTE FUNCTION DECORATOR ==============
43-
44- Decorates a controller class or route function with `IsAuthenticatedGuard`
45-
46- @param authentication_scheme: authentication_scheme - Based on the authentication scheme class name or openapi_name used.
47- @param openapi_scope: OpenAPi scope
48- @return: Callable
76+ Requires authentication for accessing a controller or route function.
77+
78+ This decorator adds the AuthenticatedRequiredGuard which ensures that requests
79+ are authenticated before they can access the protected resource.
80+
81+ Example:
82+ ```python
83+ @Controller()
84+ class UserController:
85+ @get('/profile')
86+ @AuthenticationRequired('jwt') # Require JWT authentication
87+ def get_profile(self):
88+ return {'user': 'data'}
89+
90+ @get('/public')
91+ @AuthenticationRequired(openapi_scope=['read:public'])
92+ def public_data(self):
93+ return {'public': 'data'}
94+ ```
95+
96+ Args:
97+ authentication_scheme: Optional name of the authentication scheme to use.
98+ This should match the scheme name defined in your authentication setup.
99+ openapi_scope: Optional list of OpenAPI security scopes required for the endpoint.
100+ These scopes will be reflected in the OpenAPI documentation.
101+
102+ Returns:
103+ A decorator function that enforces authentication requirements.
49104 """
50105 if callable (authentication_scheme ):
51106 return set_meta (constants .GUARDS_KEY , [AuthenticatedRequiredGuard (None , [])])(
@@ -60,9 +115,28 @@ def AuthenticationRequired(
60115
61116def SkipAuth () -> t .Callable :
62117 """
63- ========= CONTROLLER AND ROUTE FUNCTION DECORATOR ==============
64- Decorates a Class or Route Function with SKIP_AUTH attribute that is checked by `AuthenticationRequiredGuard`
65- @return: Callable
118+ Marks a controller or route function to skip authentication checks.
119+
120+ This decorator is useful when you have a controller with @AuthenticationRequired
121+ but want to exclude specific routes from the authentication requirement.
122+
123+ Example:
124+ ```python
125+ @Controller()
126+ @AuthenticationRequired() # Require auth for all routes
127+ class UserController:
128+ @get('/private')
129+ def private_data(self): # This requires auth
130+ return {'private': 'data'}
131+
132+ @get('/public')
133+ @SkipAuth() # This endpoint skips auth
134+ def public_data(self):
135+ return {'public': 'data'}
136+ ```
137+
138+ Returns:
139+ A decorator function that marks the endpoint to skip authentication.
66140 """
67141
68142 return set_meta (
0 commit comments