Rules

Rules are the basic building blocks of Entitled. Fundamentally, a Rule is a simple wrapper around a (somewhat specific) Python function.

Semantically, Rules describes "facts" about your application and about the relationships between the various actors and resources of your app.

If you have ever used Laravel's authorization API, this API is very much inspired by it.

Writing Rules

To make a new rule, you just need a Python Callable that satisfies three criteria:

• It must be an async Callable
• It should accept at least one positional parameter for the actor
• It should return either a boolean or a Response object.

These are the minimum requirements to create a rule. Additionally, if the Callable used is anonymous, you will need to provide a name for the rule:

# With a lambda
is_admin = Rule("is_admin", lambda actor: has_admin_status(actor))

# With a declared callable
async def is_admin(actor: Actor):
    return has_admin_status(actor)

rule_is_admin = Rule(is_admin)

Note : once we tackle policies, you'll be provided a third way to create a rule through policies.

Using Rules

Rules are Callable object themselves that defer to the underlying function, so using them may be ass simple as calling them on the relevant objects

if is_admin(user, post):
    print("User authorized")

However, the Rule class also provides several utility functions :

• Rule.inspect will always wrap the result into a Response object, supplying a default error message.
• Rule.allows does the opposite and systematically returns a boolean (it is equivalent to using rule.inspect().allowed())
• Rule.denies is equivalent to not rule.allows()
• Rule.authorize evaluates the rule, but returns an exception in case if the evaluation would return an error. The exception essentially calls inspect and wraps any error message into an AuthorizationException.

A Warning

Rules are meant to be extremely flexible in their definition, but you'll notice that the evaluation provided by the Rule class don't retain the signature from the underlying Callable

In most cases, you may pass any parameters to an evaluation function, and Entitled will match the parameters to the signature of the underlying function, thus preventing any errors for extra parameters. This system is still quite unoptimized : there is one massive footgun that we'll discover when discussing the Client.