tessl/pypi-jira

Python library for interacting with JIRA via REST APIs.

—

Pending

Overview

Eval results

Files

Project & Component Management

Name: tessl/pypi-jira
Author: tessl

Project administration including project creation, component management, version control, role assignment, and avatar management. These operations require appropriate administrative permissions in JIRA.

Capabilities

Project Operations

Core project management functions for creating, retrieving, and managing JIRA projects.

def projects(self) -> list[Project]:
    """Get all visible projects for the current user."""

def project(self, id: str) -> Project:
    """
    Get a specific project by ID or key.
    
    Parameters:
    - id: Project ID or key
    
    Returns:
    Project object
    """

def create_project(
    self,
    key: str,
    name: str = None,
    assignee: str = None,
    type: str = "Software",
    template_name: str = None
) -> Project:
    """
    Create a new project.
    
    Parameters:
    - key: Project key (must be unique)
    - name: Project name (defaults to key if not provided)
    - assignee: Default assignee username
    - type: Project type (Software, Business, Service Desk)
    - template_name: Template to use for project creation
    
    Returns:
    Created Project object
    """

def delete_project(self, pid: str) -> None:
    """
    Delete a project.
    
    Parameters:
    - pid: Project ID or key
    """

Usage examples:

# Get all projects
projects = jira.projects()
for project in projects:
    print(f"{project.key}: {project.name}")

# Get specific project
project = jira.project('MYPROJ')
print(f"Project: {project.name}")
print(f"Lead: {project.lead.displayName}")
print(f"Description: {project.description}")

# Create new project
new_project = jira.create_project(
    key='NEWPROJ',
    name='New Project',
    assignee='john.doe',
    type='Software'
)
print(f"Created project: {new_project.key}")

# Delete project (use with caution!)
jira.delete_project('OLDPROJ')

Component Management

Manage project components for organizing issues within projects.

def project_components(self, project: str) -> list[dict]:
    """Get all components for a project."""

def component(self, id: str) -> dict:
    """Get component by ID."""

def create_component(
    self,
    name: str,
    project: str,
    description: str = None,
    leadUserName: str = None,
    assigneeType: str = None,
    isAssigneeTypeValid: bool = False
) -> dict:
    """
    Create a project component.
    
    Parameters:
    - name: Component name
    - project: Project key or ID
    - description: Component description
    - leadUserName: Component lead username
    - assigneeType: How issues are assigned (PROJECT_DEFAULT, COMPONENT_LEAD, etc.)
    - isAssigneeTypeValid: Whether assignee type is valid
    
    Returns:
    Created component dictionary
    """

def component_count_related_issues(self, id: str) -> int:
    """Get count of issues related to a component."""

def delete_component(self, id: str) -> None:
    """Delete a component."""

Usage examples:

# Get project components
components = jira.project_components('PROJ')
for component in components:
    print(f"{component['name']}: {component['description']}")

# Create new component
new_component = jira.create_component(
    name='Frontend',
    project='PROJ',
    description='Frontend user interface components',
    leadUserName='jane.smith',
    assigneeType='COMPONENT_LEAD'
)

# Get component details
component = jira.component(new_component['id'])
issue_count = jira.component_count_related_issues(component['id'])
print(f"Component has {issue_count} related issues")

# Delete component
jira.delete_component(component['id'])

Version Management

Manage project versions for release planning and tracking.

def project_versions(self, project: str) -> list[dict]:
    """Get all versions for a project."""

def version(self, id: str, expand: str = None) -> dict:
    """Get version by ID."""

def create_version(
    self,
    name: str,
    project: str,
    description: str = None,
    releaseDate: str = None,
    startDate: str = None,
    archived: bool = False,
    released: bool = False
) -> dict:
    """
    Create a project version.
    
    Parameters:
    - name: Version name
    - project: Project key or ID
    - description: Version description
    - releaseDate: Release date (YYYY-MM-DD format)
    - startDate: Start date (YYYY-MM-DD format)
    - archived: Whether version is archived
    - released: Whether version is released
    
    Returns:
    Created version dictionary
    """

