API

`debianbts.debianbts`

Query Debian's Bug Tracking System (BTS).

This module provides a layer between Python and Debian's BTS. It provides methods to query the BTS using the BTS' SOAP interface, and the Bugreport class which represents a bugreport from the BTS.

`Bugreport`

Represents a bugreport from Debian's Bug Tracking System.

A bugreport object provides all attributes provided by the SOAP interface. Most of the attributes are strings, the others are marked.

Attributes:

Name	Type	Description
`bug_num`	`int`	The bugnumber
`severity`	`str`	Severity of the bugreport
`tags`	`list[str]`	Tags of the bugreport
`subject`	`str`	The subject/title of the bugreport
`originator`	`str`	Submitter of the bugreport
`mergedwith`	`list[int]`	List of bugnumbers this bug was merged with
`package`	`str`	Package of the bugreport
`source`	`str`	Source package of the bugreport
`date`	`datetime`	Date of bug creation
`log_modified`	`datetime`	Date of update of the bugreport
`done`	`boolean`	Is the bug fixed or not
`done_by`	`str \| None`	Name and Email or None
`archived`	`bool`	Is the bug archived or not
`unarchived`	`bool`	Was the bug unarchived or not
`fixed_versions`	`list[str]`	List of versions, can be empty even if bug is fixed
`found_versions`	`list[str]`	List of version numbers where bug was found
`forwarded`	`str`	A URL or email address
`blocks`	`list[int]`	List of bugnumbers this bug blocks
`blockedby`	`list[int]`	List of bugnumbers which block this bug
`pending`	`str`	Either 'pending' or 'done'
`msgid`	`str`	Message ID of the bugreport
`owner`	`str`	Who took responsibility for fixing this bug
`location`	`str`	Either 'db-h' or 'archive'
`affects`	`list[str]`	List of Packagenames
`summary`	`str`	Arbitrary text

Source code in debianbts/debianbts.py

class Bugreport:
    """Represents a bugreport from Debian's Bug Tracking System.

    A bugreport object provides all attributes provided by the SOAP interface.
    Most of the attributes are strings, the others are marked.

    Attributes
    ----------
    bug_num : int
        The bugnumber
    severity : str
        Severity of the bugreport
    tags : list[str]
        Tags of the bugreport
    subject : str
        The subject/title of the bugreport
    originator : str
        Submitter of the bugreport
    mergedwith : list[int]
        List of bugnumbers this bug was merged with
    package : str
        Package of the bugreport
    source : str
        Source package of the bugreport
    date : datetime
        Date of bug creation
    log_modified : datetime
        Date of update of the bugreport
    done : boolean
        Is the bug fixed or not
    done_by : str | None
        Name and Email or None
    archived : bool
        Is the bug archived or not
    unarchived : bool
        Was the bug unarchived or not
    fixed_versions : list[str]
        List of versions, can be empty even if bug is fixed
    found_versions : list[str]
        List of version numbers where bug was found
    forwarded : str
        A URL or email address
    blocks: list[int]
        List of bugnumbers this bug blocks
    blockedby : list[int]
        List of bugnumbers which block this bug
    pending : str
        Either 'pending' or 'done'
    msgid : str
        Message ID of the bugreport
    owner : str
        Who took responsibility for fixing this bug
    location : str
        Either 'db-h' or 'archive'
    affects : list[str]
        List of Packagenames
    summary : str
        Arbitrary text
    """

    def __init__(self) -> None:
        self.originator: str
        self.date: datetime
        self.subject: str
        self.msgid: str
        self.package: str
        self.tags: list[str]
        self.done: bool
        self.done_by: str | None
        self.forwarded: str
        self.mergedwith: list[int]
        self.severity: str
        self.owner: str
        self.found_versions: list[str]
        self.fixed_versions: list[str]
        self.blocks: list[int]
        self.blockedby: list[int]
        self.unarchived: bool
        self.summary: str
        self.affects: list[str]
        self.log_modified: datetime
        self.location: str
        self.archived: bool
        self.bug_num: int
        self.source: str
        self.pending: str
        # The ones below are also there but not used
        # self.fixed = None
        # self.found = None
        # self.fixed_date = None
        # self.found_date = None
        # self.keywords = None
        # self.id = None

    def __str__(self) -> str:
        """Prepare string representation."""
        s = "\n".join(
            f"{key}: {value}" for key, value in self.__dict__.items()
        )
        return s + "\n"

    def __lt__(self, other: Bugreport) -> bool:
        """Compare a bugreport with another.

        The more open and urgent a bug is, the greater the bug is:

            outstanding > resolved > archived

            critical > grave > serious > important > normal > minor > wishlist.

        Openness always beats urgency, eg an archived bug is *always* smaller
        than an outstanding bug.

        This sorting is useful for displaying bugreports in a list and sorting
        them in a useful way.

        """
        return self._get_value() < other._get_value()

    def __le__(self, other: Bugreport) -> bool:
        """Check if object <= other."""
        return not self.__gt__(other)

    def __gt__(self, other: Bugreport) -> bool:
        """Check if object > other."""
        return self._get_value() > other._get_value()

    def __ge__(self, other: Bugreport) -> bool:
        """Check if object >= other."""
        return not self.__lt__(other)

    def __eq__(self, other: object) -> bool:
        """Check if object == other."""
        if not isinstance(other, Bugreport):
            return NotImplemented
        return self._get_value() == other._get_value()

    def __ne__(self, other: object) -> bool:
        """Check if object != other."""
        if not isinstance(other, Bugreport):
            return NotImplemented
        return not self.__eq__(other)

    def _get_value(self) -> int:
        if self.archived:
            # archived and done
            val = 0
        elif self.done:
            # not archived and done
            val = 10
        else:
            # not done
            val = 20
        val += SEVERITIES[self.severity]
        return val

