tessl/pypi-jira

Python library for interacting with JIRA via REST APIs.

—

Pending

Overview

Eval results

Files

User & Group Management

Name: tessl/pypi-jira
Author: tessl

User administration including user creation, group management, permissions, avatar management, and user search functionality. These operations typically require administrative permissions in JIRA.

Capabilities

User Operations

Core user management functions for retrieving, creating, and managing JIRA users.

def user(self, id: str, expand: str = None) -> User:
    """
    Get user information by username or user ID.
    
    Parameters:
    - id: Username or user ID
    - expand: Properties to expand (groups, applicationRoles)
    
    Returns:
    User object
    """

def search_users(
    self,
    user: str,
    startAt: int = 0,
    maxResults: int = 50,
    includeActive: bool = True,
    includeInactive: bool = False
) -> list[User]:
    """
    Search for users by username or display name.
    
    Parameters:
    - user: Username or display name search term
    - startAt: Starting index for pagination
    - maxResults: Maximum number of results
    - includeActive: Include active users
    - includeInactive: Include inactive users
    
    Returns:
    List of matching User objects
    """

def add_user(
    self,
    username: str,
    email: str,
    directoryId: int = 1,
    password: str = None,
    fullname: str = None,
    notify: bool = False,
    active: bool = True,
    ignore_existing: bool = False,
    application_keys: list = None
) -> User:
    """
    Create a new user.
    
    Parameters:
    - username: Username (must be unique)
    - email: Email address
    - directoryId: Directory ID for user creation
    - password: User password (auto-generated if not provided)
    - fullname: Full display name
    - notify: Send notification email to user
    - active: Whether user is active
    - ignore_existing: Don't fail if user already exists
    - application_keys: List of application keys for access
    
    Returns:
    Created User object
    """

def rename_user(self, old_user: str, new_user: str) -> None:
    """
    Rename a user.
    
    Parameters:
    - old_user: Current username
    - new_user: New username
    """

def delete_user(self, username: str) -> None:
    """Delete a user account."""

def deactivate_user(self, username: str) -> None:
    """Deactivate a user account."""

Usage examples:

# Get user information
user = jira.user('john.doe')
print(f"Name: {user.displayName}")
print(f"Email: {user.emailAddress}")
print(f"Active: {user.active}")

# Get user with expanded groups
user = jira.user('john.doe', expand='groups')
groups = [group['name'] for group in user.groups['items']]
print(f"User groups: {groups}")

# Search for users
users = jira.search_users('john', maxResults=10)
for user in users:
    print(f"{user.name}: {user.displayName}")

# Create new user
new_user = jira.add_user(
    username='jane.smith',
    email='jane.smith@company.com',
    fullname='Jane Smith',
    password='temporary123',
    notify=True
)
print(f"Created user: {new_user.displayName}")

# Rename user
jira.rename_user('old.username', 'new.username')

# Deactivate user
jira.deactivate_user('inactive.user')

User Search for Assignment

Specialized user search functions for finding users who can be assigned to issues or projects.

def search_assignable_users_for_projects(
    self,
    username: str,
    projectKeys: list[str],
    startAt: int = 0,
    maxResults: int = 50
) -> list[User]:
    """
    Search for users who can be assigned to issues in specific projects.
    
    Parameters:
    - username: Username search term
    - projectKeys: List of project keys to check assignment permissions
    - startAt: Starting index for pagination
    - maxResults: Maximum number of results
    
    Returns:
    List of assignable User objects
    """

def search_assignable_users_for_issues(
    self,
    username: str,
    project: str = None,
    issueKey: str = None,
    expand: str = None,
    startAt: int = 0,
    maxResults: int = 50
) -> list[User]:
    """
    Search for users who can be assigned to specific issues.
    
    Parameters:
    - username: Username search term
    - project: Project key to check assignment permissions
    - issueKey: Specific issue key to check assignment permissions
    - expand: Properties to expand
    - startAt: Starting index for pagination
    - maxResults: Maximum number of results
    
    Returns:
    List of assignable User objects
    """

def search_allowed_users_for_issue(
    self,
    user: str,
    issueKey: str = None,
    projectKey: str = None,
    startAt: int = 0,
    maxResults: int = 50
) -> list[User]:
    """
    Search for users who have permissions for specific issues.
    
    Parameters:
    - user: Username search term
    - issueKey: Issue key to check permissions
    - projectKey: Project key to check permissions
    - startAt: Starting index for pagination
    - maxResults: Maximum number of results
    
    Returns:
    List of allowed User objects
    """

Usage examples:

# Find users who can be assigned in projects
assignable_users = jira.search_assignable_users_for_projects(
    username='john',
    projectKeys=['PROJ1', 'PROJ2']
)

# Find users who can be assigned to a specific issue
assignable_users = jira.search_assignable_users_for_issues(
    username='jane',
    issueKey='PROJ-123'
)

# Find users with permissions for an issue
allowed_users = jira.search_allowed_users_for_issue(
    user='smith',
    issueKey='PROJ-123'
)

User Avatars

Manage user avatar images.

def user_avatars(self, username: str) -> dict:
    """Get available avatars for a user."""

