Security Document Management

class SecurityDocument(dict):
    """
    Encapsulates a JSON security document for managing database access permissions.
    
    Parameters:
    - database: CouchDatabase or CloudantDatabase instance
    """
    def __init__(self, database): ...
    
    def fetch(self):
        """
        Retrieves security document content from remote database.
        Overwrites local content with remote document.
        """
    
    def save(self):
        """
        Saves local security document changes to remote database.
        """
    
    def json(self):
        """
        Returns JSON string representation of security document.
        
        Returns:
        str: Encoded JSON string containing security document data
        """
    
    def __enter__(self):
        """Context manager entry - automatically fetches document."""
    
    def __exit__(self, *args):
        """Context manager exit - automatically saves document."""
    
    @property
    def document_url(self):
        """
        Constructs security document URL.
        
        Returns:
        str: Security document URL
        """
    
    @property  
    def r_session(self):
        """
        Returns Python requests session used by security document.
        
        Returns:
        requests.Session: The session object
        """

from cloudant import cloudant
from cloudant.security_document import SecurityDocument

with cloudant(username, password, account=account_name) as client:
    db = client['my_database']
    
    # Context manager automatically fetches and saves
    with SecurityDocument(db) as security_doc:
        # Add users to Cloudant roles
        if 'cloudant' not in security_doc:
            security_doc['cloudant'] = {}
        
        security_doc['cloudant']['julia'] = ['_reader', '_writer']
        security_doc['cloudant']['ruby'] = ['_admin', '_replicator']
        
        # Add users to CouchDB roles  
        if 'admins' not in security_doc:
            security_doc['admins'] = {'names': [], 'roles': []}
        if 'members' not in security_doc:
            security_doc['members'] = {'names': [], 'roles': []}
            
        security_doc['admins']['names'].append('admin_user')
        security_doc['members']['names'].append('regular_user')
        # Document automatically saved on context exit

from cloudant.security_document import SecurityDocument

with cloudant(username, password, account=account_name) as client:
    db = client['my_database']
    security_doc = SecurityDocument(db)
    
    # Manually fetch current security document
    security_doc.fetch()
    
    # Modify permissions
    security_doc['cloudant'] = {
        'admin_user': ['_admin'],
        'read_user': ['_reader']
    }
    
    # Manually save changes
    security_doc.save()
    
    # Get JSON representation
    json_string = security_doc.json()
    print(json_string)

with SecurityDocument(database) as security_doc:
    # Check current Cloudant permissions
    if 'cloudant' in security_doc:
        for user, roles in security_doc['cloudant'].items():
            print(f"User {user} has roles: {roles}")
    
    # Check CouchDB permissions
    if 'admins' in security_doc:
        admin_users = security_doc['admins']['names']
        print(f"Admin users: {admin_users}")
        
    if 'members' in security_doc:
        member_users = security_doc['members']['names']  
        print(f"Member users: {member_users}")

{
    "cloudant": {
        "username": ["_reader", "_writer", "_admin", "_replicator"],
        "another_user": ["_reader"]
    }
}

{
    "admins": {
        "names": ["admin_user"],
        "roles": ["admin_role"]
    },
    "members": {
        "names": ["member_user"],
        "roles": ["member_role"]
    }
}

# Security document roles for Cloudant
CLOUDANT_ROLES = ["_reader", "_writer", "_admin", "_replicator"]

# Security document structure
SecurityDocumentData = dict[str, Any]

# CouchDB section structure
CouchDBSection = dict[str, list[str]]  # keys: "names", "roles"

# Cloudant section structure  
CloudantSection = dict[str, list[str]]  # username -> list of roles

from cloudant.security_document import SecurityDocument