Obteniendo sus tiempos de Toggl con la biblioteca Python-toggl

Toggl es uno de los mejores rastreadores de tiempo en el mercado. Es simple, fácil de aprender y confiable. Hemos estado usando esta herramienta en Swapps durante más de tres años y siempre ha sido útil. Gracias a ello, nuestro rendimiento ha mejorado significativamente.

Durante uno de nuestros proyectos internos, necesitábamos obtener información de toggl e integrarla con nuestro sistema. Fue entonces cuando empezamos a trabajar con python-toggl; puede encontrar el código del módulo en Github. Python-toggl le permite obtener información de espacios de trabajo, proyectos y entradas de tiempo sin esfuerzo; reduciendo repeticiones y facilitando el proceso de desarrollo. Veamos qué fácil es usar este paquete.

Primero, vamos a instalarlo simplemente ejecutando

pip install python-toggl

Luego, configuremos el Cliente

from toggl.api_client import TogglClientApi

configuration = {
    'token': "My Secret Token",
    'user_agent': 'swapps',
    'workspace_id': "XXXYYY"
}
client = TogglClientApi(configuration)

¡Y eso es todo!

Ahora, obtengamos nuestros proyectos registrados.

In [1]: client.get_projects().json()                                            
Out[1]:
[{'active': True,
  'actual_hours': 10,
  'at': '2019-01-01T12:00:00+00:00',
  'auto_estimates': False,
  'billable': True,
  'cid': 12345678,
  'color': '8',
  'created_at': '2019-01-01T12:00:00+00:00',
  'hex_color': '#3750b5',
  'id': 12345678,
  'is_private': False,
  'name': 'Test project',
  'template': False,
  'wid': 123456}]

Como puede ver, devuelve una lista con el detalle de todos nuestros proyectos registrados. Incluso devuelve los proyectos inactivos. También devuelve información útil, como la identificación del proyecto, que necesitaremos para obtener sus tiempos, la fecha y hora de creación, etc.

Ahora, obtengamos a todos los miembros de nuestro equipo. Esta característica es útil si desea obtener información de tiempo por miembro del equipo en lugar de por proyecto.

In[2]: members = client.get_workspace_members("my-workspace-id")
In[3]: members.json()
Out[3]:
[{'active': True,
 'admin': False,
 'at': '2019-01-01T00:00:00+00:00',
 'avatar_file_name': 'https://assets.toggl.com/avatars/f98355dfadcc3aac9de3851bca88b2c4.png',
 'email': '[email protected]',
 'group_ids': [123],
 'id': 123,
 'inactive': False,
 'invitation_code': None,
 'invite_url': None,
 'labour_cost': None,
 'name': 'Jose',
 'owner': False,
 'rate': None,
 'timezone': 'America/New_York',
 'uid': 123,
 'wid': 123}]

Como puede ver, devuelve una lista de todos los miembros dentro de su equipo con su información más importante, como su ID, correo electrónico, nombre, etc.

Ahora, consigamos el elemento más importante en toggl: tiempos. El método relacionado requiere la identificación del proyecto toggl y el rango de fechas que desea recuperar. ¡Vamos a ver el código!

In [4]: from datetime import date                                              
In [5]: start_date = date(2019, 1, 1)                                           
In [6]: end_date = date(2019, 1, 31)
# the id '12345678' is obtained from the get_projects method
In [7]: client.get_project_times('12345678', start_date, end_date)
Out [7]:
{'data': [{'billable': None,
   'client': 'Test Client',
   'cur': None,
   'description': "This is my first tracked time!",
   'dur': 1526000,
   'end': '2019-01-21T09:00:35-05:00',
   'id': 12345,
   'is_billable': True,
   'pid': 12345678,
   'project': 'Test project',
   'project_color': '0',
   'project_hex_color': '#06aaf5',
   'start': '2019-01-21T08:35:09-05:00',
   'tags': [],
   'task': None,
   'tid': None,
   'uid': 123,
   'updated': '2019-01-21T09:00:45-05:00',
   'use_stop': True,
   'user': 'Jose Ariza'}],
 'per_page': 50,
 'total_billable': 1526000,
 'total_count': 1,
 'total_currencies': [{'amount': None, 'currency': None}],
 'total_grand': 1526000}

El método devuelve una lista con todas las entradas de tiempo encontradas para el proyecto requerido entre start_date y end_date. Cada entrada de tiempo contiene información como su hora de inicio y finalización, su duración, el usuario que la creó, su ID (uid), etc. Además, devuelve cuántas entradas de tiempo hay, cuántas entradas de tiempo se devuelven por página, cuánto tiempo es facturable, etc. Puede encontrar la referencia de datos completa aquí.

Además, si necesita usar el método con parámetros adicionales, por ejemplo, el número de página o la identificación del usuario, puede usarlo así:

In [8]: client.get_project_times('12345678', start_date, end_date, extra_params={"page": 2})

Puede encontrar una guía completa de parámetros aquí.

Hay una pequeña limitación con este criterio de valoración: Toggl no permite rangos superiores a un año. Entonces, si necesita recuperar la información de varios años, necesitaría usar este método dentro de un ciclo; enviando una solicitud por año requerido.

¡Y eso es todo! en menos de diez líneas, pudimos obtener información muy útil de nuestra cuenta de Toggl sin esfuerzo. Si va a utilizar el cliente en un proyecto más grande, le recomiendo encarecidamente que use una clase para encapsularlo junto con su integración para mantener todo bajo control.

Espero que esta publicación le haya sido útil y que haya podido comenzar a mejorar su trabajo a partir de los datos obtenidos de Toggl. ¡Feliz codificación!