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, verb='get', headers=None, **kwargs)

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

Parameters:

path (str) – URL path of the raw file.
verb (str) – The HTTP method to call (e.g. get, post, put, delete). Default: get.
headers (Mapping[str, str] | None) – Request headers. Default: {"Accept": "*/*"}.
**kwargs (Any) – Extra options to pass to the underlying http_request() call.

Returns:

The raw file as a bytestring.

Return type:

bytes

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 (Mapping[str, str] | None) – Extra HTTP headers; will overwrite default headers.
query_data (Mapping[str, Any] | None) – Data to send as query string parameters.
post_data (Mapping[str, Any] | None) – Data to send in the body. This will be converted to JSON unless files is not None.

files (Mapping[str, FileSpec] | None) –

The files to send in the request. A mapping whose keys are field names, and whose values contain file specifications (FileSpec). If this is not None, then the request will be a multipart/form-data request.

Examples:

# Single file with file-like object (recommended)
files = {"file": open("file.json", "rb")}

# Single file with simple content
files = {"file": b"content"}

# Single file with filename
files = {"file": ("report.pdf", pdf_content)}

# Multiple files with metadata
files = {
    "document": ("report.pdf", pdf_content, "application/pdf"),
    "image": ("screenshot.png", image_data, "image/png"),
}

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

Returns:

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

Raises:

ReporterHttpError – If the return code is not 2xx.

Return type:

Response

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[ChildOfRestObject]) – 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)

links: Mapping[str, str]

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 (RestObject | None) – 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()

Return type:: KeysView

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 (FileSpec | None) –

A file to upload when creating the object, if any. Type: reporter.types.FileSpec.

Examples:

# Using file object (recommended)
manager.create(attrs, file=open("file.json", "rb"))

# Simple content (not recommended, loses filename)
manager.create(attrs, file="content")
manager.create(attrs, file=b"content")

# With filename
manager.create(attrs, file=("file.json", json_string))

# With filename and content-type
manager.create(attrs, file=("file.json", json_string, "application/json"))

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

Returns:

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

Raises:

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

Return type:

ChildOfRestObject

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().

Return type:

None

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 (str | List[str] | None) – Related data to include in the response.
query_data (Mapping[str, Any] | None) – Dict of additional query parameters
kwargs (Any) – Extra options to pass to the underlying reporter.Reporter.http_request() call.

Returns:

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

Raises:

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

Return type:

ChildOfRestObject

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 (Mapping[str, str | int | List[str | int]] | None) – query string parameters for HTTP request of the form filter[field]
sort (str | List[str] | None) – How to sort retrieved items
include (str | List[str] | None) – Types of related data to include
page (int | None) – ID of the page to return - page[number]
page_size (int | None) – Number of items to return per page - page[size]
query_data (Mapping[str, Any] | None) – Dict of additional query parameters
kwargs (Any) – Extra options to pass to the underlying reporter.Reporter.http_request() call.

Returns:

A RestList of RestObject instances.

Raises:

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

Return type:

RestList

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 (str | None) – Term to search for
page (int | None) – ID of the page to return - page[number]
page_size (int | None) – Number of items to return per page - page[size]
query_data (Mapping[str, Any] | None) – Dict of additional query parameters
kwargs (Any) – Extra options to pass to the underlying reporter.Reporter.http_request() call.

Returns:

A RestList of RestObject instances.

Raises:

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

Return type:

RestList

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.

Returns:

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

Raises:

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

Return type:

ChildOfRestObject

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 (bytes | str) – The error message.
response_code (int | None) – The response code returned by the server.
response_body (bytes | None) – 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 (bytes | str)
response_code (int | None)
response_body (bytes | None)

Return type:

None

Types

Additional types used by this library.

reporter.types.FileContent

Represents the content of a file, can be bytes, str, or a file-like object that supports read().

alias of FileLike[str | bytes] | str | bytes

class reporter.types.FileLike(*args, **kwargs)

Bases: Protocol[T_co]

Protocol for file-like objects that support read() and have a name attribute.

property name: str: Name of the file.

read(n=Ellipsis)

Read n bytes from the object.

Parameters:: n (int)
Return type:: T_co

reporter.types.FileSpec

Specification for a file, with optional name, type, and headers.

Can be one of the following:

FileContent: Raw file content (filename will be “file”)
tuple: (filename, file_content) or (filename, file_content, content_type) or (filename, file_content, content_type, headers)