PyCasbin

Warnings

• breaking Version 2.0.0 introduced breaking changes. While specific API changes are not fully detailed in the public changelog, a major version bump indicates potential incompatibilities. Users upgrading from v1.x should review the changelog for any necessary adaptations.
  Fix: Consult the official changelog and documentation on GitHub for details when upgrading from PyCasbin v1.x to v2.x.
• gotcha Performance differences: The Python implementation of Casbin (`PyCasbin`) can be significantly slower (up to 30x in some cases) than its Go counterpart (`Go-Casbin`) when dealing with large or complex policy sets. This is primarily due to differences in the underlying expression evaluation engines.
  Fix: For performance-critical applications with extensive policies, consider benchmarking or evaluating `Go-Casbin` via its FFI or gRPC interfaces if raw speed is paramount, or carefully design policies to minimize complexity.
• gotcha Logging configuration: PyCasbin uses Python's standard `logging` module. If an application sets up its own logger, this can lead to duplicate log messages or prevent PyCasbin's logs from appearing if the application's logging is not correctly configured to handle it.
  Fix: Initialize your application's logger before importing `casbin` or explicitly configure logging for the `casbin` logger (`logging.getLogger('casbin')`) to avoid conflicts or ensure messages are captured. Use the `logging_config` parameter during enforcer initialization if specific logging settings are required for `pycasbin`.
• gotcha ABAC `in` operator behavior: When using the `in` operator in matchers for Attribute-Based Access Control (ABAC) with array literals (e.g., `r.obj in ('data2', 'data3')`), some Casbin implementations across languages might have specific requirements, such as the array length being greater than one to avoid unexpected behavior or panics. Ensure your array literals are well-formed and test thoroughly.
  Fix: Always ensure array literals used with the `in` operator contain at least two elements if this specific syntax is causing issues, or consult the Casbin model syntax documentation for your specific implementation details to ensure correct usage.

Install

• pip install pycasbin Install PyCasbin

Imports

• Enforcer

  import casbin
  enforcer = casbin.Enforcer(...)

  The primary class `Enforcer` is accessed directly via the `casbin` top-level package, not `pycasbin`.
• SyncedEnforcer

  from casbin import SyncedEnforcer

  For thread-safe operations in multi-threaded applications, use `SyncedEnforcer`.
• AsyncEnforcer

  from casbin.enforcer import Enforcer as AsyncEnforcer
  # or
  from casbin.enforcer import AsyncEnforcer # if using direct import and not renaming

  Asynchronous operations are supported from PyCasbin >= 1.23.0. The `Enforcer` class itself can act as an async enforcer, or `AsyncEnforcer` can be imported explicitly.

Quickstart

This quickstart demonstrates how to initialize `casbin.Enforcer` with a model (`.conf`) and policy (`.csv`) file, and then use the `enforce()` method to check permissions. It also shows a dynamic policy addition. Note the use of `asyncio.run` as the `enforce` method is asynchronous.

import casbin
import os

# Create dummy model and policy files for the example
with open('model.conf', 'w') as f:
    f.write('''
[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = r.sub == p.sub && r.obj == p.obj && r.act == p.act
''')

with open('policy.csv', 'w') as f:
    f.write('''
p, alice, data1, read
p, bob, data2, write
p, data2_admin, data2, *
''')

async def run_enforcer():
    # Initialize an enforcer with a model file and a policy file
    # For real applications, use an adapter (e.g., casbin_sqlalchemy_adapter)
    e = casbin.Enforcer('model.conf', 'policy.csv')

    # Test if 'alice' can 'read' 'data1'
    if await e.enforce('alice', 'data1', 'read'):
        print("Alice CAN read data1")
    else:
        print("Alice CANNOT read data1")

    # Test if 'bob' can 'read' 'data2'
    if await e.enforce('bob', 'data2', 'read'):
        print("Bob CAN read data2")
    else:
        print("Bob CANNOT read data2")

    # Test if 'bob' can 'write' 'data2'
    if await e.enforce('bob', 'data2', 'write'):
        print("Bob CAN write data2")
    else:
        print("Bob CANNOT write data2")

    # Add a policy dynamically
    await e.add_policy('cathy', 'data3', 'read')
    if await e.enforce('cathy', 'data3', 'read'):
        print("Cathy CAN read data3 (after adding policy)")

    # Remove temporary files
    os.remove('model.conf')
    os.remove('policy.csv')

if __name__ == '__main__':
    import asyncio
    asyncio.run(run_enforcer())