Additional documentation and reference metadata methods

Author: Dario Varotto

README.md

@@ -3,18 +3,96 @@ RavenPack API - Python client
 
 A Python library to consume the [RavenPack API](https://www.ravenpack.com).
 
-[Access the documention here.](https://www.ravenpack.com/support/)
+[API documention.](https://www.ravenpack.com/support/)
 
 ## Installation
 
     pip install ravenpackapi
 
-## Basic usage
+## About
 
 The Python client helps managing the API calls to the RavenPack dataset server
  in a Pythonic way, here are some examples of usage, you can find more in the tests.
 
-To use the API you need to have a RavenPack API KEY.
-
 This is still a work in progress: while the API is stable we are still working 
 on this Python wrapper. 
+
+## Usage
+
+First, you'll need an API object that will deal with the API calls.
+
+You will need a RavenPack API KEY, you can set the `RP_API_KEY` environment variable
+or set it in your code:
+
+```python
+from ravenpackapi import RPApi
+
+api = RPApi(api_key="YOUR_API_KEY")
+```
+
+### Getting data from the datasets
+
+There are several models to deal with data, the datasets are a cut of the RavenPack data
+they are defined with a set of filters and a set of fields.
+
+```python
+# Get the dataset description from the server, here we use 'us30'
+# one of RavenPack public datasets with the top30 companies in the US  
+
+ds = api.get_dataset(dataset_id='us30')
+```
+#### Downloads: json
+
+```python
+data = ds.json(
+    start_date='2018-01-05 18:00:00',
+    end_date='2018-01-05 18:01:00',
+)
+
+for record in data:
+    print(record)
+```
+
+The json endpoint is handy for asking data synchronously, if you need to download big
+data chunks you may want to use the asynchronous datafile endpoint instead.
+
+Json queries are limited to
+* granular datasets: 10,000 records
+* indicator datasets: 500 entities, timerange 1Y, lookback 1Y
+
+#### Downloads: datafile
+
+For bigger requests the datafile endpoint can be used.
+
+Requesting a datafile, will give you back a job promise, that will take some time
+to complete.
+
+```python
+job = ds.request_datafile(
+    start_date='2018-01-05 18:00:00',
+    end_date='2018-01-05 18:01:00',
+)
+
+with open('output.csv') as fp:
+	job.save_to_file(filename=fp.name)
+```
+
+### Entity reference
+
+The entity reference endpoint give you all the available information over an Entity
+starting from the RP_ENTITY_ID
+
+```python
+ALPHABET_RP_ENTITY_ID = '4A6F00'
+
+references = api.get_entity_reference(ALPHABET_RP_ENTITY_ID)
+
+# show all the names over history
+for name in references.names:
+    print(name.value, name.start, name.end)
+    
+# print all the ticket valid today
+for ticker in references.tickers:
+    if ticker.is_valid():
+        print(ticker)
+```

ravenpackapi/examples/query_entity_reference.py

@@ -1,7 +1,5 @@
 from ravenpackapi import RPApi
-import logging
 
-logging.basicConfig(level=logging.DEBUG)
 # initialize the API (here we use the RP_API_KEY in os.environ)
 api = RPApi()
 
@@ -13,3 +11,7 @@
 print(references)
 for name in references.names:
     print(name.value, name.start, name.end)
+
+for ticker in references.tickers:
+    if ticker.is_valid():
+        print("Ticker:", ticker)

ravenpackapi/examples/query_with_json.py

@@ -6,9 +6,11 @@
 api = RPApi()
 
 # query the json endpoint for a dataset ***
-# use the public dataset with id 'us500'
-ds = api.get_dataset(dataset_id='us500')
+# use the public dataset with id 'us30'
+ds = api.get_dataset(dataset_id='us30')
 # query the dataset analytics with the json endpoint
+print(ds)
+
 data = ds.json(
     start_date='2018-01-05 18:00:00',
     end_date='2018-01-05 18:01:00',

ravenpackapi/models/reference.py

@@ -1,8 +1,33 @@
-import collections
+import datetime
+
+from ravenpackapi.utils.date_formats import as_date
+
+
+class RPEntityMetadata(object):
+    def __init__(self, value, start=None, end=None):
+        super(RPEntityMetadata, self).__init__()
+        self.value = value
+        self.start = as_date(start)
+        self.end = as_date(end)
+
+    def is_valid(self, when=None):
+        """ Check that the metadata is valid at the given time (default to now)"""
+        if when is None:
+            when = datetime.date.today()  # default to today
+        when = as_date(when)
+
+        if self.start and when < self.start:
+            return False
+        if self.end and when >= self.end:
+            return False
+        return True
+
+    def __str__(self):
+        return "Value: {value} - valid from {start} to {end}".format(
+            **self.__dict__
+        )
+
 
-RPEntityMetadata = collections.namedtuple(
-    'RPEntityMetadata', ['value', 'start', 'end']
-)
 _MAPPED_FIELDS = {
     # the fields here are singular, we use the plural attributes
     # for returning a list of RPEntityMetadata
@@ -48,13 +73,10 @@ def __getattr__(self, field):
         else:
             return self.__getattribute__(field)
 
-    @property
-    def tickers(self):
-        return [
-            RPEntityMetadata(d['data_value'],
-                             d['range_start'],
-                             d['range_end'])
-            for d in self._data['ticker']
+    def __dir__(self):
+        """ Help autocompleting this additional fields """
+        return list(super(RpEntityReference, self).__dir__()) + [
+            k for k in _MAPPED_FIELDS
         ]
 
     def __repr__(self):

ravenpackapi/tests/test_datafile.py

@@ -6,7 +6,7 @@
 from ravenpackapi.models.job import Job
 
 
-class TestDatafile:
+class TestDatafile(object):
     api = RPApi()
 
     @pytest.mark.slow

ravenpackapi/tests/test_entity_reference.py

@@ -1,5 +1,8 @@
+import datetime
+
 from ravenpackapi import RPApi
 from ravenpackapi.exceptions import APIException
+from ravenpackapi.models.reference import RPEntityMetadata
 
 APPLE_RP_ENTITY_ID = 'D8442A'
 
@@ -20,3 +23,35 @@ def test_failing(self):
             assert False, "Invalid entity should raise an Exception"
         except APIException:
             pass
+
+
+class TestMetadataValidity():
+    def test_specific_valid_range(self):
+        md = RPEntityMetadata('year 1990',
+                              start=datetime.date(1990, 1, 1),
+                              end=datetime.date(1991, 1, 1))
+        assert md.is_valid(when='1990-06-01')
+        assert not md.is_valid(when='1991-01-01')
+        assert not md.is_valid(when='1989-12-31')
+
+    def test_open_end(self):
+        md = RPEntityMetadata('since 1990',
+                              start=datetime.date(1990, 1, 1),
+                              )
+        assert not md.is_valid(when='1989-12-31')
+        assert md.is_valid(when='1990-06-01')
+        assert md.is_valid(when='1991-01-01')
+
+    def test_open_start(self):
+        md = RPEntityMetadata('until 1990',
+                              end=datetime.date(1991, 1, 1),
+                              )
+        assert md.is_valid(when='1989-12-31')
+        assert md.is_valid(when='1990-06-01')
+        assert not md.is_valid(when='1991-01-01')
+
+    def test_always_valid(self):
+        md = RPEntityMetadata('always valid')
+        assert md.is_valid(when='1989-12-31')
+        assert md.is_valid(when='1990-06-01')
+        assert md.is_valid(when='1991-01-01')

ravenpackapi/utils/date_formats.py

@@ -0,0 +1,7 @@
+import datetime
+
+
+def as_date(s):
+    if isinstance(s, str):
+        return datetime.datetime.strptime(s, '%Y-%m-%d').date()
+    return s

setup.py

@@ -26,11 +26,8 @@
 
         # Specify the Python versions you support here. In particular, ensure
         # that you indicate whether you support Python 2, Python 3 or both.
-        'Programming Language :: Python :: 2',
-        'Programming Language :: Python :: 2.6',
         'Programming Language :: Python :: 2.7',
-        'Programming Language :: Python :: 3',
-        'Programming Language :: Python :: 3.4',
+        'Programming Language :: Python :: 3.6.4',
     ],
 
     keywords='python analytics api rest news data',