Users and Groups

class User(SaveMixin, ObjectDeleteMixin, RESTObject):
    """
    GitLab user object with profile and access management.
    
    Key Attributes:
    - id: User ID
    - username: User login name  
    - name: Full display name
    - email: Primary email address
    - state: Account state ("active", "blocked", "deactivated")
    - avatar_url: Profile picture URL
    - web_url: User profile URL
    - created_at: Account creation timestamp
    - last_sign_in_at: Last login timestamp
    - current_sign_in_at: Current session start
    - is_admin: Administrator status
    - can_create_group: Can create groups
    - can_create_project: Can create projects
    - projects_limit: Maximum number of projects
    - external: External user status
    - private_profile: Profile visibility setting
    - location: User location
    - skype: Skype username
    - linkedin: LinkedIn profile
    - twitter: Twitter handle
    - website_url: Personal website
    - organization: Organization name
    - job_title: Job title
    - bio: User biography
    """
    
    def save(self) -> None:
        """
        Save user profile changes.
        
        Raises:
        GitlabUpdateError: If update fails
        """
    
    def delete(self) -> None:
        """
        Delete user account permanently.
        
        Raises:
        GitlabDeleteError: If deletion fails
        """
    
    def block(self) -> dict:
        """
        Block the user account.
        
        Returns:
        Dictionary with operation result
        
        Raises:
        GitlabBlockError: If blocking fails
        """
    
    def unblock(self) -> dict:
        """
        Unblock the user account.
        
        Returns:
        Dictionary with operation result
        
        Raises:
        GitlabUnblockError: If unblocking fails
        """
    
    def deactivate(self) -> dict:
        """
        Deactivate the user account.
        
        Returns:
        Dictionary with operation result
        
        Raises:
        GitlabDeactivateError: If deactivation fails
        """
    
    def activate(self) -> dict:
        """
        Activate the user account.
        
        Returns:
        Dictionary with operation result
        
        Raises:
        GitlabActivateError: If activation fails
        """

class UserManager(CRUDMixin[User]):
    """Manager for GitLab users with comprehensive filtering and administration."""
    
    def list(
        self,
        active: bool | None = None,
        blocked: bool | None = None,
        external: bool | None = None,
        exclude_external: bool | None = None,
        without_projects: bool | None = None,
        admins: bool | None = None,
        order_by: str | None = None,
        sort: str | None = None,
        search: str | None = None,
        username: str | None = None,
        extern_uid: str | None = None,
        provider: str | None = None,
        created_before: str | None = None,
        created_after: str | None = None,
        with_custom_attributes: bool | None = None,
        two_factor: str | None = None,
        without_project_bots: bool | None = None,
        **kwargs
    ) -> list[User]:
        """
        List users with extensive filtering options.
        
        Parameters:
        - active: Filter by active status
        - blocked: Filter by blocked status
        - external: Filter by external user status
        - exclude_external: Exclude external users
        - without_projects: Users without projects
        - admins: Filter by admin status
        - order_by: Order by field ("id", "name", "username", "created_at", "updated_at")
        - sort: Sort direction ("asc", "desc")
        - search: Search in name, username, and email
        - username: Filter by specific username
        - extern_uid: Filter by external UID
        - provider: Filter by authentication provider
        - created_before: Filter by creation date (ISO format)
        - created_after: Filter by creation date (ISO format)
        - with_custom_attributes: Include custom attributes
        - two_factor: Filter by 2FA status ("enabled", "disabled")
        - without_project_bots: Exclude project bot users
        
        Returns:
        List of User objects
        """
    
    def get(self, id: int | str, lazy: bool = False, **kwargs) -> User:
        """
        Get a specific user.
        
        Parameters:
        - id: User ID or username
        - lazy: Return object without making API call
        - with_custom_attributes: Include custom attributes
        
        Returns:
        User object
        
        Raises:
        GitlabGetError: If user not found
        """
    
    def create(self, data: dict, **kwargs) -> User:
        """
        Create a new user account.
        
        Parameters:
        - data: User creation parameters
        
        Required fields in data:
        - email: User email address
        - password: User password  
        - username: User login name
        - name: Full display name
        
        Optional fields in data:
        - skype: Skype username
        - linkedin: LinkedIn profile
        - twitter: Twitter handle
        - website_url: Personal website
        - organization: Organization name
        - projects_limit: Maximum projects (default: global limit)
        - extern_uid: External authentication UID
        - provider: Authentication provider
        - bio: User biography
        - location: User location
        - admin: Admin privileges (default: False)
        - can_create_group: Can create groups (default: True)
        - skip_confirmation: Skip email confirmation
        - external: External user status (default: False)
        - avatar: Avatar image file
        - private_profile: Make profile private (default: False)
        - color_scheme_id: Color scheme ID
        - theme_id: Theme ID
        - force_random_password: Generate random password
        - reset_password: Send password reset email
        
        Returns:
        New User object
        
        Raises:
        GitlabCreateError: If user creation fails
        """

