Authentication Service#

Module part of the core componenets for the Factiva Analytics python package. Contains classes and tools that allow to interact with the authentication and authorization elements of the Factiva Analytics API.

UserKey#

class factiva.analytics.auth.userkey.UserKey(key=None, stats=False)#

Class that represents an API user and can be instantiated based on the user-key value provided by the Dow Jones Developer Support team.

get_cloud_token() → bool#

Request a cloud token and stores its content in the cloud_token property

Returns:: True if the operation was completed successfully. False otherwise.
Return type:: bool

get_extractions(updates=False) → DataFrame#

Request a list of historical extractions for the account.

Parameters:: updates (bool) – Indicates whether the retrieved list should include update operations (True) or not (False - default).
Returns:: containing the list of historical extractions for the account.
Return type:: padas.Dataframe

get_stats() → bool#

Request the account details to the Factiva Account API Endpoint. This operation can take several seconds to complete.

Returns:: True if the operation was completed successfully. False otherwise. All returned values are assigned to the object’s properties directly.
Return type:: bool

Examples

Creates a local UserKey instance and then retrieves the stats.

from factiva.analytics import UserKey
u = UserKey('abcd1234abcd1234abcd1234abcd1234')
print(u)

output

<class 'factiva.analytics.UserKey'>
├─key: ****************************1234
├─cloud_token: <NotLoaded>
├─account_name: <NotLoaded>
├─account_type: <NotLoaded>
├─active_product: <NotLoaded>
├─max_allowed_concurrent_extractions: 0
├─max_allowed_extracted_documents: 0
├─max_allowed_extractions: 0
├─currently_running_extractions: 0
├─total_downloaded_bytes: 0
├─total_extracted_documents: 0
├─total_extractions: 0
├─total_stream_instances: 0
├─total_stream_subscriptions: 0
├─enabled_company_identifiers:
│  └─<NotLoaded>
├─remaining_documents: 0
└─remaining_extractions: 0

u.get_stats()
print(u)

output

<class 'factiva.analytics.UserKey'>
├─key: ****************************1234
├─cloud_token: <NotLoaded>
├─account_name: AccName1234
├─account_type: account_with_contract_limits
├─active_product: DNA
├─max_allowed_concurrent_extractions: 5
├─max_allowed_extracted_documents: 200,000
├─max_allowed_extractions: 3
├─currently_running_extractions: 0
├─total_downloaded_bytes: 7,253,890
├─total_extracted_documents: 2,515
├─total_extractions: 1
├─total_stream_instances: 4
├─total_stream_subscriptions: 1
├─enabled_company_identifiers:
|  ├─[1]: sedol
|  ├─[3]: cusip
|  ├─[4]: isin
|  ├─[5]: ticker_exchange
├─remaining_documents: 197,485
└─remaining_extractions: 2

get_streams(running=True) → DataFrame#

Retrieves the list of streams for the user.

Parameters:: running (bool) – Indicates whether the retrieved list should be restricted to only running streams (True - default) or also include historical ones (False).
Returns:: DataFrame with the list of historical extractions
Return type:: pandas.DataFrame

show_extractions(updates=False)#

Shows the list of historical extractions for the account. Intended to be used in notebooks or manual Python command executions.

Parameters:: updates (bool) – Indicates whether the retrieved list should include update operations (True) or not (False - default).
Returns:: Displays a table with the extraction list.
Return type:: nothing

Examples

Show the historical extractions for the current user:

from factiva.analytics import UserKey
u = UserKey()
u.show_extractions()

      current_state format extraction_type snapshot_sid update_id
  JOB_STATE_DONE   avro       documents   0pjfkz33ra      None
  JOB_STATE_DONE   json       documents   0rsfemt846      None
  JOB_STATE_DONE   json       documents   1snv7pjx1a      None
  JOB_STATE_DONE   json       documents   2toxzrekx1      None
  JOB_STATE_DONE    csv       documents   2udvglt9xy      None
..              ...    ...             ...          ...       ...
 JOB_STATE_DONE   avro       documents   re9xq88syg      None
 JOB_STATE_DONE   json       documents   wfbf3eacz8      None
 JOB_STATE_DONE   json       documents   ymhsvx20tl      None
 JOB_STATE_DONE   json       documents   yonrtw2hbe      None
 JOB_STATE_DONE   avro       documents   zpxgqyrqgr      None

show_streams(running=True)#

Shows the list of streams for a given user.

This function runs the existing function get_streams and prints a user-friendly table with stream details.

Parameters:: running (bool) – Flag that indicates whether the displayed list should be restricted to only running streams (True) or also include cancelled and failed ones (False).
Returns:: Displays a table with the extraction list.
Return type:: nothing

Examples

Show running streams:

from factiva.analytics import UserKey
u = UserKey()
u.show_streams()

  job_status        stream_id  stream_type                subscriptions n_subscriptions
1 JOB_STATE_RUNNING kmzx8wrbzs      stream [kmzx8wrbzs-filtered-1nJvA5]               1

property remaining_documents#: Dynamic property that calculates the account’s remaining documents

property remaining_extractions#: Dynamic property that calculates the account’s remaining extractions

OAuthUser#

class factiva.analytics.auth.oauthuser.OAuthUser(client_id: str | None = None, username: str | None = None, password: str | None = None)#

Class that represents a Dow Jones OAuth user.

Parameters:

client_id (str) – Assigned Client ID and communicated via the Welcome Letter. Retrieves the value from the ENV variable FACTIVA_CLIENTID it not provided.
username (str) – Assigned Username and communicated via the Welcome Letter. Retrieves the value from the ENV variable FACTIVA_USERNAME it not provided.
password (str) – Assigned password and communicated via the Welcome Letter. Retrieves the value from the ENV variable FACTIVA_PASSWORD it not provided.

Examples

Create an OAuthUser instance from ENV variables and assign the JWT token to a request headers dictionary.

from factiva.analytics import OAuthUser
o = OAuthUser()
headers = {
    'Authorization': f'Bearer {o.current_jwt_token}'
}

Shows the relevant properties of a OAuthUser instance.

from factiva.analytics import OAuthUser
o = OAuthUser()
o

output

<'factiva.analytics.OAuthUser'>
|-client_id = ****************************4Cs6
|-username = 9ZZZ000000-svcaccount@dowjones.com
|-password = ************gRk3
|-token_status = not_authenticated

property current_jwt_token#: Returns a valid token to be used in the Authorization HTTP header. Recalculates the JWT token automatically if needed.

get_id_token() → bool#

Requests an ID token to the DJ auth service (authentication operation) and store the necessary information for furher requests in the relevant instance properties.

Returns:: True if the operation was completed successfully. False otherwise.
Return type:: bool

get_jwt_token() → bool#

Requests a JWT Authorization token to the Factiva Auth service. The returned token is stored internally and available via the current_jwt_token property. Usual expiration is 1 hour (3600 seconds).

Returns:: True if the operation was completed successfully. False otherwise.
Return type:: bool

property token_status: str#

Provides the current token status:

not_authenticated (get_id_token() has not been executed)
id_token_expired (previously obtained ID token has expired)
not_authorized (get_jwt_token() has not been executed)
jwt_token_expired (previously obtained JWT token has expired)
OK (token is ready for authenticated requests)