Authentication Classes¶

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.

AccountInfo¶

class factiva.analytics.auth.accountinfo.AccountInfo(user_key: UserKey | str = None)¶

Class that represents a user-key Account and can be instantiated based on the user-key value provided when the Factiva Analytics account was provisioned and notified via the Welcome email.

Parameters:: user_key (str) – String containing the 32-character long APi Key. If not provided, the constructor will try to obtain its value from the FACTIVA_USERKEY environment variable.

Examples

Creating a new instance taking the key value from the FACTIVA_USERKEY environment varaible, and not requesting account statistics.

from factiva.analytics import AccountInfo
ai = AccountInfo()
print(ai)

<'factiva.analytics.AccountInfo'>
├─user_key: <'factiva.analytics.UserKey'>
│  ├─key: ****************************nQdu
│  └─cloud_token: **********************YKB22sJCkHXX
├─account_name: Account-Name
├─account_type: account_with_contract_limits
├─active_product: DNA
├─max_allowed_extracted_documents: 20,000,000
├─max_allowed_extractions: 30
├─currently_running_extractions: 0
├─total_extracted_documents: 15,315,291
├─total_extractions: 22
├─total_stream_instances: 0
├─total_stream_subscriptions: 0
├─extractions_list: <NotLoaded>
├─streams_list: <NotLoaded>
├─enabled_company_identifiers:
│  ├─[1]: sedol
│  ├─[3]: cusip
│  ├─[4]: isin
│  └─[5]: ticker_exchange
├─remaining_documents: 4,684,709
└─remaining_extractions: 8

Creating a new AccountInfo instance providing the user_key string explicitly and retrieving the latest account details:

from factiva.analytics import AccountInfo
ai = AccountInfo('abcd1234abcd1234abcd1234abcd1234')
print(ai)

get_extractions(updates=False) → SnapshotExtractionList¶

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

get_streams(running=True) → StreamingInstanceList¶

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

get_time_series() → 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

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

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

UserKey¶

class factiva.analytics.auth.userkey.UserKey(key=None)¶

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

OAuthUser¶

class factiva.analytics.auth.oauthuser.OAuthUser(client_id: str = None, username: str = None, password: str = 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()
print(o)

output

<'factiva.analytics.OAuthUser'>
  ├─client_id: ****************************4Cs6
  ├─username: 9zzz131500-svcaccount@dowjones.com
  ├─password: ************KAHl
  └─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)