Better doc + credits

.gitignore

@@ -1,3 +1,4 @@
 *.pyc
+*.swp
 konnectors.json*
 out.json

README.md

@@ -47,10 +47,19 @@ Each module map has a `cookies` entry containing the cookies used to fetch the
 data, so that any program running afterwards can download documents.
 
 The other entries in these maps depend on the module capabilities as defined
-by Weboob.
+by Weboob. Detailed informations about these other entires can be found in the
+`doc/capabilities` folder.
 
 
 ## License
 
 The content of this repository is licensed under an MIT license, unless
 explicitly mentionned otherwise.
+
+
+## Credits
+
+* [Cozy](http://cozy.io/) and the cozy guys on #cozycloud @ freenode
+* [Weboob](http://weboob.org/) and the weboob guys on #weboob @ freenode
+* [Kresus](https://github.com/bnjbvr/kresus/) for giving the original idea and
+  base code.

capabilities/CapDocument.py

@@ -23,6 +23,8 @@ def to_cozy(document):
         subscriptions = None
 
     # Fetch and clean the list of bills
+    # Bills are formatted final documents emitted by the third party (typically
+    # monthly bills for a phone service provider)
     try:
         assert subscriptions
         bills = {
@@ -37,7 +39,8 @@ def to_cozy(document):
 
     # Fetch and clean the list of details of the subscription (detailed
     # consumption)
-    # TODO: What is this?
+    # Details are aggregated billing counts (typically aggregated counts by
+    # communication type for a phone service provider)
     try:
         assert subscriptions
         detailed_bills = {
@@ -51,6 +54,8 @@ def to_cozy(document):
         detailed_bills = None
 
     # Fetch and clean the list of history bills
+    # History bills are detailed bills for any event that resulted in a bill
+    # (typically any communication for a phone service provider)
     try:
         assert subscriptions
         history_bills = {

cozyweboob.py

@@ -2,6 +2,9 @@
 """
 Wrapper script around Weboob to be able to use it in combination with Cozy +
 Konnectors easily.
+
+Part of this code comes from [Kresus](https://github.com/bnjbvr/kresus/)
+written by bnjbvr and released under MIT.
 """
 from __future__ import print_function
 

doc/capabilities/CapDocument.md

@@ -0,0 +1,11 @@
+CapDocument
+===========
+
+This capability is used for modules that have billing support.
+
+| Key             | Value                                                                                                                                                                             |
+|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| subscriptions   | List of subscriptions (contracts)                                                                                                                                                 |
+| bills           | Map of bills for each subscription. Bills are final document produced by the third party.                                                                                         |
+| history_bills   | Map of history bills for each subscription. History bills are detailed counts for any event resulting in a transaction (typically any communication for a phone service provider) |
+| detailed_bills  | Map of detailed bills for each subscription. Detailed bills are aggregated counts by facturation type (typically voice and texts for a phone service provider)                    |

tools/jsonwriter.py

@@ -1,6 +1,9 @@
 """
 This module implements a custom JSON writer to be able to serialize data
 returned by Weboob and pretty print the output JSON.
+
+Based upon
+http://stackoverflow.com/questions/11875770/how-to-overcome-datetime-datetime-not-json-serializable-in-python.
 """
 import json