Preciosa DocumentationPublicación dev

Martín Gaitán y colaboradores

02 de October de 2016

Índice general

1. A modo de intro 3

2. Índice 52.1. Instalación de la plataforma . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2. Arquitectura . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.3. La API de Preciosa . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.4. Tutorial de uso de la aplicación móvil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.5. Preguntas Frecuentes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.6. Glosario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.7. Licencia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3. Preciosa en los medios 15

4. Indices and tables 17

I

II

Preciosa Documentation, Publicación dev

Preciosa es una plataforma web colaborativa con aplicaciones para teléfonos inteligentes que facilita el relevamientode precios y ayuda a encontrar mejores ofertas.

A diferencia de otras aplicaciones existentes, Preciosa no limita la información a precios de productos bajo acuerdo yenfatiza la participación de los usuarios para mantener la información actualizada.

issue tracker https://github.com/mgaitan/preciosa/issues

twitter @PreciosaApp

lista https://groups.google.com/forum/#!forum/preciosa-devs

estado

email Martín Gaitán <gaitan@gmail.com>

Índice general 1

Preciosa Documentation, Publicación dev

2 Índice general

CAPÍTULO 1

A modo de intro

(...) Entran a un super, agarran el paquete de harina, le sacan una fotito con su cámara al código de barra(o buscan el producto por nombre, marca, etc.) y la app les dice cuál es el precio de referencia (o delacuerdo), en qué super cercano está más barato, cuándo y cuánto aumentó, etc.

Idea original

Repercusión y primeros pasos

3

Preciosa Documentation, Publicación dev

4 Capítulo 1. A modo de intro

CAPÍTULO 2

Índice

2.1 Instalación de la plataforma

Preciosa es una aplicación web basada en Django y Geodjango. Como depende de una base de dato espacial (enparticular, usamos PostGis) y de muchos otros componentes, no es trivial (pero tampoco difícil) armar un entorno dedesarrollo.

Por ello, la manera recomendada es utilizar docker

1. Forkear y clonar el código del repositorio

2. Instalar docker-compose de la manera correspondiente y conveniente a tu sistema operativo.

3. Construir el contenedor ejecutando docker-compose build web.

4. Inicializar la base de datos docker-compose run web ./initialize.sh

ya podés empezar a programar!

Para “levantar” el contenedor de preciosa bastará hacer docker-compose up. Tu servidor de desarrollo quedarádisponible en http://localhost:8000

Atención: Recordá que para correr cualquier comando dentro del contenedor debés precederlo condocker-compose run web Por ejemplo, para ejecutar el shell de django:

docker-compose run web python manage.py shell

2.2 Arquitectura

2.2.1 Modelo de base de datos

Los modelos fundamentales de Preciosa se definen en la aplicación precios</preciosa/precios/models.py>. Un diagrama simplificado es el siguiente:

2.2.2 Algoritmos de “precios”

Como se observa, el relevamiento de un precio está asociado a un producto y a una sucursal específica (y, opcional-mente, a un usuario), además de su fecha de relevamiento.

5

Preciosa Documentation, Publicación dev

Al ser improbable la existencia de precios para cualquier producto en todas las sucursales, la consulta del precio deun producto para una sucursal en particular se realiza a través del método PrecioManager.mas_probables(),que realiza un degradado de información:

1. Si existe un precio relevado para el producto en la sucursal, dentro del rango de máximo de dias, se devuelveese dato

2. En caso de que no exista, se buscan precios para el producto en sucursales de la misma cadena o un radiodefinido.

3. Si no hay precios en Sucursales, se buscan el precio del producto en la “Sucursal Online” de la Cadena.

4. Si no hay sucursal online asociada o no existe un precio vigente, no se devuelve un resultado.

def mas_probables(self, producto, sucursal, dias=None, radio=10):"""Cuando no hay datos especificos de unproducto para una sucursal (:meth:`PrecioManager.historico`),debe ofrecerse un precio más probable. Se calcula

- Precio más nuevo para el producto en otras sucursalesde la misma cadena en la ciudad y/o un radio de distancia si es dado

- En su defecto, precio online de la cadena"""qs = self.historico(producto, sucursal, dias)if len(qs) > 0:

return qs

qs = super(PrecioManager, self).get_queryset()

# precios para sucursales de la misma cadena de la ciudadcercanas_ciudad = sucursal.cercanas(misma_cadena=True).values_list('id',

flat=True)if radio:

