tessl/pypi-jira

Python library for interacting with JIRA via REST APIs.

—

Pending

Overview

Eval results

Files

Agile & Boards

Name: tessl/pypi-jira
Author: tessl

Agile/Scrum functionality including board management, sprint operations, and backlog management using the GreenHopper API. This enables automation of agile workflows and sprint planning.

Capabilities

Board Management

Operations for managing agile boards including creation, retrieval, and deletion.

def boards(
    self,
    startAt: int = 0,
    maxResults: int = 50,
    type: str = None,
    name: str = None
) -> list[Board]:
    """
    Get agile boards.
    
    Parameters:
    - startAt: Starting index for pagination
    - maxResults: Maximum number of results
    - type: Board type ('scrum', 'kanban', 'simple')
    - name: Board name filter
    
    Returns:
    List of Board objects
    """

def create_board(
    self,
    name: str,
    project_ids: list[str],
    preset: str = "scrum",
    location_type: str = 'user',
    location_id: str = None
) -> Board:
    """
    Create a new agile board.
    
    Parameters:
    - name: Board name
    - project_ids: List of project IDs or keys
    - preset: Board preset ('scrum', 'kanban', 'simple')
    - location_type: Location type ('user', 'project')
    - location_id: Location ID (user ID or project ID)
    
    Returns:
    Created Board object
    """

def delete_board(self, id: str) -> None:
    """
    Delete an agile board.
    
    Parameters:
    - id: Board ID
    """

Usage examples:

# Get all boards
boards = jira.boards()
for board in boards:
    print(f"Board: {board.name} (Type: {board.type})")

# Get boards by type
scrum_boards = jira.boards(type='scrum')
kanban_boards = jira.boards(type='kanban')

# Search boards by name
dev_boards = jira.boards(name='Development')

# Create new scrum board
new_board = jira.create_board(
    name='New Development Board',
    project_ids=['PROJ'],
    preset='scrum'
)
print(f"Created board: {new_board.name} (ID: {new_board.id})")

# Create kanban board
kanban_board = jira.create_board(
    name='Support Kanban',
    project_ids=['SUPPORT'],
    preset='kanban'
)

# Delete board
jira.delete_board(new_board.id)

Sprint Management

Operations for managing sprints including creation, updates, and sprint information.

def sprints(
    self,
    board_id: int,
    extended: bool = False,
    startAt: int = 0,
    maxResults: int = 50,
    state: str = None
) -> list[Sprint]:
    """
    Get sprints for a board.
    
    Parameters:
    - board_id: Board ID
    - extended: Include extended sprint information
    - startAt: Starting index for pagination
    - maxResults: Maximum number of results
    - state: Sprint state ('active', 'closed', 'future')
    
    Returns:
    List of Sprint objects
    """

def sprints_by_name(self, id: int, extended: bool = False) -> dict:
    """Get sprints organized by name."""

def sprint(self, id: int) -> Sprint:
    """
    Get sprint by ID.
    
    Parameters:
    - id: Sprint ID
    
    Returns:
    Sprint object
    """

def create_sprint(
    self,
    name: str,
    board_id: int,
    startDate: str = None,
    endDate: str = None
) -> Sprint:
    """
    Create a new sprint.
    
    Parameters:
    - name: Sprint name
    - board_id: Board ID where sprint will be created
    - startDate: Sprint start date (ISO format: YYYY-MM-DDTHH:MM:SS.sssZ)
    - endDate: Sprint end date (ISO format: YYYY-MM-DDTHH:MM:SS.sssZ)
    
    Returns:
    Created Sprint object
    """

def update_sprint(
    self,
    id: int,
    name: str = None,
    startDate: str = None,
    endDate: str = None,
    state: str = None
) -> Sprint:
    """
    Update a sprint.
    
    Parameters:
    - id: Sprint ID
    - name: New sprint name
    - startDate: New start date
    - endDate: New end date
    - state: New state ('active', 'closed', 'future')
    
    Returns:
    Updated Sprint object
    """

Usage examples:

