Repository API

The repository layer handles all database operations for IssueDB.

IssueRepository

class issuedb.repository.IssueRepository(db_path: str | None = None)[source]

Handles all issue-related database operations.

Parameters:: db_path – Optional path to database file. If None, uses ./issuedb.sqlite

Example:

from issuedb.repository import IssueRepository

# Use default database
repo = IssueRepository()

# Use custom database
repo = IssueRepository("/path/to/custom.db")

Issue Operations

IssueRepository.create_issue(issue: Issue) → Issue[source]

Create a new issue.

Parameters:: issue – Issue object to create (id should be None)
Returns:: Created issue with id populated
Raises:: ValueError – If title is missing

Example:

from issuedb.models import Issue, Priority

issue = Issue(
    title="Fix bug",
    description="Detailed description",
    priority=Priority.HIGH,
    due_date=datetime(2025, 12, 31)
)
created = repo.create_issue(issue)
print(f"Created issue #{created.id}")

IssueRepository.get_issue(issue_id: int) → Issue | None[source]

Get an issue by ID.

Parameters:: issue_id – Issue ID
Returns:: Issue object or None if not found

Example:

issue = repo.get_issue(1)
if issue:
    print(f"Found: {issue.title}")
else:
    print("Issue not found")

IssueRepository.update_issue(issue_id: int, **updates) → Issue | None[source]

Update an issue.

Parameters:

issue_id – Issue ID
updates – Field updates (title, description, priority, status, due_date)

Returns:

Updated issue or None if not found

Raises:

ValueError – If invalid field name provided

Example:

updated = repo.update_issue(1,
    status="in-progress",
    priority="high",
    due_date="2025-01-01"
)

IssueRepository.delete_issue(issue_id: int) → bool[source]

Delete an issue. Preserves audit trail.

Parameters:: issue_id – Issue ID
Returns:: True if deleted, False if not found

Example:

if repo.delete_issue(1):
    print("Issue deleted")
else:
    print("Issue not found")

List issues with optional filters.

Parameters:

status – Filter by status
priority – Filter by priority
limit – Maximum number of results
offset – Number of results to skip
due_date – Filter by due date (exact match)
tag – Filter by tag name

Returns:

List of issues

Example:

# All open issues
open_issues = repo.list_issues(status="open")

# High priority issues, first 10
urgent = repo.list_issues(priority="high", limit=10)

# Issues with 'bug' tag
bugs = repo.list_issues(tag="bug")

Memory Operations

IssueRepository.add_memory(key: str, value: str, category: str = 'general') → Memory[source]

Add a memory item.

Parameters:

key – Unique key
value – Content
category – Category

Returns:

Created Memory object

IssueRepository.get_memory(key: str) → Memory | None[source]

Get a memory item by key.

Parameters:: key – Key to search for
Returns:: Memory object or None

IssueRepository.list_memory(category: str | None = None, search: str | None = None) → List[Memory][source]

List memory items.

Parameters:

category – Filter by category
search – Search in key or value

Returns:

List of Memory objects

IssueRepository.update_memory(key: str, value: str | None = None, category: str | None = None) → Memory | None[source]

Update a memory item.

Parameters:

key – Key of item to update
value – New value
category – New category

Returns:

Updated Memory object or None

IssueRepository.delete_memory(key: str) → bool[source]

Delete a memory item.

Parameters:: key – Key of item to delete
Returns:: True if deleted

Lessons Learned

IssueRepository.add_lesson(lesson: str, issue_id: int | None = None, category: str = 'general') → LessonLearned[source]

Add a lesson learned.

Parameters:

lesson – Lesson text
issue_id – Related issue ID
category – Category

Returns:

Created LessonLearned object

IssueRepository.list_lessons(issue_id: int | None = None, category: str | None = None) → List[LessonLearned][source]

List lessons learned.

Parameters:

issue_id – Filter by related issue
category – Filter by category

Returns:

List of LessonLearned objects

Tag Operations

IssueRepository.create_tag(name: str, color: str | None = None) → Tag[source]

Create a new tag.

Parameters:

name – Tag name
color – Optional color code

Returns:

Created Tag object

IssueRepository.list_tags() → List[Tag][source]

List all tags.

Returns:: List of Tag objects

IssueRepository.add_issue_tag(issue_id: int, tag_name: str) → bool[source]

Add a tag to an issue.

Parameters:

issue_id – Issue ID
tag_name – Tag name

Returns:

True if added, False if already exists

IssueRepository.remove_issue_tag(issue_id: int, tag_name: str) → bool[source]

Remove a tag from an issue.

Parameters:

issue_id – Issue ID
tag_name – Tag name

Returns:

True if removed

IssueRepository.get_issue_tags(issue_id: int) → List[Tag][source]

Get tags for an issue.

Parameters:: issue_id – Issue ID
Returns:: List of Tag objects

Link Operations

IssueRepository.link_issues(source_id: int, target_id: int, relation_type: str) → IssueRelation[source]

Link two issues.