class CurrentUser(SaveMixin, RESTObject):
    """
    Represents the currently authenticated user with enhanced profile management.
    
    Provides access to current user's resources and settings.
    """
    
    def save(self) -> None:
        """Save current user profile changes."""

class CurrentUserManager(GetWithoutIdMixin[CurrentUser], UpdateMixin[CurrentUser]):
    """Manager for current user operations."""
    
    def get(self, **kwargs) -> CurrentUser:
        """
        Get current user information.
        
        Returns:
        CurrentUser object
        """
    
    def update(self, data: dict, **kwargs) -> CurrentUser:
        """
        Update current user profile.
        
        Parameters:
        - data: Profile update data
        
        Returns:
        Updated CurrentUser object
        """

class UserKey(ObjectDeleteMixin, RESTObject):
    """
    User SSH key object.
    
    Attributes:
    - id: Key ID
    - title: Key title/name
    - key: SSH public key content
    - created_at: Creation timestamp
    - expires_at: Expiration timestamp (optional)
    - usage_type: Key usage type
    """
    
    def delete(self) -> None:
        """Delete SSH key."""

class UserKeyManager(ListMixin[UserKey], CreateMixin[UserKey], DeleteMixin[UserKey]):
    """Manager for user SSH keys."""
    
    def list(self, **kwargs) -> list[UserKey]:
        """List user's SSH keys."""
    
    def create(self, data: dict, **kwargs) -> UserKey:
        """
        Create new SSH key for user.
        
        Parameters:
        - data: Key creation data
        
        Required fields:
        - title: Key title
        - key: SSH public key content
        
        Optional fields:
        - expires_at: Expiration date (ISO format)
        - usage_type: Key usage type
        """

class CurrentUserKey(ObjectDeleteMixin, RESTObject):
    """Current user's SSH key object."""

class CurrentUserKeyManager(CRUDMixin[CurrentUserKey]):
    """Manager for current user's SSH keys."""

class UserGPGKey(ObjectDeleteMixin, RESTObject):
    """
    User GPG key object.
    
    Attributes:
    - id: Key ID
    - key: GPG public key content
    - created_at: Creation timestamp
    - emails: Associated email addresses
    - subkeys: GPG subkeys
    """

class UserGPGKeyManager(ListMixin[UserGPGKey], CreateMixin[UserGPGKey], DeleteMixin[UserGPGKey]):
    """Manager for user GPG keys."""
    
    def create(self, data: dict, **kwargs) -> UserGPGKey:
        """
        Add GPG key to user.
        
        Parameters:
        - data: Key data with 'key' field containing GPG public key
        """

class CurrentUserGPGKey(ObjectDeleteMixin, RESTObject):
    """Current user's GPG key object."""

class CurrentUserGPGKeyManager(CRUDMixin[CurrentUserGPGKey]): 
    """Manager for current user's GPG keys."""

class UserEmail(ObjectDeleteMixin, RESTObject):
    """
    User email address object.
    
    Attributes:
    - id: Email ID
    - email: Email address
    - confirmed_at: Confirmation timestamp
    """
    
class UserEmailManager(ListMixin[UserEmail], CreateMixin[UserEmail], DeleteMixin[UserEmail]):
    """Manager for user email addresses."""
    
    def create(self, data: dict, **kwargs) -> UserEmail:
        """
        Add email address to user.
        
        Parameters:
        - data: Email data with 'email' field
        """

class CurrentUserEmail(ObjectDeleteMixin, RESTObject):
    """Current user's email address object."""

