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(job_id=None, user_key=None, query=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 = 10)¶

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