cercanas_radio = sucursal.cercanas(radio=radio,misma_cadena=True).values_list('id',

flat=True)else:

cercanas_radio = []

cercanas = set(list(cercanas_ciudad) + list(cercanas_radio))qs = qs.filter(producto=producto,

sucursal__id__in=cercanas).distinct('precio')if qs.exists():

return self._registro_precio(qs)

qs = super(PrecioManager, self).get_queryset()qs = qs.filter(producto=producto,

sucursal__cadena=sucursal.cadena,sucursal__online=True).distinct('precio')

# precios onlineif qs.exists():

return self._registro_precio(qs)return []

Análogamente se calculan los mejores precios. Dado un producto, una ubicación (o sucursal) y radio de distancia, seobtiene una lista de los mejores precios en la zona para ese producto.

6 Capítulo 2. Índice

Preciosa Documentation, Publicación dev

def mejores(self, producto, ciudad=None, punto_o_sucursal=None,radio=None, dias=None, limite=5):

"""devuelve una lista de instancias Precio para el producto,ordenados por menor precio (importe) paraun determinado producto y un radio de distancia o ciudad.

Sólo considera el último precio en cada sucursal."""

#si tiene puto.. tenemos que tener el radioif punto_o_sucursal and not radio:

raise ValueError('Si se especifica el punto o sucursal debe proveer el radio')

if radio and not punto_o_sucursal and not ciudad:raise ValueError(

'Si se especifica el radio debe proveer el punto o sucursal')

#si no tenemos una ciudad o un punto con radioif not ciudad and not radio:

raise ValueError('Debe proveer una ciudad o un radio en kilometros')

qs = super(PrecioManager,self).get_queryset().filter(producto=producto, activo__isnull=False)

if dias:desde = timezone.now() - timedelta(days=dias)qs = qs.filter(created__gte=desde)

if ciudad:if isinstance(ciudad, City):

ciudad = ciudad.idqs = qs.filter(sucursal__ciudad__id=ciudad).distinct(

'sucursal')[:limite]elif radio:

if isinstance(punto_o_sucursal, Sucursal):punto = punto_o_sucursal.ubicacion

else:punto = punto_o_sucursal

cercanas = Sucursal.objects.filter(ubicacion__distance_lte=(punto,D(km=radio)))

cercanas = cercanas.values_list('id', flat=True)qs = qs.filter(sucursal__id__in=cercanas).distinct(

'sucursal')[:limite]

if qs.exists():return sorted(qs, key=lambda i: i.precio)

return []

2.3 La API de Preciosa

Atención: La API está en plena fase de diseño e implementación. Puede cambiar sin previo aviso

2.3. La API de Preciosa 7

Preciosa Documentation, Publicación dev

2.3.1 Breve intro a Django Rest Framework

La API REST de Preciosa está implementada con Django Rest Framework (DRF) Hay 3 módulos que importan

serializers.py

views.py

urls.py

El primero define los serializadores, conceptualmente análogos a un formulario, que dado un objeto (en general, unainstancia de un Modelo), define las reglas de como debe mostrar los atributos en un formato de representación (comoJSON) o, en sentido inverso, como debe recontruir un objecto a partir de una representación.

El segundo módulo define las “vistas”, que son similares a las de Django (aunque el objeto Response que usa laAPI es ligeramente distinto). Para los casos de uso más comunes se pueden usar Class Based View (análogasa las CBV de Django, que saben listar, mostrar, crear, etc. objetos/instancias de modelos) o una abstracciín aún másgeneral denominada ViewSet, que puede pensarse como una factory de Class Based Views: un Viewset para unmodelo, ya sabe hacer todos los casos comunes y, como yapa, mediante un Router, nos genera automáticamenteuna estructura de urls tipicas. Por último, puede definirse una vista tipica como función, decorada con el decorador deDRF @api_view

Las urls son iguales a las de cualquier aplicación Django, salvo por la utilización opcional de un router (una factoryde URLs).

Preciosa utiliza una mezcla de todas las posilidades de que brinda DRF.

Por ejemplo, los endpoints para modelos simples como Cadena (Walmart, Disco, etc), utilizan ViewSets, algunoslistados/detalles como el del modelo Producto (que puede accederse en general o para una sucursal en particular)usa CBVs y la vista de detalle para productos (en una sucursal) usa una vista basada implenentada como funcióndecorada.

