Issues & Pull Request Management

def issue(self, username, repository, number):
    """
    Fetch a specific issue from a repository.
    
    Parameters:
    - username (str, required): Repository owner
    - repository (str, required): Repository name
    - number (int, required): Issue number
    
    Returns:
    Issue object with full details or None if not found
    """

def issues(self, filter="", state="", labels="", sort="", direction="", since=None, number=-1, etag=None):
    """
    List all issues for the authenticated user across organizations.
    
    Parameters:
    - filter (str, optional): 'assigned', 'created', 'mentioned', 'subscribed'
    - state (str, optional): 'all', 'open', 'closed'
    - labels (str, optional): Comma-separated label names
    - sort (str, optional): 'created', 'updated', 'comments'
    - direction (str, optional): 'asc', 'desc'
    - since (datetime/str, optional): Only issues after this date
    - number (int): Number to return (-1 for all)
    - etag (str, optional): ETag from previous request
    
    Returns:
    Generator of ShortIssue objects
    """

def issues_on(self, username, repository, milestone=None, state=None, assignee=None, mentioned=None, labels=None, sort=None, direction=None, since=None, number=-1, etag=None):
    """
    List issues on a specific repository.
    
    Parameters:
    - username (str, required): Repository owner
    - repository (str, required): Repository name
    - milestone (int/str, optional): Milestone ID, '*' for any, None for no milestone
    - state (str, optional): 'all', 'open', 'closed'
    - assignee (str, optional): Username or '*' for any assignee
    - mentioned (str, optional): Username mentioned in issue
    - labels (str, optional): Comma-separated label names
    - sort (str, optional): 'created', 'updated', 'comments'
    - direction (str, optional): 'asc', 'desc'
    - since (datetime/str, optional): Only issues after this date
    - number (int): Number to return (-1 for all)
    - etag (str, optional): ETag from previous request
    
    Returns:
    Generator of ShortIssue objects
    """

def user_issues(self, filter="", state="", labels="", sort="", direction="", since=None, per_page=None, number=-1, etag=None):
    """
    List only the authenticated user's own issues (not organization issues).
    
    Parameters:
    - filter (str, optional): 'assigned', 'created', 'mentioned', 'subscribed'
    - state (str, optional): 'all', 'open', 'closed'
    - labels (str, optional): Comma-separated label names
    - sort (str, optional): 'created', 'updated', 'comments'
    - direction (str, optional): 'asc', 'desc'
    - since (datetime/str, optional): Only issues after this date
    - per_page (int, optional): Results per page
    - number (int): Number to return (-1 for all)
    - etag (str, optional): ETag from previous request
    
    Returns:
    Generator of ShortIssue objects
    """

# Get specific issue
issue = gh.issue('octocat', 'Hello-World', 1)
print(f"Issue #{issue.number}: {issue.title}")
print(f"State: {issue.state}")
print(f"Author: {issue.user.login}")

# List all your issues
for issue in gh.issues(filter='assigned', state='open'):
    print(f"{issue.repository.full_name}#{issue.number}: {issue.title}")

# List repository issues with filters
for issue in gh.issues_on('owner', 'repo', state='open', labels='bug,priority-high'):
    print(f"Bug #{issue.number}: {issue.title}")

# List your own issues only
for issue in gh.user_issues(filter='created', sort='updated'):
    print(f"Created issue: {issue.title}")

def create_issue(self, owner, repository, title, body=None, assignee=None, milestone=None, labels=[], assignees=None):
    """
    Create an issue on a repository.
    
    Parameters:
    - owner (str, required): Repository owner
    - repository (str, required): Repository name
    - title (str, required): Issue title
    - body (str, optional): Issue description in Markdown
    - assignee (str, optional): Username to assign (legacy, use assignees)
    - milestone (int, optional): Milestone ID number
    - labels (list, optional): List of label names
    - assignees (list, optional): List of usernames to assign
    
    Returns:
    ShortIssue object for the created issue
    """

# Create simple issue
issue = gh.create_issue('owner', 'repo', 'Bug in login function')

# Create detailed issue
issue = gh.create_issue(
    owner='owner',
    repository='repo',
    title='Add user authentication',
    body='''## Description
We need to implement user authentication with the following features:

- [ ] Login form
- [ ] Password validation
- [ ] Session management

## Acceptance Criteria
- Users can log in with email/password
- Sessions expire after 24 hours
- Invalid credentials show error message
''',
    assignees=['developer1', 'developer2'],
    labels=['enhancement', 'priority-medium'],
    milestone=5
)

print(f"Created issue #{issue.number}: {issue.html_url}")

def pull_request(self, owner, repository, number):
    """
    Fetch a specific pull request from a repository.
    
    Parameters:
    - owner (str, required): Repository owner
    - repository (str, required): Repository name
    - number (int, required): Pull request number
    
    Returns:
    PullRequest object with full details or None if not found
    """