Parameters:

source_id – Source issue ID
target_id – Target issue ID
relation_type – Relationship type

Returns:

Created IssueRelation object

IssueRepository.unlink_issues(source_id: int, target_id: int, relation_type: str | None = None) → bool[source]

Unlink issues.

Parameters:

source_id – Source issue ID
target_id – Target issue ID
relation_type – Optional type filter

Returns:

True if removed

IssueRepository.get_issue_relations(issue_id: int) → Dict[str, List[dict]][source]

Get all relations for an issue.

Parameters:: issue_id – Issue ID
Returns:: Dictionary with ‘source’ and ‘target’ lists

Comment Operations

IssueRepository.add_comment(issue_id: int, text: str) → Comment[source]

Add a comment to an issue.

Parameters:

issue_id – Issue ID
text – Comment text

Returns:

Created comment

Raises:

ValueError – If issue not found or text is empty

Example:

comment = repo.add_comment(1, "Started working on this")
print(f"Comment #{comment.id} added")

IssueRepository.get_comments(issue_id: int) → List[Comment][source]

Get all comments for an issue.

Parameters:: issue_id – Issue ID
Returns:: List of comments, ordered chronologically

Example:

comments = repo.get_comments(1)
for c in comments:
    print(f"[{c.created_at}] {c.text}")

IssueRepository.delete_comment(comment_id: int) → bool[source]

Delete a comment.

Parameters:: comment_id – Comment ID
Returns:: True if deleted, False if not found

Bulk Operations

IssueRepository.bulk_create_issues(issues_data: List[dict]) → List[Issue][source]

Bulk create multiple issues from dictionaries.

Parameters:: issues_data – List of issue dictionaries
Returns:: List of created issues
Raises:: ValueError – If any issue data is invalid

Example:

issues_data = [
    {"title": "Issue 1", "priority": "high"},
    {"title": "Issue 2", "priority": "medium"},
]
created = repo.bulk_create_issues(issues_data)

IssueRepository.bulk_update_issues(filter_status: str | None = None, filter_priority: str | None = None, new_status: str | None = None, new_priority: str | None = None) → int[source]

Bulk update issues matching filters.

Parameters:

filter_status – Filter by current status
filter_priority – Filter by current priority
new_status – New status to set
new_priority – New priority to set

Returns:

Number of issues updated

Example:

# Close all open issues
count = repo.bulk_update_issues(
    filter_status="open",
    new_status="closed"
)
print(f"Closed {count} issues")

IssueRepository.bulk_update_issues_from_json(updates_data: List[dict]) → List[Issue][source]

Bulk update specific issues from dictionaries.

Parameters:: updates_data – List of dicts with ‘id’ and fields to update
Returns:: List of updated issues
Raises:: ValueError – If any update fails

Example:

updates = [
    {"id": 1, "status": "closed"},
    {"id": 2, "priority": "high"},
]
updated = repo.bulk_update_issues_from_json(updates)

IssueRepository.bulk_close_issues(issue_ids: List[int]) → List[Issue][source]

Bulk close multiple issues.

Parameters:: issue_ids – List of issue IDs to close
Returns:: List of closed issues
Raises:: ValueError – If any issue not found

Example:

closed = repo.bulk_close_issues([1, 2, 3])

Reporting

IssueRepository.get_summary() → dict[source]

Get aggregate statistics.

Returns:: Dictionary with totals and breakdowns

Example:

summary = repo.get_summary()
print(f"Total: {summary['total_issues']}")
print(f"Open: {summary['by_status']['open']['count']}")

IssueRepository.get_report(group_by: str = 'status') → dict[source]

Get detailed report grouped by status or priority.

Parameters:: group_by – “status” or “priority”
Returns:: Dictionary with grouped issues
Raises:: ValueError – If invalid group_by value

Audit Operations

IssueRepository.get_audit_logs(issue_id: int | None = None) → List[AuditLog][source]

Get audit logs.

Parameters:: issue_id – Optional filter by issue ID
Returns:: List of audit log entries

Administrative

IssueRepository.clear_all_issues() → int[source]

Delete all issues. Preserves audit logs.

Returns:: Number of deleted issues

Complete Example

from issuedb.repository import IssueRepository
from issuedb.models import Issue, Priority, Status

# Initialize repository
repo = IssueRepository("./my-project.db")

# Create issues
issue1 = repo.create_issue(Issue(
    title="Implement login",
    priority=Priority.HIGH
))
issue2 = repo.create_issue(Issue(
    title="Add tests",
    priority=Priority.MEDIUM
))

# Add comments
repo.add_comment(issue1.id, "Started implementation")

# Update status
repo.update_issue(issue1.id, status="in-progress")

# Get next issue
next_issue = repo.get_next_issue()
print(f"Next: {next_issue.title}")

# Search
results = repo.search_issues("login")

# Get summary
summary = repo.get_summary()
print(f"Total issues: {summary['total_issues']}")

# Bulk close
repo.bulk_close_issues([issue1.id, issue2.id])