`eq(other)`

Check if object == other.

Source code in debianbts/debianbts.py

def __eq__(self, other: object) -> bool:
    """Check if object == other."""
    if not isinstance(other, Bugreport):
        return NotImplemented
    return self._get_value() == other._get_value()

`ge(other)`

Check if object >= other.

Source code in debianbts/debianbts.py

def __ge__(self, other: Bugreport) -> bool:
    """Check if object >= other."""
    return not self.__lt__(other)

`gt(other)`

Check if object > other.

Source code in debianbts/debianbts.py

def __gt__(self, other: Bugreport) -> bool:
    """Check if object > other."""
    return self._get_value() > other._get_value()

`le(other)`

Check if object <= other.

Source code in debianbts/debianbts.py

def __le__(self, other: Bugreport) -> bool:
    """Check if object <= other."""
    return not self.__gt__(other)

`lt(other)`

Compare a bugreport with another.

The more open and urgent a bug is, the greater the bug is:

outstanding > resolved > archived

critical > grave > serious > important > normal > minor > wishlist.

Openness always beats urgency, eg an archived bug is always smaller than an outstanding bug.

This sorting is useful for displaying bugreports in a list and sorting them in a useful way.

Source code in debianbts/debianbts.py

def __lt__(self, other: Bugreport) -> bool:
    """Compare a bugreport with another.

    The more open and urgent a bug is, the greater the bug is:

        outstanding > resolved > archived

        critical > grave > serious > important > normal > minor > wishlist.

    Openness always beats urgency, eg an archived bug is *always* smaller
    than an outstanding bug.

    This sorting is useful for displaying bugreports in a list and sorting
    them in a useful way.

    """
    return self._get_value() < other._get_value()

`ne(other)`

Check if object != other.

Source code in debianbts/debianbts.py

def __ne__(self, other: object) -> bool:
    """Check if object != other."""
    if not isinstance(other, Bugreport):
        return NotImplemented
    return not self.__eq__(other)

`str()`

Prepare string representation.

Source code in debianbts/debianbts.py

