Metadata-Version: 1.1
Name: geckoboard.py
Version: 0.2.7
Summary: Official Python client for the Geckoboard Datasets API
Home-page: https://github.com/geckoboard/geckoboard-python
Author: Geckoboard
Author-email: dan@geckoboard.com
License: MIT
Description: geckoboard-python
        =================
        
        A Python client library for `Geckoboard datasets
        API <https://developer.geckoboard.com/api-reference/>`__.
        
        *Note: This library is still in Beta and the API has potential to change
        before the release of V1.*
        
        Installation
        ------------
        
        Install the package with pip
        
        ::
        
            pip install geckoboard.py
        
        Usage
        -----
        
        The latest documentation and user guide can be found on the `Geckoboard
        developer
        docs <https://developer.geckoboard.com/api-reference/python/>`__
        
        --------------
        
        Getting started
        ---------------
        
        Install the python client from PIP
        
        ::
        
            pip install geckoboard.py
        
        Import the Geckoboard package and create an instance of the client using
        your API key:
        
        .. code:: python
        
            import geckoboard
        
            client = geckbooard.client(API_KEY)
        
        **Note:** You can find your API key by logging into the Geckoboard
        application and visiting the Account section.
        
        Authentication
        --------------
        
        Verify that your API key is valid and that you can reach the Geckoboard
        API with the ``ping`` method.
        
        .. code:: python
        
            client.ping()
        
        Example:
        ~~~~~~~~
        
        .. code:: python
        
            client('good-api-key').ping() # => true
            client('bad-api-key').ping() # => raises Exception
        
        Finding or creating a dataset
        -----------------------------
        
        Find and verify an existing dataset or create a new dataset with the
        ``find_or_create`` method. ``unique_by`` is an optional list of one or
        more field names whose values will be unique across all your records.
        
        .. code:: python
        
            client.datasets.find_or_create(dataset_id, fields, unique_by)
        
        Params:
        ~~~~~~~
        
        -  ``dataset_id`` [required] <`str <https://docs.python.org/2/library/stdtypes.html#sequence-types-str-unicode-list-tuple-bytearray-buffer-xrange>`__>
        -  ``fields`` [required] <`dict <https://docs.python.org/2/library/stdtypes.html#mapping-types-dict>`__>
            - ``type`` [required] <`str <https://docs.python.org/2/library/stdtypes.html#sequence-types-str-unicode-list-tuple-bytearray-buffer-xrange>`__>
            - ``name`` [required] <`str <https://docs.python.org/2/library/stdtypes.html#sequence-types-str-unicode-list-tuple-bytearray-buffer-xrange>`__>
            - ``optional`` <`boolean <https://docs.python.org/2/library/stdtypes.html#boolean-values>`__>
        -  ``unique_by``
           <`list <https://docs.python.org/2/library/stdtypes.html#sequence-types-str-unicode-list-tuple-bytearray-buffer-xrange>`__>
        
        Example:
        ~~~~~~~~
        
        .. code:: python
        
            dataset = client.datasets.find_or_create('sales.by_night', {
              'amount': { 'type': 'number', 'name': 'Amount', 'optional': False },
              'timestamp': { 'type': 'datetime', 'name': 'Time' }
            }, ['timestamp'])
        
        The full list of available field types is described at the top of this
        page.
        
        Replacing all data in a dataset
        -------------------------------
        
        Replace all data in the dataset by calling the ``put`` method.
        
        .. code:: python
        
            dataset.put(items)
        
        Params:
        ~~~~~~~
        
        -  ``items`` [required]
           <`list <https://docs.python.org/2/library/stdtypes.html#sequence-types-str-unicode-list-tuple-bytearray-buffer-xrange>`__>
        
        Example:
        ~~~~~~~~
        
        .. code:: python
        
            dataset.put([
              { 'timestamp': '2016-01-01T12:00:00Z', 'amount': 819 },
              { 'timestamp': '2016-01-02T12:00:00Z', 'amount': 409 },
              { 'timestamp': '2016-01-03T12:00:00Z', 'amount': 164 }
            ])
        
        Appending data to a dataset
        ---------------------------
        
        Append records to a dataset by calling the ``post`` method.
        
        Should the number of records in your dataset exceed the limit following
        a post `old records will be discarded <#record-count-limit>`__.
        
        .. code:: python
        
            dataset.post(items, delete_by)
        
        Params:
        ~~~~~~~
        
        -  ``items`` [required]
           <`list <https://docs.python.org/2/library/stdtypes.html#sequence-types-str-unicode-list-tuple-bytearray-buffer-xrange>`__>
        -  ``delete_by``
           <`str <https://docs.python.org/2/library/stdtypes.html#sequence-types-str-unicode-list-tuple-bytearray-buffer-xrange>`__>
        
        Example:
        ~~~~~~~~
        
        .. code:: python
        
            dataset.post([
              { 'timestamp': '2016-01-03T12:00:00Z', 'amount': 312 },
              { 'timestamp': '2016-01-04T12:00:00Z', 'amount': 665 },
              { 'timestamp': '2016-01-05T12:00:00Z', 'amount': 453 }
            ], 'timestamp')
        
        Deleting a dataset
        ------------------
        
        Delete the dataset and all data with the given id.
        
        .. code:: python
        
            client.datasets.delete(dataset_id)
        
        Params:
        ~~~~~~~
        
        -  ``dataset_id`` [required]
           <`str <https://docs.python.org/2/library/stdtypes.html#sequence-types-str-unicode-list-tuple-bytearray-buffer-xrange>`__>
        
        Example:
        ~~~~~~~~
        
        .. code:: python
        
            client.datasets.delete('sales.gross') # => true
        
        You can also delete a dataset by calling the ``delete`` method on a
        dataset.
        
        .. code:: python
        
            dataset = client.datasets.find_or_create(...)
            dataset.delete() # => true
        
        --------------
        
        Development
        -----------
        
        Clone this repo
        
        ::
        
            git clone https://github.com/geckoboard/geckoboard-python && cd geckoboard-python
        
        Install package dependencies
        
        ::
        
            python setup.py develop
        
        Run tests
        
        ::
        
            nosetests
        
Keywords: geckoboard,datasets,api,python
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
