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 unlessfiles
is notNone
.files (
Optional
[Mapping
[str
,Any
]]) – The files to send in the request. If this is notNone
, then the request will be amultipart/form-data
request.obey_rate_limit – If
True
, when receiving a 429 response, sleep for the amount of seconds specified in the responseRetry-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 ofRestObject
instanceslinks (
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 requestsparent (
Optional
[RestObject
]) –RestObject
to which the manager is attached, if applicable
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 underlyingreporter.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()
.
- 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 underlyingreporter.Reporter.http_request()
call.
- Raises:
ReporterHttpError – If raised by the underlying call to
reporter.Reporter.http_request()
.
- 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 parameterskwargs (
Any
) – Extra options to pass to the underlyingreporter.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()
.
- 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 itemsinclude (
Optional
[List
[str
]]) – Types of related data to includepage (
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 parameterskwargs (
Any
) – Extra options to pass to the underlyingreporter.Reporter.http_request()
call.
- Return type:
- Returns:
A
RestList
ofRestObject
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 forpage (
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 parameterskwargs (
Any
) – Extra options to pass to the underlyingreporter.Reporter.http_request()
call.
- Return type:
- Returns:
A
RestList
ofRestObject
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.
- update(id, attrs, **kwargs)
Update an object of type self._obj_cls.
- Parameters:
id (
str
) – ID of the object to updateattrs (
Mapping
[str
,Any
]) – Attributes to updatekwargs (
Any
) – Extra options to pass to the underlyingreporter.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