Python API


class oso.Oso

The central object to manage application policy state, e.g. the policy data, and verify requests.

>>> from oso import Oso
>>> Oso()
<oso.oso.Oso object at 0x...>
get_allowed_actions(actor, resource, allow_wildcard=False)list

Determine the actions actor is allowed to take on resource.

Collects all actions allowed by allow rules in the Polar policy for the given combination of actor and resource.

  • actor – The actor for whom to collect allowed actions

  • resource – The resource being accessed

  • allow_wildcard (bool) – Flag to determine behavior if the policy includes a wildcard action. E.g., a rule allowing any action: allow(_actor, _action, _resource). If True, the method will return ["*"], if False, the method will raise an exception.


A list of the unique allowed actions.

is_allowed(actor, action, resource)bool

Evaluate whether actor is allowed to perform action on resource.

Uses allow rules in the Polar policy to determine whether a request is permitted. actor and resource should be classes that have been registered with Polar using the register_class() function or the polar_class decorator.

  • actor – The actor performing the request.

  • action – The action the actor is attempting to perform.

  • resource – The resource being accessed.


True if the request is allowed, False otherwise.


Load Polar policy from a “.polar” file.

load_str(string, filename=None)

Load a Polar string, checking that all inline queries succeed.

query(query, *, bindings=None, accept_expression=False)

Query for a predicate, parsing it if necessary.


query – The predicate to query for.


The result of the query.

query_rule(name, *args, **kwargs)

Query for rule with name name and arguments args.

  • name – The name of the predicate to query.

  • args – Arguments for the predicate.


The result of the query.

register_class(cls, *, name=None)

Register cls as a class accessible by Polar.

class oso.Variable

An unbound variable type, can be used to query the KB for information

class oso.Predicate(name: str, args: Sequence[Any])

Represent a predicate in Polar (name(args, …)).

Decorator Functions

oso.polar_class(_cls=None, *, name=None)

Decorator to register a Python class with Polar. An alternative to register_class().


Exceptions used within polar.

exception polar.exceptions.DuplicateClassAliasError(name, old, new)

Bases: polar.exceptions.PolarRuntimeError

Raised on attempts to register a class with the same name as a class that has already been registered

exception polar.exceptions.DuplicateInstanceRegistrationError(message=None, details=None)

Bases: polar.exceptions.PolarRuntimeError

exception polar.exceptions.ExtraToken(message=None, details=None)

Bases: polar.exceptions.ParserError

exception polar.exceptions.FFIErrorNotFound(message=None, details=None)

Bases: polar.exceptions.OsoError

Raised when an error is generated by the oso Rust core, but the error type is not found.

exception polar.exceptions.FileLoadingError(message=None, details=None)

Bases: polar.exceptions.PolarRuntimeError

Error loading a Polar file

exception polar.exceptions.InlineQueryFailedError(source)

Bases: polar.exceptions.PolarRuntimeError

exception polar.exceptions.IntegerOverflow(message=None, details=None)

Bases: polar.exceptions.ParserError

exception polar.exceptions.InvalidCallError(message=None, details=None)

Bases: polar.exceptions.PolarRuntimeError

Invalid attempt to call a field or method on an object in Polar

exception polar.exceptions.InvalidConstructorError(message=None, details=None)

Bases: polar.exceptions.PolarRuntimeError

exception polar.exceptions.InvalidIteratorError(message=None, details=None)

Bases: polar.exceptions.PolarRuntimeError

Invalid attempt to iterate over a non-iterable value

exception polar.exceptions.InvalidQueryTypeError(message=None, details=None)

Bases: polar.exceptions.PolarRuntimeError

exception polar.exceptions.InvalidToken(message=None, details=None)

Bases: polar.exceptions.ParserError

exception polar.exceptions.InvalidTokenCharacter(message=None, details=None)

Bases: polar.exceptions.ParserError

exception polar.exceptions.OperationalError(message=None, details=None)

Bases: polar.exceptions.OsoError

Errors from polar that are not necessarily the user’s fault. OOM etc…

exception polar.exceptions.OsoError(message=None, details=None)

Bases: Exception

Base exception class for oso.

exception polar.exceptions.ParameterError(message=None, details=None)

Bases: polar.exceptions.PolarApiError

exception polar.exceptions.ParserError(message=None, details=None)

Bases: polar.exceptions.OsoError

Parse time errors.

exception polar.exceptions.PolarApiError(message=None, details=None)

Bases: polar.exceptions.OsoError

Errors coming from the python bindings to polar, not the engine itself.

exception polar.exceptions.PolarFileExtensionError(file)

Bases: polar.exceptions.PolarRuntimeError

exception polar.exceptions.PolarFileNotFoundError(file)

Bases: polar.exceptions.PolarRuntimeError

exception polar.exceptions.PolarRuntimeError(message=None, details=None)

Bases: polar.exceptions.OsoError

Errors generated by oso at runtime

exception polar.exceptions.PolarTypeError(message=None, details=None)

Bases: polar.exceptions.PolarRuntimeError

Error related to the type of a Polar object, generated by the Rust core

exception polar.exceptions.SerializationError(message=None, details=None)

Bases: polar.exceptions.PolarRuntimeError

Error serializing data across the FFI boundary

exception polar.exceptions.StackOverflowError(message=None, details=None)

Bases: polar.exceptions.PolarRuntimeError

Polar stack overflow error, generated by the Rust core

exception polar.exceptions.UnexpectedPolarTypeError(message=None, details=None)

Bases: polar.exceptions.PolarRuntimeError

exception polar.exceptions.UnknownError(message=None, details=None)

Bases: polar.exceptions.OperationalError

exception polar.exceptions.UnrecognizedEOF(message=None, details=None)

Bases: polar.exceptions.ParserError

exception polar.exceptions.UnrecognizedToken(message=None, details=None)

Bases: polar.exceptions.ParserError

exception polar.exceptions.UnregisteredClassError(message=None, details=None)

Bases: polar.exceptions.PolarRuntimeError

Raised on attempts to reference unregistered Python classes from a Polar policy.

exception polar.exceptions.UnregisteredInstanceError(message=None, details=None)

Bases: polar.exceptions.PolarRuntimeError

exception polar.exceptions.UnsupportedError(message=None, details=None)

Bases: polar.exceptions.PolarRuntimeError

Unsupported action error generated by the Rust core