tessl/pypi-jira

Python library for interacting with JIRA via REST APIs.

—

Pending

Overview

Eval results

Files

Comments & Attachments

Name: tessl/pypi-jira
Author: tessl

Comment management and file attachment operations for issues. This includes adding, updating, and retrieving comments, as well as managing file attachments with support for various file types.

Capabilities

Comment Management

Operations for managing issue comments including creation, retrieval, and updates.

def comments(self, issue: Issue) -> list[Comment]:
    """
    Get all comments for an issue.
    
    Parameters:
    - issue: Issue object or issue key
    
    Returns:
    List of Comment objects
    """

def comment(self, issue: Issue, comment: str) -> Comment:
    """
    Get a specific comment by ID.
    
    Parameters:
    - issue: Issue object or issue key
    - comment: Comment ID
    
    Returns:
    Comment object
    """

def add_comment(
    self,
    issue: Issue,
    body: str,
    visibility: dict = None,
    is_internal: bool = False
) -> Comment:
    """
    Add a comment to an issue.
    
    Parameters:
    - issue: Issue object or issue key
    - body: Comment text content
    - visibility: Visibility restrictions (role or group based)
    - is_internal: Mark comment as internal (Service Desk)
    
    Returns:
    Created Comment object
    """

Usage examples:

# Get all comments for an issue
issue = jira.issue('PROJ-123')
comments = jira.comments(issue)
for comment in comments:
    print(f"Author: {comment.author.displayName}")
    print(f"Created: {comment.created}")
    print(f"Body: {comment.body}")
    print("---")

# Add a simple comment
new_comment = jira.add_comment(
    issue='PROJ-123',
    body='This is a comment added via the API'
)
print(f"Added comment: {new_comment.id}")

# Add comment with visibility restrictions
restricted_comment = jira.add_comment(
    issue='PROJ-123',
    body='This comment is only visible to developers',
    visibility={
        'type': 'group',
        'value': 'developers'
    }
)

# Add internal comment (Service Desk)
internal_comment = jira.add_comment(
    issue='SD-456',
    body='Internal note for agents only',
    is_internal=True
)

# Get specific comment
comment = jira.comment('PROJ-123', new_comment.id)
print(f"Comment body: {comment.body}")

Comment Updates

Comments can be updated through the Comment resource object:

# Update a comment
comment = jira.comment('PROJ-123', '12345')
comment.update(body='Updated comment text')

# Update comment with visibility
comment.update(
    body='Updated restricted comment',
    visibility={
        'type': 'role',
        'value': 'Administrators'
    }
)

Attachment Management

Operations for managing file attachments on issues.

def attachment(self, id: str) -> Attachment:
    """
    Get attachment by ID.
    
    Parameters:
    - id: Attachment ID
    
    Returns:
    Attachment object
    """

def attachment_meta(self) -> dict:
    """
    Get attachment metadata including size limits and enabled status.
    
    Returns:
    Attachment metadata dictionary
    """

def add_attachment(self, issue: Issue, attachment: str, filename: str = None) -> Attachment:
    """
    Add an attachment to an issue.
    
    Parameters:
    - issue: Issue object or issue key
    - attachment: File path or file-like object
    - filename: Custom filename (optional)
    
    Returns:
    Created Attachment object
    """

def delete_attachment(self, id: str) -> None:
    """
    Delete an attachment.
    
    Parameters:
    - id: Attachment ID
    """

Usage examples:

# Get attachment metadata
meta = jira.attachment_meta()
print(f"Attachments enabled: {meta['enabled']}")
print(f"Upload limit: {meta['uploadLimit']} bytes")

# Add file attachment
with open('document.pdf', 'rb') as f:
    attachment = jira.add_attachment(
        issue='PROJ-123',
        attachment=f,
        filename='requirements_document.pdf'
    )
print(f"Uploaded attachment: {attachment.filename}")

# Add multiple attachments
files_to_upload = ['screenshot.png', 'log.txt', 'report.xlsx']
for file_path in files_to_upload:
    with open(file_path, 'rb') as f:
        attachment = jira.add_attachment('PROJ-123', f)
        print(f"Uploaded: {attachment.filename}")

# Get attachment details
attachment = jira.attachment(attachment.id)
print(f"Filename: {attachment.filename}")
print(f"Size: {attachment.size} bytes")
print(f"MIME Type: {attachment.mimeType}")
print(f"Author: {attachment.author.displayName}")
print(f"Created: {attachment.created}")

# Delete attachment
jira.delete_attachment(attachment.id)

Attachment Content Access

Retrieve attachment file content for processing or download.

# Get attachment content as string (for text files)
attachment = jira.attachment('12345')
content = attachment.get()
print(content)

# Stream attachment content (for large files)
attachment = jira.attachment('12345')
with open(f'downloaded_{attachment.filename}', 'wb') as f:
    for chunk in attachment.iter_content(chunk_size=8192):
        f.write(chunk)
print(f"Downloaded: {attachment.filename}")

