tessl/pypi-jira

Python library for interacting with JIRA via REST APIs.

—

Pending

Overview

Eval results

Files

System Operations & Administration

Name: tessl/pypi-jira
Author: tessl

Administrative and system-level operations including server information, session management, backup, reindexing, and application configuration. These operations typically require system administrator permissions.

Capabilities

Server Information & Properties

Retrieve server configuration, version information, and manage application properties.

def server_info(self) -> dict:
    """
    Get JIRA server information including version, build, and deployment details.
    
    Returns:
    Dictionary containing server information
    """

def myself(self) -> User:
    """
    Get current authenticated user information.
    
    Returns:
    User object for current user
    """

def current_user(self) -> str:
    """
    Get current authenticated username.
    
    Returns:
    Username string
    """

def application_properties(self, key: str = None) -> dict:
    """
    Get server application properties.
    
    Parameters:
    - key: Specific property key to retrieve (returns all if None)
    
    Returns:
    Dictionary of application properties
    """

def set_application_property(self, key: str, value: str) -> dict:
    """
    Set an application property value.
    
    Parameters:
    - key: Property key
    - value: Property value
    
    Returns:
    Response dictionary
    """

def applicationlinks(self, cached: bool = True) -> list[dict]:
    """
    Get application links configured in JIRA.
    
    Parameters:
    - cached: Whether to use cached results
    
    Returns:
    List of application link dictionaries
    """

Usage examples:

# Get server information
server_info = jira.server_info()
print(f"JIRA Version: {server_info['version']}")
print(f"Build Number: {server_info['buildNumber']}")
print(f"Server Time: {server_info['serverTime']}")
print(f"Deployment Type: {server_info['deploymentType']}")

# Get current user info
current_user = jira.myself()
print(f"Logged in as: {current_user.displayName}")
print(f"Email: {current_user.emailAddress}")
print(f"Time Zone: {current_user.timeZone}")

# Get username only
username = jira.current_user()
print(f"Current username: {username}")

# Get application properties
all_props = jira.application_properties()
for key, value in all_props.items():
    print(f"{key}: {value}")

# Get specific property
jira_title = jira.application_properties('jira.title')
print(f"JIRA Instance Title: {jira_title}")

# Set application property (requires admin permissions)
jira.set_application_property('jira.title', 'My Company JIRA')

# Get application links
app_links = jira.applicationlinks()
for link in app_links:
    print(f"App Link: {link['name']} -> {link['displayUrl']}")

Session Management

Manage user sessions and authentication state.

def session(self, auth: tuple = None) -> dict:
    """
    Get current session information.
    
    Parameters:
    - auth: Optional authentication tuple (username, password)
    
    Returns:
    Dictionary containing session details
    """

def kill_session(self) -> dict:
    """
    Destroy the current authenticated session.
    
    Returns:
    Response dictionary
    """

def kill_websudo(self) -> dict:
    """
    Destroy current WebSudo session (on-premise only).
    
    Returns:
    Response dictionary
    """

Usage examples:

# Get session information
session_info = jira.session()
print(f"Session Name: {session_info['name']}")
print(f"Login Info: {session_info['loginInfo']}")

# End current session
response = jira.kill_session()
print("Session terminated")

# Kill WebSudo session (on-premise only)
try:
    jira.kill_websudo()
    print("WebSudo session terminated")
except Exception as e:
    print(f"WebSudo not available or failed: {e}")

System Maintenance

Backup, restore, and reindexing operations for system maintenance.

def reindex(self, force: bool = False, background: bool = True) -> dict:
    """
    Start JIRA reindexing process.
    
    Parameters:
    - force: Force reindex even if already running
    - background: Run reindex in background
    
    Returns:
    Reindex response dictionary
    """

def backup(self, filename: str = 'backup.zip', attachments: bool = False) -> dict:
    """
    Create system backup (cloud only).
    
    Parameters:
    - filename: Backup file name
    - attachments: Include attachments in backup
    
    Returns:
    Backup response dictionary
    """

def backup_progress(self) -> dict:
    """
    Get backup progress status (cloud only).
    
    Returns:
    Dictionary containing backup progress information
    """

def backup_complete(self) -> bool:
    """
    Check if backup is complete (cloud only).
    
    Returns:
    True if backup is complete, False otherwise
    """

def backup_download(self, filename: str = None) -> None:
    """
    Download completed backup file (cloud only).
    
    Parameters:
    - filename: Local filename to save backup
    """

Usage examples:

# Start background reindex
reindex_result = jira.reindex(background=True)
print(f"Reindex started: {reindex_result}")

# Force immediate reindex (use carefully)
reindex_result = jira.reindex(force=True, background=False)
print("Forced reindex completed")

# Cloud backup operations
if jira.server_info().get('deploymentType') == 'Cloud':
    # Start backup
    backup_result = jira.backup(
        filename='daily_backup.zip',
        attachments=True
    )
    print(f"Backup started: {backup_result}")
    
    # Check progress
    import time
    while not jira.backup_complete():
        progress = jira.backup_progress()
        print(f"Backup progress: {progress.get('progress', 'Unknown')}%")
        time.sleep(30)
    
    # Download when complete
    jira.backup_download('local_backup.zip')
    print("Backup downloaded successfully")