class CurrentUserEmailManager(ListMixin[CurrentUserEmail], CreateMixin[CurrentUserEmail]):
    """Manager for current user's email addresses."""

class Group(SaveMixin, ObjectDeleteMixin, RESTObject):
    """
    GitLab group object with comprehensive resource management.
    
    Key Attributes:
    - id: Group ID
    - name: Group name
    - path: Group path (URL slug)
    - full_name: Full group name with parent hierarchy
    - full_path: Full group path with parent hierarchy
    - description: Group description
    - visibility: Group visibility ("private", "internal", "public")
    - lfs_enabled: Git LFS enabled status
    - avatar_url: Group avatar URL
    - web_url: Group web URL
    - request_access_enabled: Allow access requests
    - parent_id: Parent group ID (for subgroups)
    - created_at: Creation timestamp
    - statistics: Group statistics (if included)
    """
    
    def save(self) -> None:
        """
        Save group changes.
        
        Raises:
        GitlabUpdateError: If update fails
        """
    
    def delete(self) -> None:
        """
        Delete group permanently.
        
        Raises:
        GitlabDeleteError: If deletion fails
        """
    
    def transfer(self, to_parent_id: int | None) -> dict:
        """
        Transfer group to different parent.
        
        Parameters:
        - to_parent_id: Target parent group ID (None for root level)
        
        Returns:
        Dictionary with transfer result
        
        Raises:
        GitlabGroupTransferError: If transfer fails
        """

class GroupManager(CRUDMixin[Group]):
    """Manager for GitLab groups with comprehensive filtering."""
    
    def list(
        self,
        skip_groups: list[int] | None = None,
        all_available: bool | None = None,
        search: str | None = None,
        order_by: str | None = None,
        sort: str | None = None,
        statistics: bool | None = None,
        with_custom_attributes: bool | None = None,
        owned: bool | None = None,
        min_access_level: int | None = None,
        top_level_only: bool | None = None,
        **kwargs
    ) -> list[Group]:
        """
        List groups with filtering options.
        
        Parameters:
        - skip_groups: Group IDs to skip
        - all_available: Include all available groups
        - search: Search in group name and path
        - order_by: Order by field ("name", "path", "id", "similarity")
        - sort: Sort direction ("asc", "desc")
        - statistics: Include group statistics
        - with_custom_attributes: Include custom attributes
        - owned: Show only owned groups
        - min_access_level: Minimum access level
        - top_level_only: Show only top-level groups
        
        Returns:
        List of Group objects
        """
    
    def create(self, data: dict, **kwargs) -> Group:
        """
        Create a new group.
        
        Parameters:
        - data: Group creation parameters
        
        Required fields:
        - name: Group name
        - path: Group path
        
        Optional fields:
        - description: Group description
        - visibility: Group visibility ("private", "internal", "public")
        - lfs_enabled: Enable Git LFS (default: True)
        - request_access_enabled: Allow access requests (default: False)
        - parent_id: Parent group ID (for subgroups)
        - auto_devops_enabled: Enable Auto DevOps
        - emails_disabled: Disable group emails
        - mentions_disabled: Disable group mentions
        - subgroup_creation_level: Subgroup creation level
        - project_creation_level: Project creation level
        - share_with_group_lock: Prevent sharing with other groups
        - require_two_factor_authentication: Require 2FA for members
        - two_factor_grace_period: 2FA grace period in hours
        - default_branch_protection: Default branch protection level
        
        Returns:
        New Group object
        
        Raises:
        GitlabCreateError: If group creation fails
        """

class GroupMember(SaveMixin, ObjectDeleteMixin, RESTObject):
    """
    Group member object with access level management.
    
    Attributes:
    - id: User ID
    - username: Username
    - name: Full name
    - access_level: Access level (10=Guest, 20=Reporter, 30=Developer, 40=Maintainer, 50=Owner)
    - expires_at: Membership expiration date
    """
    
    def save(self) -> None:
        """Save member access level changes."""
    
    def delete(self) -> None:
        """Remove member from group."""