def move_version(self, id: str, after: str = None, position: str = None) -> dict:
    """Move a version in the version list."""

def version_count_related_issues(self, id: str) -> int:
    """Count issues related to a version."""

def version_count_unresolved_issues(self, id: str) -> int:
    """Count unresolved issues for a version."""

Usage examples:

# Get project versions
versions = jira.project_versions('PROJ')
for version in versions:
    print(f"{version['name']}: Released={version['released']}")

# Create new version
new_version = jira.create_version(
    name='v2.1.0',
    project='PROJ',
    description='Minor feature release',
    releaseDate='2024-03-15'
)

# Get version details with issue counts
version = jira.version(new_version['id'])
total_issues = jira.version_count_related_issues(version['id'])
unresolved_issues = jira.version_count_unresolved_issues(version['id'])
print(f"Version {version['name']}: {unresolved_issues}/{total_issues} unresolved")

# Move version in list
jira.move_version(version['id'], position='First')

Project Roles & Permissions

Manage project roles and user assignments.

def project_roles(self, project: str) -> dict:
    """Get all roles for a project."""

def project_role(self, project: str, id: str) -> dict:
    """Get specific project role."""

def my_permissions(
    self,
    projectKey: str = None,
    projectId: str = None,
    issueKey: str = None,
    issueId: str = None
) -> dict:
    """
    Get current user's permissions.
    
    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:
    Permissions dictionary
    """

Usage examples:

# Get project roles
roles = jira.project_roles('PROJ')
for role_name, role_url in roles.items():
    print(f"Role: {role_name}")

# Get specific role details
developer_role = jira.project_role('PROJ', '10000')
print(f"Developers: {[user['displayName'] for user in developer_role['actors']]}")

# Check permissions
permissions = jira.my_permissions(projectKey='PROJ')
if permissions['permissions']['CREATE_ISSUES']['havePermission']:
    print("Can create issues in this project")

Project Avatars

Manage project avatar images.

def project_avatars(self, project: str) -> dict:
    """Get available avatars for a project."""

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

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

def set_project_avatar(self, project: str, avatar: str) -> None:
    """Set project avatar."""

def delete_project_avatar(self, project: str, avatar: str) -> None:
    """Delete project avatar."""

Usage examples:

# Get project avatars
avatars = jira.project_avatars('PROJ')
print(f"Available avatars: {len(avatars['system']) + len(avatars['custom'])}")

# Upload and set new avatar
with open('project_logo.png', 'rb') as avatar_file:
    temp_avatar = jira.create_temp_project_avatar(
        project='PROJ',
        filename='project_logo.png',
        size=avatar_file.tell(),
        avatar_img=avatar_file,
        contentType='image/png'
    )

# Confirm avatar with cropping
cropping = {
    'cropperOffsetX': 0,
    'cropperOffsetY': 0,
    'cropperWidth': 120,
    'cropperHeight': 120
}
confirmed_avatar = jira.confirm_project_avatar('PROJ', cropping)

Project Types

Common project types available in JIRA:

Software: For software development projects with agile features
Business: For general business projects and task management
Service Desk: For IT service management and customer support

Component Assignee Types

Available assignee types for components:

PROJECT_DEFAULT: Use project default assignee
COMPONENT_LEAD: Assign to component lead
PROJECT_LEAD: Assign to project lead
UNASSIGNED: Leave unassigned

Permission Examples

Common permissions you can check:

permissions = jira.my_permissions(projectKey='PROJ')

# Check specific permissions
can_create = permissions['permissions']['CREATE_ISSUES']['havePermission']
can_delete = permissions['permissions']['DELETE_ISSUES']['havePermission']
can_admin = permissions['permissions']['ADMINISTER_PROJECTS']['havePermission']

print(f"Create: {can_create}, Delete: {can_delete}, Admin: {can_admin}")

Install with Tessl CLI