Skip to content

Commit 98fec1b

Browse files
miballemiballe
committed
Readme doc updated with latest classes.
1 parent 69d5314 commit 98fec1b

File tree

1 file changed

+75
-46
lines changed

1 file changed

+75
-46
lines changed

‎README.rst‎

Lines changed: 75 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
Dow Jones Factiva Analytics Python Library
22
##########################################
33
.. image:: https://github.com/dowjones/factiva-analytics-python/actions/workflows/main_test_publish.yml/badge.svg
4+
.. image:: https://readthedocs.org/projects/factiva-analytics-python/badge/?version=latest&style=plastic
45

56
This library simplifies the integration to Factiva Analytics API services that delivers premium news content.
67

@@ -10,6 +11,7 @@ The following services are currently implemented.
1011
* **Snapshots**: Allows to run each snapshot creation, monitoring, download and local exploration, in an individual manner. Also allows to run the whole process within a single method.
1112
* **Streams**: In addition to creating and getting stream details, contains the methods to easily implement a stream listener and push the content to other locations appropriate for high-available setups.
1213
* **Taxonomy**: Operations that return taxonomies applied to classify news content.
14+
* **Article Retrieval**: Allows to retrieve articles by their unique identifiers (AN) for display purposes only.
1315

1416
Installation
1517
============
@@ -23,68 +25,95 @@ Using Library services
2325
======================
2426
Most Factiva Analytics services are implemented in this library. There may be a delay (commonly weeks) when new features are released and their operations are implemented in this package.
2527

26-
Creating a User Instance and Getting its statistics
27-
---------------------------------------------------
28-
Create `UserKey` instance and retrieve a summary of the account statistics.
28+
Getting Account Information
29+
---------------------------
30+
Create an `AccountInfo` instance that retrieves a summary of the account's basic information and usage statistics.
2931

3032
.. code-block:: python
3133
32-
from factiva.analytics import UserKey
33-
u = UserKey(
34-
key='abcd1234abcd1234abcd1234abcd1234', # Not needed if the ENV variable FACTIVA_USERKEY is set
35-
stats=True) # Connects to the API and pulls the latest account status
34+
from factiva.analytics import AccountInfo
35+
u = AccountInfo(
36+
user_key='abcd1234abcd1234abcd1234abcd1234' # Not needed if the ENV variable FACTIVA_USERKEY is set
37+
)
3638
print(u)
3739
3840
.. code-block::
3941
40-
<class 'factiva.core.userkey.UserKey'>
41-
|-key = ****************************1234
42-
|-cloud_token = **Not Fetched**
43-
|-account_name = AccName1234
44-
|-account_type = account_with_contract_limits
45-
|-active_products = DNA
46-
|-max_allowed_concurrent_extractions = 5
47-
|-max_allowed_extracted_documents = 200,000
48-
|-max_allowed_extractions = 3
49-
|-currently_running_extractions = 0
50-
|-total_downloaded_bytes = 7,253,890
51-
|-total_extracted_documents = 2,515
52-
|-total_extractions = 1
53-
|-total_stream_instances = 4
54-
|-total_stream_subscriptions = 1
55-
|-enabled_company_identifiers = [{'id': 4, 'name': 'isin'}, {'id': 3, 'name': 'cusip'}, {'id': 1, 'name': 'sedol'}, {'id': 5, 'name': 'ticker_exchange'}]
56-
|-remaining_documents = 197,485
57-
|-remaining_extractions = 2
58-
59-
Snapshots
60-
---------
42+
<'factiva.analytics.AccountInfo'>
43+
├─user_key: <'factiva.analytics.UserKey'>
44+
│ ├─key: ****************************1234
45+
│ └─cloud_token: **********************YKB12sJrkHXX
46+
├─account_name: AccName1234
47+
├─account_type: account_with_contract_limits
48+
├─active_product: DNA
49+
├─max_allowed_extracted_documents: 8,000,000
50+
├─max_allowed_extractions: 20
51+
├─currently_running_extractions: 0
52+
├─total_extracted_documents: 5,493,078
53+
├─total_extractions: 4
54+
├─total_stream_instances: 0
55+
├─total_stream_subscriptions: 0
56+
├─extractions_list: <NotLoaded>
57+
├─streams_list: <NotLoaded>
58+
├─enabled_company_identifiers:
59+
│ ├─[1]: sedol
60+
│ ├─[3]: cusip
61+
│ ├─[4]: isin
62+
│ └─[5]: ticker_exchange
63+
├─remaining_documents: 2,506,922
64+
└─remaining_extractions: 16
65+
66+
67+
Snapshot Explain
68+
----------------
69+
Creates an API request that tests the query and returns the number of matching items in the archive.
70+
71+
.. code-block:: python
72+
73+
from factiva.analytics import SnapshotExplain
74+
my_query = "publication_datetime >= '2023-01-01 00:00:00' AND UPPER(source_code) = 'DJDN'"
75+
my_explain = SnapshotExplain(
76+
user_key='abcd1234abcd1234abcd1234abcd1234', # Not needed if the ENV variable FACTIVA_USERKEY is set
77+
query=my_query)
78+
my_explain.process_job() # This operation can take several seconds to complete
79+
print(my_explain)
80+
81+
.. code-block::
82+
83+
<'factiva.analytics.SnapshotExplain'>
84+
├─user_key: <'factiva.analytics.UserKey'>
85+
│ ├─key: ****************************1234
86+
│ └─cloud_token: **********************YKB12sJrkHXX
87+
├─query: <'factiva.analytics.SnapshotExplainQuery'>
88+
│ ├─where: publication_datetime >= '2023-01-01 00:00:00' AND UPPER(source_code) = 'DJDN'
89+
│ ├─includes: <NotSet>
90+
│ ├─excludes: <NotSet>
91+
│ ├─include_lists: <NotSet>
92+
│ └─exclude_lists: <NotSet>
93+
├─job_response: <'factiva.analytics.SnapshotExplainJobResponse'>
94+
│ ├─job_id: 3ee35a80-0406-4f2b-a999-3e4eb5aa94d8
95+
│ ├─job_link: https://api.dowjones...8/_explain
96+
│ ├─job_state: JOB_STATE_DONE
97+
│ ├─volume_estimate: 2,482,057
98+
│ └─errors: <NoErrors>
99+
└─samples: <NotRetrieved>
100+
101+
102+
Snapshot Extraction
103+
-------------------
61104
Create a new snapshot and download to a local repository just require a few lines of code.
62105