# Get specific pull request
pr = gh.pull_request('owner', 'repo', 42)
print(f"PR #{pr.number}: {pr.title}")
print(f"State: {pr.state}")
print(f"Author: {pr.user.login}")
print(f"Base: {pr.base.ref} <- Head: {pr.head.ref}")
print(f"Mergeable: {pr.mergeable}")

# Check PR review status
if pr.merged:
    print(f"Merged at: {pr.merged_at}")
else:
    print(f"Comments: {pr.review_comments}")
    print(f"Commits: {pr.commits}")

def organization_issues(self, name, filter="", state="", labels="", sort="", direction="", since=None, number=-1, etag=None):
    """
    Iterate over organization issues (requires membership).
    
    Parameters:
    - name (str, required): Organization name
    - filter (str, optional): 'assigned', 'created', 'mentioned', 'subscribed'
    - state (str, optional): 'all', 'open', 'closed'
    - labels (str, optional): Comma-separated label names
    - sort (str, optional): 'created', 'updated', 'comments'
    - direction (str, optional): 'asc', 'desc'
    - since (datetime/str, optional): Only issues after this date
    - number (int): Number to return (-1 for all)
    - etag (str, optional): ETag from previous request
    
    Returns:
    Generator of ShortIssue objects
    """

# List organization issues
for issue in gh.organization_issues('my-org', filter='assigned', state='open'):
    print(f"{issue.repository.name}#{issue.number}: {issue.title}")
    print(f"Assigned to: {[a.login for a in issue.assignees]}")

class Issue:
    """Full issue representation with all details and operations"""
    id: int
    number: int
    title: str
    body: str
    state: str  # 'open' or 'closed'
    user: User  # Issue author
    assignee: User  # Primary assignee (deprecated)
    assignees: list  # List of assigned users
    labels: list  # List of Label objects
    milestone: Milestone
    comments: int
    created_at: datetime
    updated_at: datetime
    closed_at: datetime
    repository: Repository
    html_url: str
    # ... additional issue properties and methods

class ShortIssue:
    """Abbreviated issue representation for list operations"""
    id: int
    number: int
    title: str
    state: str
    user: User
    # ... essential issue properties

class PullRequest:
    """Full pull request representation with code review details"""
    id: int
    number: int
    title: str
    body: str
    state: str  # 'open', 'closed', 'merged'
    user: User
    assignee: User
    assignees: list
    labels: list
    milestone: Milestone
    head: dict  # Source branch info
    base: dict  # Target branch info
    merged: bool
    mergeable: bool
    merged_at: datetime
    merged_by: User
    commits: int
    additions: int
    deletions: int
    changed_files: int
    review_comments: int
    # ... additional PR properties and methods

class ShortPullRequest:
    """Abbreviated pull request representation"""
    id: int
    number: int
    title: str
    state: str
    # ... essential PR properties

class Label:
    """Issue/PR label representation"""
    id: int
    name: str
    color: str
    description: str
    # ... additional label properties

class Milestone:
    """Issue milestone representation"""
    id: int
    number: int
    title: str
    description: str
    state: str
    created_at: datetime
    updated_at: datetime
    due_on: datetime
    closed_issues: int
    open_issues: int
    # ... additional milestone properties

class Comment:
    """Issue/PR comment representation"""
    id: int
    body: str
    user: User
    created_at: datetime
    updated_at: datetime
    html_url: str
    # ... additional comment properties

# Create issue from template
issue = gh.create_issue(
    'owner', 'repo',
    title='[BUG] Login fails with special characters',
    body='## Bug Report\n**Steps to reproduce:**\n1. ...',
    labels=['bug', 'priority-high']
)

# Add comments and updates
issue.create_comment('Investigating this issue...')
issue.add_labels(['investigating'])

# Get PR and review details
pr = gh.pull_request('owner', 'repo', 123)

# Check review status
print(f"Mergeable: {pr.mergeable}")
print(f"Review comments: {pr.review_comments}")

# List PR files and changes
for file in pr.files():
    print(f"{file.filename}: +{file.additions}/-{file.deletions}")

# Bulk operations on issues
org_issues = list(gh.organization_issues('my-org', state='open'))

# Find stale issues
import datetime
cutoff = datetime.datetime.now() - datetime.timedelta(days=30)
stale_issues = [i for i in org_issues if i.updated_at < cutoff]

print(f"Found {len(stale_issues)} stale issues")

# Complex issue queries
# Issues assigned to multiple people
multi_assigned = gh.issues_on(
    'owner', 'repo',
    assignee='*',  # Any assignee
    labels='priority-high,bug'
)

# Recent issues with activity
recent = gh.issues_on(
    'owner', 'repo',
    since=datetime.datetime.now() - datetime.timedelta(days=7),
    sort='updated'
)