def __str__(self) -> str:
    """Prepare string representation."""
    s = "\n".join(
        f"{key}: {value}" for key, value in self.__dict__.items()
    )
    return s + "\n"

`get_bug_log(nr)`

Get Buglogs.

A buglog is a dictionary with the following mappings:

"header": string
"body": string
"attachments": list
"msg_num": int
"message": email.message.Message

Parameters:

Name	Type	Description	Default
`nr`	`int`	the bugnumber	required

Returns:

Type	Description
`list[dict[str, str \| list[Any] \| int \| Message]]`	list of buglogs

Source code in debianbts/debianbts.py

def get_bug_log(
    nr: int,
) -> list[dict[str, str | list[Any] | int | email.message.Message]]:
    """Get Buglogs.

    A buglog is a dictionary with the following mappings:

    * "header": `string`
    * "body": `string`
    * "attachments": `list`
    * "msg_num": `int`
    * "message": `email.message.Message`

    Parameters
    ----------
    nr
        the bugnumber

    Returns
    -------
    list[dict[str, str | list[Any] | int | email.message.Message]]
        list of buglogs

    """
    reply = _soap_client_call("get_bug_log", nr)
    items_el = reply("soapenc:Array")
    buglogs = []
    for buglog_el in items_el.children():
        buglog: dict[str, str | list[Any] | int | email.message.Message] = {}
        header = _parse_string_el(buglog_el("header"))
        body = _parse_string_el(buglog_el("body"))
        msg_num = int(buglog_el("msg_num"))
        # server always returns an empty attachments array ?
        attachments: list[Any] = []

        mail_parser = email.feedparser.BytesFeedParser(
            policy=email.policy.SMTP
        )
        mail_parser.feed(header.encode())
        mail_parser.feed(b"\n\n")
        mail_parser.feed(body.encode())
        message = mail_parser.close()

        buglog = {
            "header": header,
            "body": body,
            "msg_num": msg_num,
            "attachments": attachments,
            "message": message,
        }

        buglogs.append(buglog)
    return buglogs

`get_bugs(**kwargs)`

Get list of bugs matching certain criteria.

The conditions are defined by the keyword arguments.

Parameters:

Name	Type	Description	Default
`**kwargs`	`str \| int \| list[int]`	Possible keywords are: `package`: bugs for the given package `submitter`: bugs from the submitter `maint`: bugs belonging to a maintainer `src`: bugs belonging to a source package `severity`: bugs with a certain severity `status`: can be either "done", "forwarded", or "open" `tag`: see http://www.debian.org/Bugs/Developer#tags for available tags `owner`: bugs which are assigned to `owner` `bugs`: takes single int or list of bugnumbers, filters the list according to given criteria `correspondent`: bugs where `correspondent` has sent a mail to `archive`: takes a string: "0" (unarchived), "1" (archived) or "both" (un- and archived). if omitted, only returns un-archived bugs.	`{}`

Returns:

Type	Description
`list[int]`	the bugnumbers

Examples:

>>> get_bugs(package='gtk-qt-engine', severity='normal')
[12345, 23456]

Source code in debianbts/debianbts.py