def create_temp_user_avatar(
    self,
    user: str,
    filename: str,
    size: int,
    avatar_img,
    contentType: str = None,
    auto_confirm: bool = False
) -> dict:
    """Create temporary user avatar."""

def confirm_user_avatar(self, user: str, cropping_properties: dict) -> dict:
    """Confirm and crop user avatar."""

def set_user_avatar(self, username: str, avatar: str) -> None:
    """Set user avatar."""

def delete_user_avatar(self, username: str, avatar: str) -> None:
    """Delete user avatar."""

Usage examples:

# Get user avatars
avatars = jira.user_avatars('john.doe')
print(f"Available avatars: {len(avatars['system']) + len(avatars['custom'])}")

# Upload new avatar
with open('profile_pic.jpg', 'rb') as avatar_file:
    temp_avatar = jira.create_temp_user_avatar(
        user='john.doe',
        filename='profile_pic.jpg',
        size=avatar_file.tell(),
        avatar_img=avatar_file,
        contentType='image/jpeg'
    )

# Confirm avatar with cropping
cropping = {
    'cropperOffsetX': 10,
    'cropperOffsetY': 10,
    'cropperWidth': 100,
    'cropperHeight': 100
}
confirmed_avatar = jira.confirm_user_avatar('john.doe', cropping)

Group Management

Manage JIRA groups and group memberships.

def groups(self, query: str = None, exclude: str = None, maxResults: int = 9999) -> list[dict]:
    """
    Get groups matching criteria.
    
    Parameters:
    - query: Group name search term
    - exclude: Group names to exclude from results
    - maxResults: Maximum number of results
    
    Returns:
    List of group dictionaries
    """

def group_members(self, group: str) -> list[User]:
    """
    Get members of a group.
    
    Parameters:
    - group: Group name
    
    Returns:
    List of User objects in the group
    """

def add_group(self, groupname: str) -> dict:
    """
    Create a new group.
    
    Parameters:
    - groupname: Name of the group to create
    
    Returns:
    Created group dictionary
    """

def remove_group(self, groupname: str) -> None:
    """
    Delete a group.
    
    Parameters:
    - groupname: Name of the group to delete
    """

def add_user_to_group(self, username: str, group: str) -> None:
    """
    Add a user to a group.
    
    Parameters:
    - username: Username to add
    - group: Group name
    """

def remove_user_from_group(self, username: str, groupname: str) -> None:
    """
    Remove a user from a group.
    
    Parameters:
    - username: Username to remove
    - groupname: Group name
    """

Usage examples:

# Get all groups
groups = jira.groups()
for group in groups:
    print(f"Group: {group['name']}")

# Search for specific groups
dev_groups = jira.groups(query='developer')
for group in dev_groups:
    print(f"Dev group: {group['name']}")

# Get group members
members = jira.group_members('developers')
for member in members:
    print(f"Member: {member.displayName}")

# Create new group
new_group = jira.add_group('qa-team')
print(f"Created group: {new_group['name']}")

# Add user to group
jira.add_user_to_group('john.doe', 'developers')

# Remove user from group
jira.remove_user_from_group('jane.smith', 'old-team')

# Delete group
jira.remove_group('deprecated-group')

User Properties

Common user properties available in User objects:

user = jira.user('john.doe')

# Basic properties
print(f"Username: {user.name}")
print(f"Display Name: {user.displayName}")
print(f"Email: {user.emailAddress}")
print(f"Active: {user.active}")
print(f"Time Zone: {user.timeZone}")
print(f"Locale: {user.locale}")

# Avatar URLs
print(f"Avatar: {user.avatarUrls['48x48']}")

# With expanded groups
user = jira.user('john.doe', expand='groups')
groups = [group['name'] for group in user.groups['items']]
print(f"Groups: {', '.join(groups)}")

Group Management Examples

Common group management patterns:

# Bulk add users to group
usernames = ['user1', 'user2', 'user3']
group_name = 'project-team'

for username in usernames:
    try:
        jira.add_user_to_group(username, group_name)
        print(f"Added {username} to {group_name}")
    except Exception as e:
        print(f"Failed to add {username}: {e}")

# Move users from one group to another
old_group = 'old-team'
new_group = 'new-team'

old_members = jira.group_members(old_group)
for member in old_members:
    jira.add_user_to_group(member.name, new_group)
    jira.remove_user_from_group(member.name, old_group)
    print(f"Moved {member.displayName} from {old_group} to {new_group}")

# Find inactive users
all_users = jira.search_users('', includeInactive=True, maxResults=1000)
inactive_users = [user for user in all_users if not user.active]
print(f"Found {len(inactive_users)} inactive users")

User Creation Best Practices

When creating users programmatically:

# Create user with all recommended fields
new_user = jira.add_user(
    username='new.employee',
    email='new.employee@company.com',
    fullname='New Employee',
    notify=True,  # Send welcome email
    active=True,
    application_keys=['jira-software']  # Grant appropriate access
)

# Add to appropriate groups immediately
jira.add_user_to_group(new_user.name, 'employees')
jira.add_user_to_group(new_user.name, 'project-users')

print(f"Created and configured user: {new_user.displayName}")

Install with Tessl CLI