class GroupMemberManager(CRUDMixin[GroupMember]):
    """Manager for group members."""
    
    def list(
        self,
        query: str | None = None,
        user_ids: list[int] | None = None,
        **kwargs
    ) -> list[GroupMember]:
        """
        List group members.
        
        Parameters:
        - query: Search query for member names
        - user_ids: Filter by specific user IDs
        
        Returns:
        List of GroupMember objects
        """
    
    def create(self, data: dict, **kwargs) -> GroupMember:
        """
        Add member to group.
        
        Parameters:
        - data: Member data
        
        Required fields:
        - user_id: User ID to add
        - access_level: Access level (10-50)
        
        Optional fields:
        - expires_at: Membership expiration date (ISO format)
        
        Returns:
        New GroupMember object
        """

# Similar classes for all group members (including inherited)
class GroupMemberAll(RESTObject):
    """Group member including inherited members."""

class GroupMemberAllManager(ListMixin[GroupMemberAll]):
    """Manager for all group members including inherited."""

class GroupAccessRequest(ObjectDeleteMixin, RESTObject):
    """
    Group access request object.
    
    Attributes:
    - id: Request ID
    - username: Requesting username
    - name: Full name
    - requested_at: Request timestamp
    """
    
    def approve(self, access_level: int = 30) -> dict:
        """
        Approve access request.
        
        Parameters:
        - access_level: Access level to grant (default: 30=Developer)
        
        Returns:
        Dictionary with approval result
        """

class GroupAccessRequestManager(ListMixin[GroupAccessRequest], CreateMixin[GroupAccessRequest], DeleteMixin[GroupAccessRequest]):
    """Manager for group access requests."""

import gitlab
from gitlab import DEVELOPER_ACCESS, MAINTAINER_ACCESS

# Initialize client
gl = gitlab.Gitlab("https://gitlab.example.com", private_token="your-token")

# User management
users = gl.users.list(active=True, search="john")
user = gl.users.get(123)

# Update user profile
user.bio = "Updated biography"
user.location = "New York"
user.save()

# Block/unblock user
user.block()
user.unblock()

# Create new user
user_data = {
    "email": "newuser@example.com",
    "password": "secure_password",
    "username": "newuser",
    "name": "New User",
    "projects_limit": 10,
    "can_create_group": True
}
new_user = gl.users.create(user_data)

# Current user operations
current_user = gl.user
print(f"Logged in as: {current_user.name}")

# Manage SSH keys
keys = current_user.keys.list()
key_data = {
    "title": "My Laptop Key",
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ..."
}
new_key = current_user.keys.create(key_data)

# Group management
groups = gl.groups.list(owned=True, order_by="name")
group = gl.groups.get(456)

# Create subgroup
subgroup_data = {
    "name": "Development Team",
    "path": "dev-team", 
    "parent_id": group.id,
    "visibility": "private"
}
subgroup = gl.groups.create(subgroup_data)

# Group member management
members = group.members.list()

# Add member to group
member_data = {
    "user_id": 123,
    "access_level": DEVELOPER_ACCESS,
    "expires_at": "2024-12-31"
}
new_member = group.members.create(member_data)

# Update member access level
member = group.members.get(123)
member.access_level = MAINTAINER_ACCESS
member.save()

# Remove member
member.delete()

# Handle access requests
access_requests = group.accessrequests.list()
for request in access_requests:
    request.approve(access_level=DEVELOPER_ACCESS)

# Transfer group
group.transfer(to_parent_id=None)  # Move to root level

# Delete user (admin only)
# user.delete()

class GitlabBlockError(GitlabOperationError):
    """Raised when user blocking fails."""
    pass

class GitlabUnblockError(GitlabOperationError):
    """Raised when user unblocking fails."""
    pass

class GitlabActivateError(GitlabOperationError):
    """Raised when user activation fails."""
    pass

class GitlabDeactivateError(GitlabOperationError):
    """Raised when user deactivation fails."""
    pass

class GitlabGroupTransferError(GitlabOperationError):
    """Raised when group transfer fails."""
    pass

try:
    user = gl.users.create(invalid_user_data)
except gitlab.GitlabCreateError as e:
    print(f"User creation failed: {e}")

try:
    user.block()
except gitlab.GitlabBlockError as e:
    print(f"Cannot block user: {e}")

try:
    group.transfer(invalid_parent_id)
except gitlab.GitlabGroupTransferError as e:
    print(f"Group transfer failed: {e}")