Metadata-Version: 2.1
Name: togglwrapper
Version: 1.2.1
Summary: UNKNOWN
Home-page: https://github.com/aarose/togglwrapper
Author: aarose
License: MIT
Keywords: toggl timetracking API wrapper
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Requires-Dist: requests
Provides-Extra: dev
Requires-Dist: requests (==2.20.0) ; extra == 'dev'
Requires-Dist: wheel (==0.24.0) ; extra == 'dev'
Requires-Dist: cookies (==2.2.1) ; extra == 'dev'
Requires-Dist: coverage (==3.7.1) ; extra == 'dev'
Requires-Dist: mock (==1.3.0) ; extra == 'dev'
Requires-Dist: pbr (==1.6.0) ; extra == 'dev'
Requires-Dist: responses (==0.4.0) ; extra == 'dev'
Requires-Dist: six (==1.9.0) ; extra == 'dev'

=============
Toggl Wrapper
=============

Python library to easily interface with Toggl's API.

Implements all of Toggl's main API. The Reports API is not yet supported (coming soon).

Works in Python 2.7+ and Python 3+, and uses `requests <http://www.python-requests.org/en/latest/>`_.


-----
Toggl
-----

`Toggl <https://www.toggl.com>`_ is free time tracking software.

--------
Features
--------
- Handles authentication for you: only need to provide your API token once
- The most complete Python wrapper: implements all of v8 API.
- Convenient install from PyPI
- Easy to make requests to custom URLs
- Python2 and Python3 compatible

-------
Install
-------

.. code-block:: bash

    $ pip install togglwrapper


----------
Quickstart
----------

.. code-block:: python

    >>> from togglwrapper import Toggl
    >>> toggl = Toggl('your_api_token')``
    >>> toggl.User.get()
    {u'data': {u'achievements_enabled': True,
    u'api_token': u'your_api_token',
    u'email': u'your_email@domain.com',
    u'fullname': u'Your Name',
    ...
    }
    >>> toggl.Clients.get()
    [{u'at': u'2015-07-02T14:27:59+00:00',
    u'id': 12031893,
    u'name': u'Client Name',
    u'wid': 3928}]
    >>> toggl.Workspaces.get()
    [{u'admin': True,
    u'api_token': u'your_api_token',
    u'id': 1234,
    u'name': u"Your workspace",
    ...
    }]
    >>> toggl.Clients.create({"client":{"name":"Very Big Company", "wid": 1234}})
    {u'data': {u'id': 294021, u'name': u'Very Big Company', u'wid': 1234}}

--------------
Custom Request
--------------

Let's pretend that a new endpoint is released, for a new Toggl object: Addresses. This hypothetical endpoint is located at ``https://www.toggl.com/api/v8/addresses``. We can GET all addresses, GET a specific address by ID, or POST to create a new address.

We can use the methods on the Toggl client, so we don't have to wait for a new version of togglwrapper that supports the new endpoint:

.. code-block:: python

    >>> from togglwrapper import Toggl
    >>> toggl = Toggl('your_api_token')
    >>> toggl.get('/addresses')
    ...
    >>> toggl.get('/addresses/{address_id}')
    ...
    >>> toggl.post('/addresses', data={"address": {"name": "Billing Address 1", "address": "123 Main St."}})
    ...


``toggl.put`` and ``toggl.delete`` are also available.


-------------------
Documentation
-------------------
Find the full documentation here: http://togglwrapper.readthedocs.org/en/latest/


---------------------------
API Endpoints Documentation
---------------------------

For full details on what fields are required, and what endpoints are available, see the `Toggl API docs <https://github.com/toggl/toggl_api_docs>`_


---------------------------
Running tests locally
---------------------------

Using `virtualenv <https://virtualenv.pypa.io/en/stable/>`_ + `virtualenvwrapper <https://pypi.org/project/virtualenvwrapper/>`_ to keep the environment isolated:

1. Create a testing virtualenv
2. Install the test requirements
3. `python tests.py`

Sample command line output:

.. code-block::

    $ mkvirtualenv twtests  # if creating the virtualenv for the first time
    Running virtualenv [...]
    [...]
    (twtest) $ pip install -r test-requirements.txt
    Collecting [...]
    [...]
    (twtest) $ python tests.py
    .......................................................
    ----------------------------------------------------------------------
    Ran 55 tests in 0.414s

    OK
    (twtest) $ deactivate
    $