63106
.. code-block:: python
64107
65-
from factiva.analytics import Snapshot
66-
my_query = "publication_datetime >= '2020-01-01 00:00:00' AND LOWER(language_code) = 'en'"
67-
my_snapshot = Snapshot(
108+
from factiva.analytics import SnapshotExtraction
109+
my_query = "publication_datetime >= '2023-01-01 00:00:00' AND UPPER(source_code) = 'DJDN'"
110+
my_snapshot = SnapshotExtraction(
68111
user_key='abcd1234abcd1234abcd1234abcd1234', # Can be ommited if exist as env variable
69112
query=my_query)
70-
my_snapshot.process_extract() # This operation can take several minutes to complete
113+
my_snapshot.process_job() # This operation can take several minutes to complete
71114
72115
After the process completes, the output files are stored in a subfolder named as the Extraction Job ID.
73116

74117
In the previous code a new snapshot is created using my_query as selection criteria and user_key for user authentication. After the job is being validated internally, a Snapshot Id is obtained along with the list of files to download. Files are automatically downloaded to a folder named equal to the snapshot ID, and contents are loaded as a Pandas DataFrame to the variable news_articles. This process may take several minutes, but automates the extraction process significantly.
75118

76-
Streams
77-
-------
78-
Create a stream instance and get the details to configure the stream client and listen the content as it is delivered.
79-
80-
.. code-block:: python
81-
82-
from factiva.analytics import Stream
83119

84-
stream_query = Stream(
85-
user_key='abcd1234abcd1234abcd1234abcd1234', # Can be ommited if exist as env variable
86-
user_key_stats=True,
87-
query="publication_datetime >= '2021-04-01 00:00:00' AND LOWER(language_code)='en' AND UPPER(source_code) = 'DJDN'",
88-
)
89-
90-
print(stream_query.create())

0 commit comments

Comments
 (0)