Metadata-Version: 2.4
Name: vexen-rbac
Version: 0.1.0
Summary: Role-Based Access Control library with hexagonal architecture
Project-URL: Homepage, https://github.com/vexen-labs/vexen-rbac
Project-URL: Documentation, https://github.com/vexen-labs/vexen-rbac#readme
Project-URL: Repository, https://github.com/vexen-labs/vexen-rbac
Project-URL: Issues, https://github.com/vexen-labs/vexen-rbac/issues
Author-email: albakore <kevink.contacto@gmail.com>
Maintainer-email: albakore <kevink.contacto@gmail.com>
License: MIT
License-File: LICENSE
Keywords: access-control,async,authorization,clean-architecture,hexagonal-architecture,permissions,rbac,role-based-access-control,sqlalchemy
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: greenlet>=3.0.0
Requires-Dist: sqlalchemy[asyncio]>=2.0.44
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=9.0.1; extra == 'dev'
Requires-Dist: ruff>=0.14.7; extra == 'dev'
Description-Content-Type: text/markdown

# RBAC - Role-Based Access Control Library

A flexible and extensible Role-Based Access Control (RBAC) library built with hexagonal architecture principles, designed to be as simple to use as FastAPI.

## Features

- **Clean Architecture**: Built with hexagonal architecture (ports and adapters)
- **Simple API**: FastAPI-like interface for ease of use
- **Async Support**: Fully asynchronous using SQLAlchemy 2.0+ with asyncpg
- **Type Safe**: Complete type hints for better IDE support
- **Flexible**: Easy to extend and customize
- **Production Ready**: Session management, connection pooling, and error handling

## Installation

```bash
pip install rbac
```

Or with uv:

```bash
uv pip install rbac
```

## Quick Start

```python
from rbac import RBAC
from rbac.application.dto import CreateRoleRequest

# Initialize RBAC
rbac = RBAC(database_url="postgresql+asyncpg://user:pass@localhost/db")
await rbac.init()

# Create a role
role = await rbac.roles.create_role(
    CreateRoleRequest(
        name="admin",
        display_name="Administrator",
        permissions=[1, 2, 3]
    )
)

# List roles with pagination
result = await rbac.service.list_roles_paginated(page=1, page_size=20)

# Get role with expanded permissions
role_detail = await rbac.service.get_role_expanded(role_id=1)

# Close when done
await rbac.close()
```

## Usage with FastAPI

```python
from fastapi import FastAPI
from rbac import RBAC

app = FastAPI()
rbac = RBAC(database_url="postgresql+asyncpg://...")

@app.on_event("startup")
async def startup():
    await rbac.init()

@app.on_event("shutdown")
async def shutdown():
    await rbac.close()

@app.get("/roles")
async def list_roles(page: int = 1, page_size: int = 20):
    result = await rbac.service.list_roles_paginated(page, page_size)
    return result
```

## Features

### Roles

- Create, read, update, delete roles
- List roles with pagination
- Add/remove permissions from roles
- Count roles and permissions

### Permissions

- Create, read, update, delete permissions
- List permissions
- Group permissions by category

### Permission Groups

- Create, read, update, delete permission groups
- Add/remove permissions from groups
- Organize permissions hierarchically

## Architecture

This library follows hexagonal architecture principles:

- **Domain Layer**: Pure business logic (entities, value objects)
- **Application Layer**: Use cases and DTOs
- **Infrastructure Layer**: Database adapters (SQLAlchemy)
- **Public API**: Clean facade hiding complexity

## Requirements

- Python 3.11+
- PostgreSQL (with asyncpg)
- SQLAlchemy 2.0+

## Documentation

- [Usage Guide](USAGE.md) - Complete usage documentation
- [API Examples](API_EXAMPLES.md) - API response formats
- [Integration Guide](INTEGRATION_GUIDE.md) - Framework integration examples
- [New Features](NEW_FEATURES.md) - Recently added features

## Development

```bash
# Clone repository
git clone https://github.com/yourusername/rbac.git
cd rbac

# Install with development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Format code
ruff format .

# Lint code
ruff check .
```

## License

MIT License - see LICENSE file for details

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues and questions, please open an issue on GitHub.