def get_bugs(
    **kwargs: str | int | list[int],
) -> list[int]:
    """Get list of bugs matching certain criteria.

    The conditions are defined by the keyword arguments.

    Parameters
    ----------
    **kwargs
        Possible keywords are:

        * `package`: bugs for the given package
        * `submitter`: bugs from the submitter
        * `maint`: bugs belonging to a maintainer
        * `src`: bugs belonging to a source package
        * `severity`: bugs with a certain severity
        * `status`: can be either "done", "forwarded", or "open"
        * `tag`: see http://www.debian.org/Bugs/Developer#tags for available
          tags
        * `owner`: bugs which are assigned to `owner`
        * `bugs`: takes single int or list of bugnumbers, filters the list
          according to given criteria
        * `correspondent`: bugs where `correspondent` has sent a mail to
        * `archive`: takes a string: "0" (unarchived), "1" (archived) or "both"
          (un- and archived). if omitted, only returns un-archived bugs.

    Returns
    -------
    list[int]
        the bugnumbers

    Examples
    --------
        >>> get_bugs(package='gtk-qt-engine', severity='normal')
        [12345, 23456]

    """
    # flatten kwargs to list:
    # {'foo': 'bar', 'baz': 1} -> ['foo', 'bar','baz', 1]
    args = []
    for k, v in kwargs.items():
        args.extend([k, v])

    # pysimplesoap doesn't generate soap Arrays without using wsdl
    # I build body by hand, converting list to array and using standard
    # pysimplesoap marshalling for other types
    method_el = SimpleXMLElement("<get_bugs></get_bugs>")
    for arg_n, kv in enumerate(args):
        arg_name = "arg" + str(arg_n)
        if isinstance(kv, (list, tuple)):
            _build_int_array_el(arg_name, method_el, kv)
        else:
            method_el.marshall(arg_name, kv)

    soap_client = _build_soap_client()
    reply = soap_client.call("get_bugs", method_el)
    items_el = reply("soapenc:Array")
    return [int(item_el) for item_el in items_el.children() or []]

`get_soap_client_kwargs()`

Return SOAP client kwargs.

Returns:

Type	Description
`dict[str, str]`	the SOAP client kwargs

Source code in debianbts/debianbts.py

def get_soap_client_kwargs() -> dict[str, str]:
    """Return SOAP client kwargs.

    Returns
    -------
    dict[str, str]
        the SOAP client kwargs

    """
    return _soap_client_kwargs

`get_status(nrs)`

Return a list of Bugreport objects.

Given a list of bug numbers this method returns a list of Bugreport objects.

Parameters:

Name	Type	Description	Default
`nrs`	`int \| list[int] \| tuple[int, ...]`	The bugnumbers	required

Returns:

Type	Description
`list[Bugreport]`	list of Bugreport objects

Source code in debianbts/debianbts.py

def get_status(
    nrs: int | list[int] | tuple[int, ...],
) -> list[Bugreport]:
    """Return a list of Bugreport objects.

    Given a list of bug numbers this method returns a list of Bugreport
    objects.

    Parameters
    ----------
    nrs
        The bugnumbers

    Returns
    -------
    list[Bugreport]
        list of Bugreport objects

    """
    numbers: list[int]
    if not isinstance(nrs, (list, tuple)):
        numbers = [nrs]
    else:
        numbers = list(nrs)

    # Process the input in batches to avoid hitting resource limits on
    # the BTS
    soap_client = _build_soap_client()
    bugs = []
    for i in range(0, len(numbers), BATCH_SIZE):
        slice_ = numbers[i:i + BATCH_SIZE]
        # I build body by hand, pysimplesoap doesn't generate soap Arrays
        # without using wsdl
        method_el = SimpleXMLElement("<get_status></get_status>")
        _build_int_array_el("arg0", method_el, slice_)
        reply = soap_client.call("get_status", method_el)
        for bug_item_el in reply("s-gensym3").children() or []:
            bug_el = bug_item_el.children()[1]
            bugs.append(_parse_status(bug_el))
    return bugs

`get_usertag(email, tags=None)`

Get buglists by usertags.

Parameters:

Name	Type	Description	Default
`email`	`str`		required
`tags`	`None \| list[str] \| tuple[str, ...]`	If tags are given the dictionary is limited to the matching tags, if no tags are given all available tags are returned.	`None`

Returns:

Type	Description
`dict[str, list[int]]`	a mapping of usertag -> buglist

Source code in debianbts/debianbts.py