Advertencia: DISCLAIMER: Estamos aprendiendo a usar este framework sobre la marcha. Si tenés ideas decómo mejorar, recomendaciones, etc. estaremos contentos de recibirlas.

2.3.2 Autenticación básica basada en token

La API de preciosa utiliza una manera muy simple y opcionalmente anónima de autenticación. El motivo de usarautenticación es para prevenir/aminorar el vandalismo y el uso desleal de los recursos.

Cada usuario está asociado a un token. Registrar un usuario para obtener un token es muy fácil. Basta hacer un POSTal enpoint

http://preciosdeargentina.com.ar/api/v1/auth/registro

Opcionalmente la petición puede enviar esta información

uuid un identificador único del equipo (ejemplo, el movil)

nombre un nombre elegido por el usuario para el equipo

plataforma la plataforma subyacente (ejemplo: “Android”)

phonegap si el cliente es Phonegap, la versión.

plataforma_version la versión de la plataforma (ejemplo “2.2” para Android)

preciosa_version la versión del cliente de preciosa.

Los parámetros no son obligatorios, pero cualquiera subconjunto que se envie debe incluir el uuid (sin uuid ningunainformación quedará guardada)

8 Capítulo 2. Índice

Preciosa Documentation, Publicación dev

Obtenido el token, este debe enviarse para cada subsecuente petición. Puede hacerse configurando el un header HTTP.Por ejemplo

Authorization: Token XXXXX

Donde XXXX es el token dado.

Desde jQuery, puede configurarse para todas las peticiones ajax

$.ajaxSetup({headers: {'Authorization': "Token XXXXX"

}});

Alternativamente, se puede enviar un token como parámetro en el QUERY de la URL. Por ejemplo:

api/v1/<end_point>/?token=XXXX

Si ya se cuenta con un usuario y contraseña (por ejemplo un Voluntario registrado via web) se puede obtener un tokenenviando parámetros usuario y password al recurso

http://preciosdeargentina.com.ar/api/v1/auth/token

Devuelve el token en formato json de igual manera que /auth/registro

2.3.3 ¿Qué se puede hacer?

Como DRF ofrece una versión HTML del contenido de la API, gran parte de los recursos que la API de preciosaofrece pueden autodescubrirse navegando desde la raiz.

http://preciosdeargentina.com.ar/api/v1/

2.3.4 Otros recursos

Detalle de una sucursal http://preciosdeargentina.com.ar/api/v1/sucursales/<pk>

Listado de productos con precios conocidos en una sucursal http://preciosdeargentina.com.ar/api/v1/sucursales/<pk>/productos

Es igual que http://preciosdeargentina.com.ar/api/v1/productos, pero filtra aquellos pro-ductos en los que para esa sucursal hay precios conocidos.

Detalle de producto para una sucursal en particular http://preciosdeargentina.com.ar/api/v1/sucursales/<pk>/productos/<pk_producto>

Este recurso devuelve un detalle exhaustivo de los precios probables y los mejores para una zona, incluyendosucursales asociadas a esos mejores precios.

2.3.5 Filtros

