API Reference

Reporter Client

This module exposes the Reporter object.

class reporter.client.Reporter(api_token, url, ssl_verify=True)

Bases: object

Represents a Reporter server connection.

Parameters:

  • api_token (str) – The Reporter API token to use for authentication.

  • ssl_verify (bool) – Whether to verify the server’s SSL certificate.

  • url (str) – The URL of the Reporter server. Must start with URL scheme (i.e. https://).

get_raw_file(path, headers=None, **kwargs)

Wrapper around http_request() for downloading a raw file as bytestring.

Parameters:

  • path (str) – URL path of the raw file.

  • headers – Request headers. Default: {"Accept": "*/*"}.

  • **kwargs – Extra options to pass to the underlying http_request() call.

Return type:

bytes

Returns:

The raw file as a bytestring.

http_request(verb, path, headers=None, query_data=None, post_data=None, files=None, obey_rate_limit=True)

Make an HTTP request to the Reporter server.

Parameters:

  • verb (str) – The HTTP method to call (e.g. get, post, put, delete).

  • path (str) – Path to query (e.g. findings/1 for /api/v1/findings/1).

  • headers (Optional[Mapping[str, str]]) – Extra HTTP headers; will overwrite default headers.

  • query_data (Optional[Mapping[str, Any]]) – Data to send as query string parameters.

  • post_data (Optional[Mapping[str, Any]]) – Data to send in the body. This will be converted to JSON unless files is not None.

  • files (Optional[Mapping[str, Any]]) – The files to send in the request. If this is not None, then the request will be a multipart/form-data request.

  • obey_rate_limit – If True, when receiving a 429 response, sleep for the amount of seconds specified in the response Retry-After header before retrying the request.

Return type:

Response

Returns:

A requests Response object corresponding to the response from the Reporter server.

Raises:

ReporterHttpError – If the return code is not 2xx.

session: Session

The requests.Session object used to make HTTP requests.

Object Base Classes

Base classes for API models.

This module contains base classes that should be inherited by objects representing API models, managers of these objects, and lists of these objects.

class reporter.base.RestList(data, links, meta)

Bases: Sequence, Generic[ChildOfRestObject]

Represents a list of RestObject instances built from server data.

Includes associated links and metadata.

Parameters:

  • data (List[TypeVar(ChildOfRestObject, bound= RestObject)]) – List of RestObject instances

  • links (Mapping[str, str]) – Dict of links (see Reporter API docs)

  • meta (Mapping[str, str]) – Dict of metadata (see Reporter API docs)

meta: Mapping[str, str]
class reporter.base.RestManager(reporter, parent=None)

Bases: Sequence, Generic[ChildOfRestObject]

Base class for RestObject managers.

Parameters:

  • reporter (Reporter) – connection to use to make requests

  • parent (Optional[RestObject]) – RestObject to which the manager is attached, if applicable

reporter: Reporter
class reporter.base.RestObject(reporter, attrs)

Bases: object

Represents an object built from server data.

Parameters:

  • reporter (Reporter) – The Reporter instance used by this object to perform requests.

  • attrs (Mapping[str, Any]) – Object attributes

keys()
reporter: Reporter

Mixins

Mixins for model CRUD operations.

Instances of RestManager should derive these mixins according to the operations possible on their corresponding RestObject in the Reporter API.

class reporter.mixins.CreateMixin

Bases: Generic[ChildOfRestObject]

Manager can create object.

create(attrs, file=None, **kwargs)

Create a new object.

Parameters:

  • attrs (Mapping[str, Any]) – Attributes for the created object.

  • file (Optional[Any]) – A file to upload when creating the object, if any.

  • kwargs (Any) – Extra options to pass to the underlying reporter.Reporter.http_request() call.

Return type:

TypeVar(ChildOfRestObject, bound= RestObject)

Returns:

The response from the server, serialized into the object type.

Raises:

ReporterHttpError – If raised by the underlying call to reporter.Reporter.http_request().

reporter: Reporter
class reporter.mixins.CrudMixin

Bases: CreateMixin, GetMixin, UpdateMixin, DeleteMixin, Generic[ChildOfRestObject]

Composite class of other mixins.

class reporter.mixins.DeleteMixin

Bases: Generic[ChildOfRestObject]

Manager can delete object.

delete(id, **kwargs)

Delete an object.

Parameters:

  • id (str) – The ID of the object to delete.

  • kwargs (Any) – Extra options to pass to the underlying reporter.Reporter.http_request() call.

Raises:

ReporterHttpError – If raised by the underlying call to reporter.Reporter.http_request().

reporter: Reporter
class reporter.mixins.GetMixin

Bases: Generic[ChildOfRestObject]

Manager can retrieve object.

get(id, include=None, query_data=None, **kwargs)

Retrieve a single object.

Parameters:

  • id (str) – The ID of the object to retrieve.

  • include (Optional[List[str]]) – Related data to include in the response.

  • query_data (Optional[Mapping[str, str]]) – Dict of additional query parameters

  • kwargs (Any) – Extra options to pass to the underlying reporter.Reporter.http_request() call.

Return type:

TypeVar(ChildOfRestObject, bound= RestObject)

Returns:

The response from the server, serialized into the object type.

Raises:

ReporterHttpError – If raised by the underlying call to reporter.Reporter.http_request().

reporter: Reporter
class reporter.mixins.ListMixin

Bases: _ListMixin

Manager can list objects.

list(filter=None, sort=None, include=None, page=None, page_size=None, query_data=None, **kwargs)

Retrieve a list of objects.

Parameters:

  • filter (Optional[Mapping[str, str]]) – query string parameters for HTTP request of the form filter[field]

  • sort (Optional[List[str]]) – How to sort retrieved items

  • include (Optional[List[str]]) – Types of related data to include

  • page (Optional[int]) – ID of the page to return - page[number]

  • page_size (Optional[int]) – Number of items to return per page - page[size]

  • query_data (Optional[Mapping[str, str]]) – Dict of additional query parameters

  • kwargs (Any) – Extra options to pass to the underlying reporter.Reporter.http_request() call.

Return type:

RestList

Returns:

A RestList of RestObject instances.

Raises:

ReporterHttpError – If raised by the underlying call to reporter.Reporter.http_request().

class reporter.mixins.SearchMixin

Bases: _ListMixin

Manager can search for objects.

search(term=None, page=None, page_size=None, query_data=None, **kwargs)

Search for a list of objects.

Parameters:

  • term (Optional[str]) – Term to search for

  • page (Optional[int]) – ID of the page to return - page[number]

  • page_size (Optional[int]) – Number of items to return per page - page[size]

  • query_data (Optional[Mapping[str, str]]) – Dict of additional query parameters

  • kwargs (Any) – Extra options to pass to the underlying reporter.Reporter.http_request() call.

Return type:

RestList

Returns:

A RestList of RestObject instances.

Raises:

ReporterHttpError – If raised by the underlying call to reporter.Reporter.http_request().

class reporter.mixins.UpdateMixin

Bases: Generic[ChildOfRestObject]

Manager can update objects.

reporter: Reporter
update(id, attrs, **kwargs)

Update an object of type self._obj_cls.

Parameters:

  • id (str) – ID of the object to update

  • attrs (Mapping[str, Any]) – Attributes to update

  • kwargs (Any) – Extra options to pass to the underlying reporter.Reporter.http_request() call.

Return type:

TypeVar(ChildOfRestObject, bound= RestObject)

Returns:

The response from the server, serialized into the object type.

Raises:

ReporterHttpError – If raised by the underlying call to reporter.Reporter.http_request().

Exceptions

This module contains exceptions raised by this library.

exception reporter.exceptions.ReporterError(error_message='', response_code=None, response_body=None)

Bases: Exception

Base class for Reporter errors.

Parameters:

  • error_message (Union[bytes, str]) – The error message.

  • response_code (Optional[int]) – The response code returned by the server.

  • response_body (Optional[bytes]) – The response body returned by the server.

Return type:

None

exception reporter.exceptions.ReporterHttpError(error_message='', response_code=None, response_body=None)

Bases: ReporterError

Raised on unsuccessful HTTP response.

Parameters:

  • error_message (Union[bytes, str]) –

  • response_code (Optional[int]) –

  • response_body (Optional[bytes]) –

Return type:

None