def get_usertag(
    email: str,
    tags: None | list[str] | tuple[str, ...] = None,
) -> dict[str, list[int]]:
    """Get buglists by usertags.

    Parameters
    ----------
    email
    tags
        If tags are given the dictionary is limited to the matching tags, if no
        tags are given all available tags are returned.

    Returns
    -------
    dict[str, list[int]]
        a mapping of usertag -> buglist

    """
    if tags is None:
        tags = []

    reply = _soap_client_call("get_usertag", email, *tags)
    map_el = reply("s-gensym3")
    mapping = {}
    # element <s-gensys3> in response can have standard type
    # xsi:type=apachens:Map (example, for email debian-python@lists.debian.org)
    # OR no type, in this case keys are the names of child elements and
    # the array is contained in the child elements
    type_attr = map_el.attributes().get("xsi:type")
    if type_attr and type_attr.value == "apachens:Map":
        for usertag_el in map_el.children() or []:
            tag = str(usertag_el("key"))
            buglist_el = usertag_el("value")
            mapping[tag] = [int(bug) for bug in buglist_el.children() or []]
    else:
        for usertag_el in map_el.children() or []:
            tag = usertag_el.get_name()
            mapping[tag] = [int(bug) for bug in usertag_el.children() or []]
    return mapping

`newest_bugs(amount)`

Return the newest bugs.

This method can be used to query the BTS for the n newest bugs.

Parameters:

Name	Type	Description	Default
`amount`	`int`	the number of desired bugs. E.g. if `amount` is 10 the method will return the 10 latest bugs.	required

Returns:

Type	Description
`list[int]`	the bugnumbers

Source code in debianbts/debianbts.py

def newest_bugs(amount: int) -> list[int]:
    """Return the newest bugs.

    This method can be used to query the BTS for the n newest bugs.

    Parameters
    ----------
    amount
        the number of desired bugs. E.g. if `amount` is 10 the method will
        return the 10 latest bugs.

    Returns
    -------
    list[int]
        the bugnumbers

    """
    reply = _soap_client_call("newest_bugs", amount)
    items_el = reply("soapenc:Array")
    return [int(item_el) for item_el in items_el.children() or []]

`set_soap_location(url)`

Set location URL for SOAP client.

You may use this method after import to override the default URL.

Parameters:

Name	Type	Description	Default
`url`	`str`	default URL	required

Source code in debianbts/debianbts.py

def set_soap_location(url: str) -> None:
    """Set location URL for SOAP client.

    You may use this method after import to override the default URL.

    Parameters
    ----------
    url
        default URL

    """
    _soap_client_kwargs["location"] = url

`set_soap_proxy(proxy_arg)`

Set proxy for SOAP client.

You must use this method after import to set the proxy.

Parameters:

Name	Type	Description	Default
`proxy_arg`	`str`		required

Source code in debianbts/debianbts.py

def set_soap_proxy(proxy_arg: str) -> None:
    """Set proxy for SOAP client.

    You must use this method after import to set the proxy.

    Parameters
    ----------
    proxy_arg

    """
    _soap_client_kwargs["proxy"] = proxy_arg

`debianbts.version`

Version module of debianbts.

`debianbts.main`

Entry point for the (not yet implemented) cli.

`main()`

CLI entry point.

Source code in debianbts/__main__.py

def main() -> None:
    """CLI entry point."""
    logger.warning("Not implemented yet, sorry!")

API

debianbts.debianbts

Bugreport

__eq__(other)

__ge__(other)

__gt__(other)

__le__(other)

__lt__(other)

__ne__(other)

__str__()

get_bug_log(nr)

get_bugs(**kwargs)

get_soap_client_kwargs()

get_status(nrs)

get_usertag(email, tags=None)

newest_bugs(amount)

set_soap_location(url)

set_soap_proxy(proxy_arg)

debianbts.version

debianbts.__main__

main()

`debianbts.debianbts`

`Bugreport`

`eq(other)`

`ge(other)`

`gt(other)`

`le(other)`

`lt(other)`

`ne(other)`

`str()`

`get_bug_log(nr)`

`get_bugs(**kwargs)`

`get_soap_client_kwargs()`

`get_status(nrs)`

`get_usertag(email, tags=None)`

`newest_bugs(amount)`

`set_soap_location(url)`

`set_soap_proxy(proxy_arg)`

`debianbts.version`

`debianbts.main`

`main()`