Snapshot Explain#

Module that handles all Factiva Analytics Explain requests and objects. Contains classes and tools that allow to run volume estimates and obtain random samples given a predefined selection criteria (query).

SnapshotExplain#

class factiva.analytics.snapshots.explain.SnapshotExplain(user_key=None, query=None, job_id=None)#

Main class to interact with the Explain service from Factiva Analytics.

user_key#

User representation for service authentication

Type:: UserKey

query#

Query object tailored for Extraction operations

Type:: SnapshotExtractionQuery

job_response#

Object containing job status and execution details

Type:: SnapshotExtractionJobReponse

samples#

Type:: SnapshotExplainSamplesResponse

get_job_response() → bool#

Performs a request to the API using the job ID to get its status.

If the job has been completed, results are assigned to the job_response object.

Returns:: True if the get request was successful. An Exception otherwise.
Return type:: bool

get_samples(num_samples: int = 100)#

Performs a request to the API using the job ID to get its status.

If the job has been completed, results are assigned to the job_response object.

Returns:: True if the get request was successful. An Exception otherwise.
Return type:: bool

process_job()#

Submits a new job to be processed, wait until the job is completed and then retrieves the job results.

Returns:: True if the explain processing was successful. An Exception otherwise.
Return type:: bool

submit_job()#

Performs a POST request to the API using the assigned query to start an Explain job.

If the job is initiated succesfully, results are assigned to the job_response object. Otherwise any HTTP error will raise an exception.

Returns:: True if the submission was successful. An Exception otherwise.
Return type:: bool

SnapshotExplainQuery#

class factiva.analytics.snapshots.explain.SnapshotExplainQuery(where=None, includes: dict | None = None, include_lists: dict | None = None, excludes: dict | None = None, exclude_lists: dict | None = None)#

Query class used specifically for Snapshot Explain operations.

where#

User representation for service authentication

Type:: str

includes#

Dictionary with a fixed list of codes to include

Type:: dict

includes_list#

Dictionary with references to Lists for inclusion

Type:: dict

excludes#

Dictionary with a fixed list of codes to exclude

Type:: dict

excludes_list#

Dictionary with references to Lists for inclusion

Type:: dict

get_payload() → dict#

Create the basic request payload to be used within Snapshots Explain API request.

Returns:: Dictionary containing non-null query attributes.
Return type:: dict

SnapshotExplainJobResponse#

class factiva.analytics.snapshots.explain.SnapshotExplainJobResponse(job_id: str | None = None)#

Snapshot Explain Job Response class. Essentially contains the volume of estimate documents.

job_id#

Explain Job ID with a format like abcd1234-ab12-ab12-ab12-abcdef123456.

Type:: str

job_link#

Unique URL referring to the job instance

Type:: str

job_state#

Latest known job status. Value is self-explanatory.

Type:: str

volume_estimate#

Number representing the total volume of matching documents

Type:: int

errors#

Job execution errors returned by the API

Type:: list[dict]

SnapshotExplainSamplesResponse#

class factiva.analytics.snapshots.explain.SnapshotExplainSamplesResponse(samples_list: list)#

Snapshot Explain Samples Response class. Essentially contains the list of metadata samples randomly selected from a previously sent criteria linked to the Job ID.

num_samples#

Number with the returned number of samples

Type:: int

data#

Pandas DataFrame with the samples dataset

Type:: pandas.DataFrame