Merge branch 'master' into cuducos-coveralls

README.rst

@@ -50,14 +50,57 @@ Usage
 
 Copy `config.ini.example` as `config.ini` and edit it with your own credentials. If you don't plan to upload anything to S3 please don't bother about keys and secrets in this file.
 
-Example:
+Example 1: How do I download the datasets?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We have `plenty of them <https://github.com/datasciencebr/serenata-de-amor/blob/master/CONTRIBUTING.md#datasets-data>`_ ready for you to download from our servers. And this toolbox helps you get them. Let's say you want your datasets at `/tmp/serenata-data/`:
+
+.. code:: python
+
+  from serenata_toolbox.datasets import Datasets
+  datasets = Datasets('/tmp/serenata-data/')
+
+  # now lets see what datasets are available
+  for dataset in datasets.remote.all:
+      print(dataset)  # and you'll see a long list of datasets!
+
+  # now let's download one of them
+  datasets.downloader.download('2016-12-06-reibursements.xz')  # yay, you've just downloaded this dataset to /tmp/serenata-data/
+
+  # You can also get themostrecent version of all datasets:
+  latest = list(dataset.downloader.LATEST)
+  datasets.downloader.download(latest)
+
+Example 2: Using shortcuts
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the last example doesn't look that simple, there are some fancy shortcuts available:
+
+.. code:: python
+
+  from serenata_toolbox.datasets import fetch, fetch_latest_backup
+  fetch('2016-12-06-reibursements.xz', '/tmp/serenata-data')
+  fetch_latest_backup( '/tmp/serenata-data')  # yep, we've just did exactly the same thing
+
+Example 3: Generating datasets
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you ever wonder how did we generated these datasets, this toolbox can help you too (at least with the more used ones — the other ones are generated `in our main repo <https://github.com/datasciencebr/serenata-de-amor/blob/master/CONTRIBUTING.md#the-toolbox-and-our-the-source-files-src>`_):
 
 .. code:: python
 
-  $ python3
-  >>> from serenata_toolbox.datasets import Dataset
-  >>> dataset = Dataset('/tmp/serenata-data')
-  >>> tuple(dataset.local.all)
+    from serenata_toolbox.federal_senate.federal_senate_dataset import FederalSenateDataset
+    from serenata_toolbox.chamber_of_deputies.chamber_of_deputies_dataset import ChamberOfDeputiesDataset
+
+    senate = FederalSenateDataset('/tmp/serenata-data/')
+    senate.fetch()
+    senate.translate()
+    senate.clean()
+
+    chamber = ChamberOfDeputiesDataset('/tmp/serenata-data/')
+    chamber.fetch()
+    chamber.translate()
+    chamber.clean()
 
 Documentation (WIP)
 -------------------

setup.py

@@ -27,7 +27,11 @@
     license='MIT',
     long_description='Check `Serenata Toolbox at GitHub <{}>`_.'.format(REPO_URL),
     name='serenata-toolbox',
-    packages=['serenata_toolbox.chamber_of_deputies', 'serenata_toolbox.datasets'],
+    packages=[
+        'serenata_toolbox.federal_senate',
+        'serenata_toolbox.chamber_of_deputies',
+        'serenata_toolbox.datasets'
+    ],
     url=REPO_URL,
-    version='9.1.0'
+    version='10.0.0'
 )