# Get all sprints for a board
board_id = 123
sprints = jira.sprints(board_id)
for sprint in sprints:
    print(f"Sprint: {sprint.name} (State: {sprint.state})")

# Get active sprints only
active_sprints = jira.sprints(board_id, state='active')

# Get sprint with extended information
extended_sprints = jira.sprints(board_id, extended=True)
for sprint in extended_sprints:
    if hasattr(sprint, 'completeDate'):
        print(f"Completed: {sprint.completeDate}")

# Create new sprint
from datetime import datetime, timedelta

start_date = datetime.now()
end_date = start_date + timedelta(weeks=2)

new_sprint = jira.create_sprint(
    name='Sprint 15',
    board_id=board_id,
    startDate=start_date.isoformat() + 'Z',
    endDate=end_date.isoformat() + 'Z'
)
print(f"Created sprint: {new_sprint.name}")

# Update sprint
updated_sprint = jira.update_sprint(
    id=new_sprint.id,
    name='Sprint 15 - Feature Development',
    state='active'
)

# Get specific sprint
sprint = jira.sprint(new_sprint.id)
print(f"Sprint: {sprint.name}, Goal: {getattr(sprint, 'goal', 'No goal set')}")

Sprint Operations

Operations for managing issues within sprints and sprint lifecycle.

def add_issues_to_sprint(self, sprint_id: int, issue_keys: list[str]) -> None:
    """
    Add issues to a sprint.
    
    Parameters:
    - sprint_id: Sprint ID
    - issue_keys: List of issue keys to add
    """

def sprint_info(self, board_id: int, sprint_id: int) -> dict:
    """
    Get detailed sprint information.
    
    Parameters:
    - board_id: Board ID
    - sprint_id: Sprint ID
    
    Returns:
    Sprint information dictionary
    """

def incompletedIssuesEstimateSum(self, board_id: int, sprint_id: int) -> dict:
    """Get sum of estimates for incomplete issues in sprint."""

def removed_issues(self, board_id: int, sprint_id: int) -> dict:
    """Get issues removed from sprint."""

def removedIssuesEstimateSum(self, board_id: int, sprint_id: int) -> dict:
    """Get sum of estimates for issues removed from sprint."""

Usage examples:

# Add issues to sprint
issue_keys = ['PROJ-123', 'PROJ-124', 'PROJ-125']
jira.add_issues_to_sprint(sprint_id=456, issue_keys=issue_keys)
print(f"Added {len(issue_keys)} issues to sprint")

# Get detailed sprint information
sprint_info = jira.sprint_info(board_id=123, sprint_id=456)
print(f"Sprint capacity: {sprint_info.get('capacity', 'Not set')}")

# Get incomplete issues estimate
incomplete_estimate = jira.incompletedIssuesEstimateSum(123, 456)
print(f"Remaining work: {incomplete_estimate}")

# Get removed issues from sprint
removed = jira.removed_issues(123, 456)
print(f"Removed issues: {len(removed)}")

# Get estimate of removed issues
removed_estimate = jira.removedIssuesEstimateSum(123, 456)
print(f"Removed work estimate: {removed_estimate}")

Epic Management

Operations for managing epics and adding issues to epics.

def add_issues_to_epic(
    self,
    epic_id: str,
    issue_keys: list[str],
    ignore_epics: bool = True
) -> None:
    """
    Add issues to an epic.
    
    Parameters:
    - epic_id: Epic issue key or ID
    - issue_keys: List of issue keys to add to epic
    - ignore_epics: Whether to ignore if issue is already an epic
    """

Usage examples:

# Add issues to epic
epic_key = 'PROJ-100'  # Epic issue key
story_keys = ['PROJ-101', 'PROJ-102', 'PROJ-103']

jira.add_issues_to_epic(
    epic_id=epic_key,
    issue_keys=story_keys
)
print(f"Added {len(story_keys)} stories to epic {epic_key}")

# Create epic and add stories
epic = jira.create_issue(
    project={'key': 'PROJ'},
    summary='User Authentication Epic',
    issuetype={'name': 'Epic'},
    customfield_10011='AUTH'  # Epic Name field
)

