### Navigation

- index
- modules |
- next |
- previous |
- Sage's Development Scripts »

# Trac Interface

This module provides an interface to access sage’s issue tracker ‘trac’ through its RPC interface.

AUTHORS:

- David Roe, Julian Rueth, R. Andrew Ohana, Robert Bradshaw, Timo Kluck: initial version

exception `sage.dev.trac_interface.``TicketSyntaxError`

  Bases: `exceptions.SyntaxError`

  A syntax error when parsing a ticket description modified by the user.

  EXAMPLES:

      sage: from sage.dev.trac_interface import TicketSyntaxError
      sage: raise TicketSyntaxError()
      Traceback (most recent call last):
      ...
      TicketSyntaxError: None

class `sage.dev.trac_interface.``TracInterface`(config, UI)

  Bases: `object`

  Wrapper around the XML-RPC interface of trac.

  EXAMPLES:

      sage: from sage.dev.test.config import DoctestConfig
      sage: from sage.dev.test.user_interface import DoctestUserInterface
      sage: from sage.dev.trac_interface import TracInterface
      sage: config = DoctestConfig()
      sage: trac = TracInterface(config['trac'], DoctestUserInterface(config['UI']))
      sage: trac
      <sage.dev.trac_interface.TracInterface object at 0x...>

  `add_comment`(ticket, comment)

    Add `comment` to `ticket` on trac.

    See also

    `add_comment_interactive()`

    EXAMPLES:

        sage: from sage.dev.test.config import DoctestConfig
        sage: from sage.dev.test.user_interface import DoctestUserInterface
        sage: from sage.dev.test.trac_interface import DoctestTracInterface
        sage: from sage.dev.test.trac_server import DoctestTracServer
        sage: config = DoctestConfig()
        sage: config['trac']['password'] = 'secret'
        sage: UI = DoctestUserInterface(config['UI'])
        sage: trac = DoctestTracInterface(config['trac'], UI, DoctestTracServer())
        sage: ticket = trac.create_ticket('Summary', 'Description', {'type':'defect', 'component':'algebra'})
        sage: trac.add_comment(ticket, "a comment")

  `add_comment_interactive`(ticket, comment='')

    Add a comment to `ticket` on trac.

    INPUT:

    - `comment` – a string (default: `''`), the default value for the comment to add.

    EXAMPLES:

        sage: from sage.dev.test.config import DoctestConfig
        sage: from sage.dev.test.user_interface import DoctestUserInterface
        sage: from sage.dev.test.trac_interface import DoctestTracInterface
        sage: from sage.dev.test.trac_server import DoctestTracServer
        sage: config = DoctestConfig()
        sage: config['trac']['password'] = 'secret'
        sage: UI = DoctestUserInterface(config['UI'])
        sage: trac = DoctestTracInterface(config['trac'], UI, DoctestTracServer())
        sage: ticket = trac.create_ticket('Summary', 'Description', {'type':'defect', 'component':'algebra'})

        sage: UI.append("# empty comment")
        sage: trac.add_comment_interactive(ticket)
        Traceback (most recent call last):
        ...
        OperationCancelledError: comment creation aborted

        sage: UI.append("a comment")
        sage: trac.add_comment_interactive(ticket)

  `attachment_names`(ticket)

    Retrieve the names of the attachments for `ticket`.

    EXAMPLES:

        sage: dev.trac.attachment_names(1000) # optional: internet
        ()
        sage: dev.trac.attachment_names(13147) # optional: internet
        ('13147_move.patch',
         '13147_lazy.patch',
         '13147_lazy_spkg.patch',
         '13147_new.patch',
         '13147_over_13579.patch',
         'trac_13147-ref.patch',
         'trac_13147-rebased-to-13681.patch',
         'trac_13681_root.patch')

  `create_ticket`(summary, description, attributes={})

    Create a ticket on trac and return the new ticket number.

    See also

    `create_ticket_interactive()`

    EXAMPLES:

        sage: from sage.dev.test.config import DoctestConfig
        sage: from sage.dev.test.user_interface import DoctestUserInterface
        sage: from sage.dev.test.trac_interface import DoctestTracInterface
        sage: from sage.dev.test.trac_server import DoctestTracServer
        sage: config = DoctestConfig()
        sage: config['trac']['password'] = 'secret'
        sage: UI = DoctestUserInterface(config['UI'])
        sage: trac = DoctestTracInterface(config['trac'], UI, DoctestTracServer())
        sage: trac.create_ticket('Summary', 'Description', {'type':'defect', 'component':'algebra'})
        1

  `create_ticket_interactive`()

    Drop user into an editor for creating a ticket.

    EXAMPLE:

        sage: from sage.dev.test.config import DoctestConfig
        sage: from sage.dev.test.user_interface import DoctestUserInterface
        sage: from sage.dev.test.trac_interface import DoctestTracInterface
        sage: from sage.dev.test.trac_server import DoctestTracServer
        sage: config = DoctestConfig()
        sage: config['trac']['password'] = 'secret'
        sage: UI = DoctestUserInterface(config['UI'])
        sage: trac = DoctestTracInterface(config['trac'], UI, DoctestTracServer())
        sage: UI.append("Summary: summary\nType: defect\nPriority: minor\nComponent: algebra\ndescription")
        sage: trac.create_ticket_interactive()
        1

  `dependencies`(ticket, recurse=False, seen=None)

    > Retrieve dependencies of `ticket`, sorted by ticket number.

    > INPUT:

    > - `ticket` – an integer, the number of the ticket
    > - `recurse` – a boolean (default: `False`), whether to get indirect dependencies of `ticket`
    > - `seen` – a list (default: `[]`), used internally to implement `recurse`

    EXAMPLES:

        sage: from sage.dev.test.sagedev import single_user_setup_with_internet
        sage: dev = single_user_setup_with_internet()[0]
        sage: dev.trac.dependencies(1000)            # optional: internet (an old ticket with no dependency field)
        []
        sage: dev.trac.dependencies(13147)           # optional: internet
        [13579, 13681]
        sage: dev.trac.dependencies(13147, recurse=True) # long time, optional: internet
        [13579, 13631, 13681]

  `edit_ticket_interactive`(ticket)

    Edit `ticket` on trac.

    EXAMPLES:

        sage: from sage.dev.test.config import DoctestConfig
        sage: from sage.dev.test.user_interface import DoctestUserInterface
        sage: from sage.dev.test.trac_interface import DoctestTracInterface
        sage: from sage.dev.test.trac_server import DoctestTracServer
        sage: config = DoctestConfig()
        sage: config['trac']['password'] = 'secret'
        sage: UI = DoctestUserInterface(config['UI'])
        sage: trac = DoctestTracInterface(config['trac'], UI, DoctestTracServer())
        sage: ticket = trac.create_ticket('Summary', 'Description', {'type':'defect', 'component':'algebra'})

        sage: UI.append("# empty")
        sage: trac.edit_ticket_interactive(ticket)
        Traceback (most recent call last):
        ...
        OperationCancelledError: ticket edit aborted

        sage: UI.append("Summary: summary\ndescription\n")
        sage: trac.edit_ticket_interactive(ticket)

  `query`(qstr)

    Return a list of ticket ids that match the given query string.

    INPUT:

    - `qstr` – a query string. All queries will use stored settings for maximum number of results per page and paging options. Use max=n to define number of results to receive, and use page=n to page through larger result sets. Using max=0 will turn off paging and return all results.

    EXAMPLES:

        sage: dev.trac.query('status!=closed&(component=padics||component=misc)&max=3') # random, optional: internet
        [329, 15130, 21]

  `reset_password`()

    Reset password stored in this object and in the configuration.

    EXAMPLES:

        sage: from sage.dev.test.config import DoctestConfig
        sage: from sage.dev.test.user_interface import DoctestUserInterface
        sage: from sage.dev.trac_interface import TracInterface
        sage: config = DoctestConfig()
        sage: UI = DoctestUserInterface(config['UI'])
        sage: trac = TracInterface(config['trac'], UI)
        sage: UI.append('y')
        sage: UI.append('secret')
        sage: trac._password
        Trac password:
        You can save your password in a configuration file. However, this file might be
        readable by privileged users on this system.
        Save password in file? [yes/No] y
        #  Your trac password has been written to a configuration file. To reset your
        password, use "dev.trac.reset_password()".
        'secret'
        sage: config['trac']['password']
        'secret'
        sage: trac.reset_password()
        sage: config['trac']['password']
        Traceback (most recent call last):
        ...
        KeyError: 'password'

  `reset_username`()

    Reset username and password stored in this object and in the configuration.

    EXAMPLES:

        sage: from sage.dev.test.config import DoctestConfig
        sage: from sage.dev.test.user_interface import DoctestUserInterface
        sage: from sage.dev.trac_interface import TracInterface
        sage: config = DoctestConfig()
        sage: UI = DoctestUserInterface(config['UI'])
        sage: trac = TracInterface(config['trac'], UI)
        sage: trac.reset_username()
        sage: UI.append("doctest2")
        sage: trac._username
        Trac username: doctest2
        #  Your trac username has been written to a configuration file for future
        sessions. To reset your username, use "dev.trac.reset_username()".
        'doctest2'

  `set_attributes`(ticket, comment='', notify=False, **kwds)

    Set attributes on a track ticket.

    INPUT:

    - `ticket` – the ticket id
    - `comment` – a comment when changing these attributes
    - `kwds` – a dictionary of field:value pairs

    See also

    `_get_attributes()`

    EXAMPLES:

        sage: from sage.dev.test.config import DoctestConfig
        sage: from sage.dev.test.user_interface import DoctestUserInterface
        sage: from sage.dev.test.trac_interface import DoctestTracInterface
        sage: from sage.dev.test.trac_server import DoctestTracServer
        sage: config = DoctestConfig()
        sage: config['trac']['password'] = 'secret'
        sage: UI = DoctestUserInterface(config['UI'])
        sage: trac = DoctestTracInterface(config['trac'], UI, DoctestTracServer())
        sage: n = trac.create_ticket('Summary', 'Description', {'type':'defect', 'component':'algebra', 'status':'new'})
        sage: trac._get_attributes(n)['status']
        'new'
        sage: trac.set_attributes(n, status='needs_review')
        sage: trac._get_attributes(n)['status']
        'needs_review'

    Some error checking is done:

    > sage: trac.set_attributes(n, status=’invalid_status’) Traceback (most recent call last): ... TicketSyntaxError: “invalid_status” is not a valid value for the field “status”

  `show_comments`(ticket, ignore_git_user=True)

    Shows the comments on a given ticket.

    INPUT:

    - `ticket` – the ticket number
    - `ignore_git_user` – whether to remove comments automatically added when the branch is updated.

    EXAMPLES:

        sage: dev.trac.show_comments(100) # optional: internet
        ====================
        was (6 years ago)
        fixed

  `show_ticket`(ticket)

    Show the important fields of the given ticket.

    See also

    `_get_attributes()` `show_comments()`

    EXAMPLES:

        sage: from sage.dev.test.sagedev import single_user_setup_with_internet
        sage: dev = single_user_setup_with_internet()[0]
        sage: dev.trac.show_ticket(101) # optional: internet
        #101: closed enhancement
        == graph theory -- create a graph theory package for SAGE ==
        Opened: ... years ago
        Closed: ... years ago
        Priority: major
        Milestone: sage-2.8.5
        Component: combinatorics
        ----------------------------------------
        See http://sage.math.washington.edu:9001/graph for
        initial research that Robert Miller and Emily Kirkman are doing on this.

### Navigation

- index
- modules |
- next |
- previous |
- Sage's Development Scripts »