API Reference

This section provides detailed API documentation for the jarkdown components.

Main Module

Jarkdown - Export Jira issues to markdown with attachments.

JiraApiClient

class jarkdown.jira_api_client.JiraApiClient(domain, email, api_token)

Bases: object

Handles all communication with the Jira Cloud REST API.

The JiraApiClient handles all communication with the Jira REST API.

Example usage:

from jarkdown.jira_api_client import JiraApiClient

client = JiraApiClient(
    domain="company.atlassian.net",
    email="user@company.com",
    api_token="your_token"
)

issue_data = client.get_issue("PROJ-123")

__init__(domain, email, api_token)

Initialize the Jira API client.

Parameters:

• domain – Jira domain (e.g., ‘company.atlassian.net’)

• email – User email for authentication

• api_token – API token for authentication

fetch_issue(issue_key)

Fetch issue data from Jira API.

Parameters:

issue_key – The Jira issue key (e.g., ‘PROJ-123’)

Returns:

Raw JSON response from Jira API

Return type:

dict

Raises:

• AuthenticationError – If authentication fails

• IssueNotFoundError – If issue is not found

• JiraApiError – For other API errors

get_attachment_content_url(attachment)

Get the download URL for an attachment.

Parameters:

attachment – Attachment metadata from Jira API

Returns:

The content URL for downloading the attachment

Return type:

str

download_attachment_stream(content_url)

Stream download an attachment.

Parameters:

content_url – The URL to download the attachment from

Returns:

Streaming response object

Return type:

requests.Response

Raises:

JiraApiError – If download fails

AttachmentHandler

class jarkdown.attachment_handler.AttachmentHandler(api_client)

Bases: object

Manages downloading and saving of issue attachments.

The AttachmentHandler manages downloading and saving attachments.

Example usage:

from jarkdown.attachment_handler import AttachmentHandler

handler = AttachmentHandler(auth_session, verbose=True)
downloaded = handler.download_attachments(
    attachments_data,
    output_dir="/path/to/output"
)

__init__(api_client)

Initialize the attachment handler.

Parameters:

api_client – JiraApiClient instance for API communication

download_attachment(attachment, output_dir)

Download a single attachment.

Parameters:

• attachment – Attachment metadata from Jira API

• output_dir – Directory to save the attachment to

Returns:

Information about the downloaded attachment including

filename, original_filename, mime_type, and path

Return type:

dict

Raises:

AttachmentDownloadError – If download fails

download_all_attachments(attachments, output_dir)

Download all attachments for an issue.

Parameters:

• attachments – List of attachment metadata from Jira API

• output_dir – Directory to save attachments to

Returns:

Information about all successfully downloaded attachments

Return type:

list

MarkdownConverter

class jarkdown.markdown_converter.MarkdownConverter(base_url, domain)

Bases: object

Converts Jira issue data into Markdown format.

The MarkdownConverter transforms Jira HTML content to clean Markdown.

Example usage:

from jarkdown.markdown_converter import MarkdownConverter

converter = MarkdownConverter()
markdown_content = converter.convert_issue(
    issue_data,
    attachment_mapping
)

__init__(base_url, domain)

Initialize the markdown converter.

Parameters:

• base_url – Base URL of the Jira instance (e.g., ‘https://company.atlassian.net’)

• domain – Jira domain (e.g., ‘company.atlassian.net’)

convert_html_to_markdown(html_content)

Convert HTML content to Markdown.

Parameters:

html_content – HTML string to convert

Returns:

Converted markdown content

Return type:

str

replace_attachment_links(markdown_content, downloaded_attachments)

Replace Jira attachment URLs with local file references.

Parameters:

• markdown_content – Markdown content with Jira attachment URLs

• downloaded_attachments – List of downloaded attachment info

Returns:

Markdown content with local file references

Return type:

str

compose_markdown(issue_data, downloaded_attachments)

Compose the final markdown file content.

Parameters:

• issue_data – Raw issue data from Jira API

• downloaded_attachments – List of downloaded attachment info

Returns:

Complete markdown content for the issue

Return type:

str

Exceptions

Custom exceptions for jarkdown.

Custom exceptions for error handling.

Exception Hierarchy:

JarkdownError
├── ConfigurationError
├── JiraApiError
│   ├── AuthenticationError
│   └── IssueNotFoundError
└── AttachmentDownloadError

Example usage:

from jarkdown.exceptions import AuthenticationError, IssueNotFoundError

try:
    issue = client.get_issue(issue_key)
except AuthenticationError:
    print("Invalid credentials")
except IssueNotFoundError:
    print(f"Issue {issue_key} not found")

exception jarkdown.exceptions.JarkdownError

Bases: Exception

Base exception for all jarkdown errors.

exception jarkdown.exceptions.JiraApiError(message, status_code=None, response=None)

Bases: JarkdownError

Raised when there’s an error communicating with the Jira API.

__init__(message, status_code=None, response=None)

exception jarkdown.exceptions.AuthenticationError(message, status_code=None, response=None)

Bases: JiraApiError

Raised when authentication with Jira fails.

exception jarkdown.exceptions.IssueNotFoundError(message, status_code=None, response=None)

Bases: JiraApiError

Raised when the requested issue is not found.

exception jarkdown.exceptions.AttachmentDownloadError(message, filename=None)

Bases: JarkdownError

Raised when there’s an error downloading an attachment.

__init__(message, filename=None)

exception jarkdown.exceptions.ConfigurationError

Bases: JarkdownError

Raised when there’s a configuration problem.