# Create stories for the epic
stories = []
for i in range(3):
    story = jira.create_issue(
        project={'key': 'PROJ'},
        summary=f'Authentication Story {i+1}',
        issuetype={'name': 'Story'}
    )
    stories.append(story.key)

# Add stories to epic
jira.add_issues_to_epic(epic.key, stories)

Backlog Management

Operations for managing the product backlog and issue ranking.

def rank(self, issue: str, next_issue: str) -> None:
    """
    Rank an issue before another issue.
    
    Parameters:
    - issue: Issue key to rank
    - next_issue: Issue key to rank before
    """

def move_to_backlog(self, issue_keys: list[str]) -> None:
    """
    Move issues to backlog (remove from active sprints).
    
    Parameters:
    - issue_keys: List of issue keys to move to backlog
    """

Usage examples:

# Rank issue higher in backlog
jira.rank('PROJ-123', 'PROJ-124')  # Move PROJ-123 before PROJ-124
print("Ranked PROJ-123 higher in backlog")

# Move issues back to backlog
sprint_issues = ['PROJ-125', 'PROJ-126']
jira.move_to_backlog(sprint_issues)
print(f"Moved {len(sprint_issues)} issues back to backlog")

# Reorder backlog based on priority
high_priority_issues = jira.search_issues(
    'project = PROJ AND priority = High ORDER BY created ASC'
)

# Rank high priority issues at top
for i, issue in enumerate(high_priority_issues[:-1]):
    next_issue = high_priority_issues[i + 1]
    jira.rank(issue.key, next_issue.key)

Sprint States

Sprints can be in different states:

future: Sprint is created but not started
active: Sprint is currently in progress
closed: Sprint has been completed

# Filter sprints by state
future_sprints = jira.sprints(board_id, state='future')
active_sprints = jira.sprints(board_id, state='active')
closed_sprints = jira.sprints(board_id, state='closed')

# Start a sprint (change from future to active)
jira.update_sprint(
    id=future_sprint.id,
    state='active',
    startDate=datetime.now().isoformat() + 'Z'
)

# Complete a sprint (change from active to closed)
jira.update_sprint(
    id=active_sprint.id,
    state='closed',
    endDate=datetime.now().isoformat() + 'Z'
)

Board Types

Different board types support different workflows:

Scrum Boards

Support sprints and sprint planning
Include backlog management
Support velocity tracking

Kanban Boards

Continuous flow without sprints
Support WIP limits
Focus on cycle time

Simple Boards

Basic board functionality
Limited agile features

# Create different board types
scrum_board = jira.create_board(
    name='Development Scrum',
    project_ids=['DEV'],
    preset='scrum'
)

kanban_board = jira.create_board(
    name='Support Kanban',
    project_ids=['SUPPORT'],
    preset='kanban'
)

simple_board = jira.create_board(
    name='Simple Task Board',
    project_ids=['TASKS'],
    preset='simple'
)

Sprint Planning Automation

Automate common sprint planning tasks:

def plan_next_sprint(board_id, sprint_name, duration_weeks=2):
    """Automate sprint planning process."""
    
    # Create new sprint
    start_date = datetime.now()
    end_date = start_date + timedelta(weeks=duration_weeks)
    
    sprint = jira.create_sprint(
        name=sprint_name,
        board_id=board_id,
        startDate=start_date.isoformat() + 'Z',
        endDate=end_date.isoformat() + 'Z'
    )
    
    # Get high priority backlog items
    backlog_items = jira.search_issues(
        f'project = PROJ AND sprint is EMPTY AND priority in (Highest, High) '
        f'ORDER BY priority DESC, created ASC',
        maxResults=20
    )
    
    # Add top items to sprint
    issue_keys = [issue.key for issue in backlog_items[:10]]
    if issue_keys:
        jira.add_issues_to_sprint(sprint.id, issue_keys)
    
    print(f"Created sprint '{sprint_name}' with {len(issue_keys)} issues")
    return sprint

# Plan next sprint
next_sprint = plan_next_sprint(123, 'Sprint 16', duration_weeks=2)

Install with Tessl CLI