Security & Permissions

Retrieve security levels and user permissions.

def security_level(self, id: str) -> dict:
    """
    Get security level details by ID.
    
    Parameters:
    - id: Security level ID
    
    Returns:
    Security level dictionary
    """

def my_permissions(
    self,
    projectKey: str = None,
    projectId: str = None,
    issueKey: str = None,
    issueId: str = None
) -> dict:
    """
    Get current user's permissions for project or issue.
    
    Parameters:
    - projectKey: Project key to check permissions for
    - projectId: Project ID to check permissions for
    - issueKey: Issue key to check permissions for  
    - issueId: Issue ID to check permissions for
    
    Returns:
    Dictionary of permissions with boolean values
    """

Usage examples:

# Get security level details
security_level = jira.security_level('10000')
print(f"Security Level: {security_level['name']}")
print(f"Description: {security_level['description']}")

# Check permissions for project
project_perms = jira.my_permissions(projectKey='PROJ')
print("Project permissions:")
for perm, has_perm in project_perms['permissions'].items():
    if has_perm:
        print(f"  ✓ {perm}")

# Check permissions for specific issue
issue_perms = jira.my_permissions(issueKey='PROJ-123')
print("Issue permissions:")
for perm, has_perm in issue_perms['permissions'].items():
    if has_perm:
        print(f"  ✓ {perm}")

# Check if user can create issues in project
can_create = project_perms['permissions'].get('CREATE_ISSUES', False)
print(f"Can create issues: {can_create}")

Universal Resource Finder

Generic method for accessing any JIRA REST resource.

def find(self, resource_format: str, ids: tuple = None) -> dict:
    """
    Universal resource locator for any REST resource in JIRA.
    
    Parameters:
    - resource_format: REST API resource path format
    - ids: Tuple of IDs to substitute in resource format
    
    Returns:
    Resource dictionary
    """

Usage examples:

# Access custom REST endpoints
custom_resource = jira.find('rest/api/2/customendpoint/{0}', ('12345',))

# Access plugin-specific endpoints
plugin_data = jira.find('rest/scriptrunner/latest/custom/getData')

# Access advanced configuration
config_data = jira.find('rest/api/2/configuration')

System Information Examples

Common system information retrieval patterns:

# Comprehensive system status check
def system_health_check(jira_client):
    """Perform basic system health check."""
    try:
        # Server info
        server_info = jira_client.server_info()
        print(f"✓ Server: {server_info['version']} (Build {server_info['buildNumber']})")
        
        # Current user
        user = jira_client.myself()
        print(f"✓ Authentication: {user.displayName}")
        
        # Session info
        session = jira_client.session()
        print(f"✓ Session: {session['name']}")
        
        # Basic permissions
        perms = jira_client.my_permissions()
        admin_perms = ['ADMINISTER', 'SYSTEM_ADMIN']
        is_admin = any(perms['permissions'].get(p, False) for p in admin_perms)
        print(f"✓ Admin permissions: {is_admin}")
        
        return True
    except Exception as e:
        print(f"✗ Health check failed: {e}")
        return False

# Run health check
health_check_passed = system_health_check(jira)

Maintenance Operations

System maintenance automation:

# Scheduled maintenance routine
def scheduled_maintenance(jira_client):
    """Perform scheduled maintenance tasks."""
    print("Starting scheduled maintenance...")
    
    # 1. Create backup (cloud only)
    try:
        backup_result = jira_client.backup(
            filename=f'scheduled_backup_{datetime.now().strftime("%Y%m%d")}.zip',
            attachments=False
        )
        print("✓ Backup initiated")
    except Exception as e:
        print(f"⚠ Backup skipped: {e}")
    
    # 2. Reindex if needed
    try:
        reindex_result = jira_client.reindex(background=True)
        print("✓ Reindex started")
    except Exception as e:
        print(f"⚠ Reindex failed: {e}")
    
    # 3. Check application properties
    try:
        props = jira_client.application_properties()
        important_props = ['jira.title', 'jira.baseurl']
        for prop in important_props:
            value = props.get(prop, 'Not set')
            print(f"✓ {prop}: {value}")
    except Exception as e:
        print(f"⚠ Property check failed: {e}")
    
    print("Maintenance routine completed")

# Run maintenance
scheduled_maintenance(jira)

Security Best Practices

When performing administrative operations:

# Always verify permissions before admin operations
def safe_admin_operation(jira_client, operation_func, *args, **kwargs):
    """Safely perform admin operation with permission check."""
    try:
        # Check if user has admin permissions
        perms = jira_client.my_permissions()
        is_admin = perms['permissions'].get('ADMINISTER', False)
        
        if not is_admin:
            raise PermissionError("Admin permissions required")
        
        # Perform operation
        result = operation_func(*args, **kwargs)
        print(f"✓ Admin operation completed successfully")
        return result
        
    except Exception as e:
        print(f"✗ Admin operation failed: {e}")
        raise

# Example usage
try:
    safe_admin_operation(
        jira,
        jira.set_application_property,
        'jira.title',
        'Updated Title'
    )
except Exception as e:
    print(f"Could not update property: {e}")

Install with Tessl CLI