El listado de productos (http://preciosdeargentina.com.ar/api/v1/productos) puede recibir los siguientes parámetrosopcionales via GET

q cadena a buscar. Usa el criterio definido en Producto.objects.buscar (es decir, dará los mismos resultadosque el buscador de la web). Por ejemplo, puede ser un conjunto de palabras claves o un código de barras(completo o los primeros números desde la izquierda).

limite cuantos resultados mostrar para el criterio

pk limita la busqueda a un PK de producto en particular

2.3. La API de Preciosa 9

Preciosa Documentation, Publicación dev

El listado de sucursales (http://preciosdeargentina.com.ar/api/v1/sucursales) puede recibir los siguientes parámetrosvia GET

q cadena a buscar. Por ejemplo, nombre de ciudad, cadena, o calle.

lat, lon y radio: una posición y el radio en kilometros que determina las zona donde se buscan sucursales. Estosparámetros son interdependientes.

El listado de Ciudades (http://preciosdeargentina.com.ar/api/v1/ciudades) puede recibir los siguientes paráme-tros via GET:

q cadena a buscar. Por ejemplo, nombre de ciudad o provincia.

2.3.6 Formatos

DRF sabe interpretar el content-type preferido en el encabezado de la petición HTTP. Alternativamente puededefinirse mediante el parámetro format en la URL del recurso. Por ejemplo

http://preciosdeargentina.com.ar/api/v1/cadenas/?format=json

Forzará el serializado de la lista de cadenas en formato JSON, aun desde un navegador web que acepta HTML.

2.3.7 Tasas de limitación (throttling)

Complementario a la autenticación, la API tiene un sistema de limitación de peticiones (throttling), para evitar el abusode usuarios malintencionados.

Actualmente las tasas son:

30 peticiones por dia para usuarios anónimos. Actualmente permite acceder a la URL /auth/registro

40 peticiones por minuto para usuarios autorizados. Es para evitar los picos de peticiones automatizadas.

1000 peticiones por dia para usuarios autorizados. Es para evitar el “leeching”.

2.4 Tutorial de uso de la aplicación móvil

Preciosa tiene un cliente para dispositivos móviles. Esta es una guía de uso de la versión actual.

2.4.1 Instalación

Nuestra intención es que Preciosa sea muy fácil de usar y funcione en la mayor cantidad de teléfonos posi-ble. Existe una aplicación descargable desde Google Play para teléfonos con Android 2.1 o superior. Otrasplataformas o dispositivos pueden acceder a una versión simplificadada para el navegador web desde la urlhttp://mobile.preciosdeargentina.com.ar [1]_.

2.4.2 Paso 1: elegir tu sucursal

Una vez que instalaste la aplicación, el primer paso es elegir la sucursal de supermercado en la que estás (o querésconsultar precios).

Hay tres maneras de elegir una sucursal:

Buscar por palabras clave. Por ejemplo, podés buscar el nombre de la cadena y la calle, o intentar con elnombre de tu barrio y tu ciudad.

10 Capítulo 2. Índice

Preciosa Documentation, Publicación dev

Elegir una sucursal que ya elegiste antes.Esta es la opción “Recientes”. Se van guardando las sucursales quemás frecuentemente elegís, para facilitar la búsqueda.

O podés buscar sucursales cercanas.Esta es una función experimental que utiliza geolocalización, es decir,intenta detectar tu ubicación y te da un listado de las sucursales conocidas más cercanas. Si estás en un super, laprimera que aparece debería ser aquella en la que estás.

Si creés que no te detecta correctamente la ubicación, poder

corregirla con el botón Configurar Ubicación que sale al pie de de la solapa, y eligiendo tu ubicación correctaen el mapa.

¿No aparece la sucursal que buscás? ¡Cargala desde el panel de voluntarios!

2.4.3 Paso 2: Buscar productos

Una vez que encontraste la sucursal que buscabas, podés consultar productos.

Las opciones son: usar el buscador de palabras claves, o, sí tu teléfono tiene una buena cámara, usar el lector decódigo de barras. Tenés que tener en cuenta que aun si no te funciona el lector de códigos, podés buscar ingresandolos primeros números que aparecen bajo el código del producto. (¡Como hacen las cajeras!).

Actualmente conocemos más de 30mil productos (aunque todavía no sabemos los precios de todos). Si buscás unproducto específico que te parece muy importante que esté y no aparece, por favor avisanos.

2.4.4 Paso 3: ¡Comparar los precios!

Una vez que encontraste el producto que buscabas, haciendo click verás los detalles. Preciosa intenta decirte cuál es elprecio más probable que conoce para la sucursal en la que estás(que elegiste en el paso 1) y te pide que la confirmeso la corrijas, con los botones SIoNO.

Este paso es la esencia de Preciosa. Cuando vos actualizás un precio estás ayudando a todos los que consulten porese producto más adelante. Te pedimos que seas solidario y envíes información fidedigna. ¡Acá está la inteligenciacolectiva contra la inflación!

Una vez que enviaste el precio que estás viendo en la góndola, ¡verás los mejores preciosque Preciosa conoce (graciasa los usuarios) en otros supermercados cercanos! Si sabés los precios para ese mismo producto, podés saber si teconviene o no comprarlo donde estás.

**

¿Te gusta la idea?

¡Buenísimo! Queremos hacer de Preciosa una herramienta útil para defender el bolsillo de todos los argentinos. Tene-mos muchas ideas y funciones nuevas, pero necesitamos ser miles usando Preciosa. ¡Ayudanos a difundir!

2.5 Preguntas Frecuentes

2.5.1 ¿En qué lenguaje está programado Preciosa?

La aplicación web (sitio + API) se basa en el framework Django_, programado principalmente con Python_. Para laAPI rest usamos ‘Django Rest Framework‘_

2.5. Preguntas Frecuentes 11

Preciosa Documentation, Publicación dev

2.5.2 ¿Puedo ayudar en las aplicaciones móviles?

Por supuesto. El respositorio está acá. La aplicación cliente es común para las distintas plataformas está basada enHTML5 y javascript utilizando Phonegap_

2.5.3 Quiero ayudar, ¿cómo hago?

En primer lugar, ¡muchas gracias por eso! Primero anotate en la lista de correo de colaboradores. Luego fijate cómotrabajamos.

2.5.4 ¿Cómo trabajamos?

En general tenemos milestones <https://github.com/mgaitan/preciosa/issues/milestones>, es decir, conjuntos de tareasprioritarias para los objetivos de corto plazo.

Preciosa tiene algunos desarrolladores “core-committers” pero recibe activamente código de la comunidad a través depull requests.

Proponé tus ideas o preguntá qué es prioritario hacer en la lista de correo. Luego hacés un fork y pull request (contrala rama develop) de tus aportes!

Si encontrás bugs, reportalos en el ‘issue tracker‘_.

2.5.5 ¿Por qué programan y documentan en español?

Preciosa comenzó como un proyecto particularmente orientado a Argentina, donde el problema del aumento de preciosafecta cada vez más el poder adquisitivo de la población. No sólo se trata de construir una plataforma colaborativa,sino que el propio desarrollo del proyecto se realiza de manera abierta a la comunidad.

En este contexto, la idea fue ampliar la base de potenciales colaboradores de Argentina (y Latinoamérica), rompiendola barrera de la limitación idiomática.

Sabemos y aceptamos que la lengua franca en el software es el inglés, pero creemos que esta excepción, por ahora, esválida.

2.6 Glosario

EAN, UPC distintos tipos de códigos de barras.

Scrapping Web Scraping es una técnica utilizada mediante programas de software para extraer información desitios web. Usualmente, estos programas simulan la navegación de un humano en la World Wide Web ya seautilizando el protocolo HTTP manualmente, o incrustando un navegador en una aplicación como puede serInternet Explorer o Mozilla Firefox.

JSON acrónimo de JavaScript Object Notation, es un formato ligero para el intercambio de datos. JSON es unsubconjunto de la notación literal de objetos de JavaScript que no requiere el uso de XML.

2.7 Licencia

Por las virtudes técnicas y ventajas estratégicas que aporta, el desarrollo de Preciosa es Software Libre, basado en lalicencia AGPL.

12 Capítulo 2. Índice

Preciosa Documentation, Publicación dev

Podés leer el hilo de discusión en la lista de correo donde se discutió el tema.

Además, el desarrollo abierto y comunitario, donde las ideas se discuten públicamente. Gracias a esta transparencia yla empatía con el fin social del proyecto, decenas de voluntarios han colaborado ad honorem.

Gracias a ser También recibimos la colaboración y apoyo del equipo técnico de Huayra Linux, el sistema operativo libredel programa Conectar Igualdad. A partir de la versión 2.0, Huayra incluye a Preciosa como una de sus aplicacionesdestacadas.

2.7.1 Términos

Podés leer el texto completo de la licencia en el sitio de GNU.

Preciosa, software colaborativo para relevar precios y encontrar mejores ofertasCopyright (c) 2014 Martín Gaitán and contributors.

This program is free software: you can redistribute it and/or modifyit under the terms of the GNU Affero General Public License as published bythe Free Software Foundation, either version 3 of the License, or(at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See theGNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public Licensealong with this program. If not, see <http://www.gnu.org/licenses/>.

2.7. Licencia 13

Preciosa Documentation, Publicación dev

14 Capítulo 2. Índice

CAPÍTULO 3

Preciosa en los medios

Durante febrero de 2014 (cuando retomamos el proyecto, iniciado originalmente en junio de 2013) Preciosa, aún endesarrollo, tuvo muchísima repercusión en los medios:

Entrevista en Radio Nacional

Entrevista en Radio Madres/Universidad de Córdoba

Nota en Agencia Télam.

Entrevista en Canal 10 de Córdoba

Y muchísimas aparaciones más.

15

Preciosa Documentation, Publicación dev

16 Capítulo 3. Preciosa en los medios

CAPÍTULO 4

Indices and tables

genindex

modindex

search

17

Preciosa Documentation, Publicación dev

18 Capítulo 4. Indices and tables

Índice

EEAN, 12

JJSON, 12

SScrapping, 12

UUPC, 12

19