# Process image attachment
import io
from PIL import Image

attachment = jira.attachment('image_attachment_id')
if attachment.mimeType.startswith('image/'):
    image_data = io.BytesIO()
    for chunk in attachment.iter_content():
        image_data.write(chunk)
    image_data.seek(0)
    
    image = Image.open(image_data)
    print(f"Image size: {image.size}")
    print(f"Image mode: {image.mode}")

Remote Links

Manage remote links that connect issues to external resources.

def remote_links(self, issue: Issue) -> list[dict]:
    """Get all remote links for an issue."""

def remote_link(self, issue: Issue, id: str) -> dict:
    """Get a specific remote link by ID."""

def add_remote_link(
    self,
    issue: Issue,
    destination: str,
    globalId: str = None,
    application: dict = None,
    relationship: str = None
) -> dict:
    """
    Add a remote link to an issue.
    
    Parameters:
    - issue: Issue object or issue key
    - destination: URL or destination object
    - globalId: Global ID for the link
    - application: Application information dictionary
    - relationship: Relationship type
    
    Returns:
    Created remote link dictionary
    """

def add_simple_link(self, issue: Issue, object: dict) -> dict:
    """
    Add a simple remote link to an issue.
    
    Parameters:
    - issue: Issue object or issue key
    - object: Link object with URL and title
    
    Returns:
    Created remote link dictionary
    """

Usage examples:

# Get all remote links for an issue
links = jira.remote_links('PROJ-123')
for link in links:
    print(f"Title: {link['object']['title']}")
    print(f"URL: {link['object']['url']}")

# Add simple remote link
simple_link = jira.add_simple_link(
    issue='PROJ-123',
    object={
        'url': 'https://example.com/related-doc',
        'title': 'Related Documentation'
    }
)

# Add remote link with application info
app_link = jira.add_remote_link(
    issue='PROJ-123',
    destination='https://github.com/company/repo/pull/123',
    application={
        'type': 'com.atlassian.jira.plugins.github',
        'name': 'GitHub'
    },
    relationship='implements'
)

# Get specific remote link
link = jira.remote_link('PROJ-123', simple_link['id'])
print(f"Link: {link['object']['title']} -> {link['object']['url']}")

Comment Visibility Options

Control who can see comments using visibility restrictions:

Group-based Visibility

# Restrict to specific group
jira.add_comment(
    issue='PROJ-123',
    body='Visible only to developers',
    visibility={
        'type': 'group',
        'value': 'developers'
    }
)

Role-based Visibility

# Restrict to project role
jira.add_comment(
    issue='PROJ-123',
    body='Visible only to administrators',
    visibility={
        'type': 'role',
        'value': 'Administrators'
    }
)

Attachment File Types

The library supports all file types that JIRA allows. Common examples:

# Document files
jira.add_attachment('PROJ-123', open('document.pdf', 'rb'))
jira.add_attachment('PROJ-123', open('spreadsheet.xlsx', 'rb'))
jira.add_attachment('PROJ-123', open('presentation.pptx', 'rb'))

# Image files
jira.add_attachment('PROJ-123', open('screenshot.png', 'rb'))
jira.add_attachment('PROJ-123', open('diagram.jpg', 'rb'))

# Code files
jira.add_attachment('PROJ-123', open('script.py', 'rb'))
jira.add_attachment('PROJ-123', open('config.json', 'rb'))

# Archive files
jira.add_attachment('PROJ-123', open('logs.zip', 'rb'))
jira.add_attachment('PROJ-123', open('backup.tar.gz', 'rb'))

Bulk Operations

Handle multiple comments or attachments efficiently:

# Add multiple comments
comments_to_add = [
    'First comment',
    'Second comment with visibility',
    'Third comment'
]

for i, comment_text in enumerate(comments_to_add):
    visibility = None
    if i == 1:  # Second comment restricted
        visibility = {'type': 'group', 'value': 'developers'}
    
    jira.add_comment('PROJ-123', comment_text, visibility=visibility)

# Upload multiple related files
import os
log_dir = '/path/to/logs'
for filename in os.listdir(log_dir):
    if filename.endswith('.log'):
        with open(os.path.join(log_dir, filename), 'rb') as f:
            jira.add_attachment('PROJ-123', f, filename=filename)

Error Handling

Handle common attachment and comment errors:

from jira import JIRAError

try:
    # Attempt to add large attachment
    with open('very_large_file.zip', 'rb') as f:
        attachment = jira.add_attachment('PROJ-123', f)
except JIRAError as e:
    if e.status_code == 413:
        print("File too large for upload")
    elif e.status_code == 403:
        print("No permission to add attachments")
    else:
        print(f"Upload failed: {e.text}")

try:
    # Attempt to add comment with invalid visibility
    jira.add_comment(
        'PROJ-123',
        'Test comment',
        visibility={'type': 'group', 'value': 'nonexistent-group'}
    )
except JIRAError as e:
    print(f"Comment creation failed: {e.text}")

Install with Tessl CLI