Pep 20: El Zen del Barça

image0 El Zen de Python es también el Zen del Barça, el de Pep Guardiola. La "Pep" 20 [1]:

Bello es mejor que feo. Explícito es mejor que implícito. Simple es mejor que complejo. Complejo es mejor que complicado. Plano es mejor que anidado. Disperso es mejor que denso. La legibilidad cuenta. Los casos especiales no son tan especiales como para quebrantar las reglas. Aunque lo práctico gana a la pureza. Los errores nunca deberían dejarse pasar silenciosamente. A menos que hayan sido silenciados explícitamente. Frente a la ambigüedad, rechaza la tentación de adivinar. Debería haber una —y preferiblemente sólo una— manera obvia de hacerlo. Aunque esa manera puede no ser obvia al principio a menos que usted sea Messi, Xavi o Iniesta. Ahora es mejor que nunca. Aunque nunca es a menudo mejor que ya mismo. Si la implementación es difícil de explicar, es una mala idea. Si la implementación es fácil de explicar, puede que sea una buena idea. Los espacios son una gran idea ¡Hagamos más de esas cosas!

Compartiendo documentación de paquetes python

Sabido es, aunque muchas veces se ignora, que un software sin documentación está incompleto [1].

Si bien el manifiesto ágil proclama "Software funcionando sobre documentación extensiva", yo subrayaría extensiva como eufemismo de documentación burocrática e inútil (opiné de esto acá) que evidentemente no es la que hace falta. Pero la documentación (sobre todo la buena) es indispensable y para algunos, la parte que más los enorgullece del proyecto (y con razón).

Desde el punto de vista técnico, escribir documentación (no sólo para Python!) es bastante fácil con restructuredText (qué feo el sitio de docutils, che!) que es el markup estándar de los pythonistas.

Sobre este markup funciona Sphinx, el generador de documentación más utilizado (por lejos) en el ecosistema de Python. Es lo que usa la documentación de Python misma, la de Django y casi todo proyecto conocido o por conocer.

Entonces usamos restructuredText, usamos Sphinx, pero para nuestro proyectito de morondanga que no tiene web propia ni nada, ¿dónde subimos la documentación generada? Veamos.

Usando Readthedocs.org

Read the docs es un sitio para hospedar documentación realizada con Sphinx. Sólo se necesita indicarle el repositorio público del proyecto (svn, git, mercurial, bazaar), subir los fuentes .rst y contenido estático (imágenes) aptos para Sphinx en una carpeta /doc o /docs y el sitio se encarga de bajar los fuentes de documentación y renderizarlos a HTML a través de Sphinx.

Estrictamente, usando rtfd.org (como le dicen los amigos) ni siquiera hace falta tener Sphinx instalado localmente.

System Message: WARNING/2 (<string>, line 31); backlink

Duplicate explicit target name: "acá".

Más aun, por defecto actualiza diariamente, pero se puede utilizar un "hook" para indicarle que actulice cuando "pusheamos" (o "commiteamos") al repo, de manera de tener la documentación actualizada al instante. Para usuarios de GitHub la activación del "web hook" se explica acá . Para BitBucket.org es parecido:

  1. Vas a tu proyecto , click en Admin -> Services
  2. Agregás el servicio "POST"
  3. Completás el campo de texto con la URL que te da ReadTheDocs en la página de descripción de tu proyecto (estándo logueado). Por ejemplo:

System Message: WARNING/2 (<string>, line 60)

Explicit markup ends without a blank line; unexpected unindent.

Y listo. Tu docu al instante.

Como el sitio genera el html en vez de servir una versión generada previamente, la documentación que requiere introspección del código ( todas las directivas `` .. auto* :: `` de Sphinx) este debe poder ejecutarse. Para eso el paquete debe ser instalable via setup.py y hay marcar desde la página de configuración del proyecto en RTFD.org, que instale en un virtualenv.

Para ver si hubo algún problema en la generación, podés fijarte en "build" donde te muestra el stdout y el stderr de la corrida de Sphinx.

Subir la docu a PyPi

Una forma buenísima de compartir tu trabajo pythónico es a través del Python Package Index, pypi, que es el índice que usan las herramientas pip e easy_install. Si bien no necesarimente los paquetes deben estar hospedados allí (indicando en el setup.py la URL de descarga) es muy común y fácil hacerlo con el comando upload del setup.py.

Lo que muchos no saben es que PyPi también ofrece hostear la documentación. La forma canónica es ir a la página de administración de tu proyecto en PyPi y adjuntar un .zip con la documentación (que no necesariamente tiene que ser hecha con Sphinx)

System Message: WARNING/2 (<string>, line 93)

Explicit markup ends without a blank line; unexpected unindent.

Pero si usamos Sphinx hay una manera más fácil, manteniendosé en el "ecosistema" de desarrollo: usar esta extension de setuptools que permite generar el html a través Sphinx y subirlo automáticamente. Se instala, obviamente, vía pypi:

$ easy_install sphinx-pypi-upload

Hay que condigurar un setup.cfg (ubicado al nivel raiz, junto con setup.py) indicandole dónde está la docu fuente y dónde el resultado. Más o menos así:

[build_sphinx]
source-dir = doc/source
build-dir  = doc/build
all_files  = 1

[upload_sphinx]
upload-dir = doc/build/html

Luego se usa:

$ python setup.py build_sphinx
$ python setup.py upload_sphinx

Y docu subida a la dire `http://packages.python.org/tu-proyecto <http://packages.python.org/tu-proyecto>`_ . ¡Charaaán!

Usando tu repositorio SVN

Si usas SVN y tu servidor lo permite, podés servir contenido estático (html y todo lo que produce y necesita Sphinx) directamente desde el repositorio.

Para que el servidor Subversion muestre el html renderizado en vez del código (como texto plano) hay que indicarle el tipo mime de cada archivo.

$ svn propset svn:mime-type 'text/html' FILENAME
$ svn propset svn:mime-type 'image/jpeg' FILENAME

Para que esto se haga automático, se puede modificar el archivo de configuración ``~/.subversion/config ``

System Message: WARNING/2 (<string>, line 144); backlink

Inline literal start-string without end-string.
[miscellany]
enable-auto-props = yes

[auto-props]
*.html = svn:mime-type=text/html
*.css = svn:mime-type=text/css
*.js = svn:mime-type=text/javascript
*.png = svn:mime-type=image/png
*.jpg = svn:mime-type=image/jpeg
*.gif = svn:mime-type=image/gif

Un ejemplo de esto es el reporte de mi proyecto integrador que está hospedado en Google Code

Aprovechándote de GitHub

GitHub hospeda páginas estáticas, tanto del desarrollador/a como de tus proyectos. Bien sirve eso para subir la documentación y eso hacen mas o menos automáticamente estas opciones que no he probado pero las dejo como referencia:

-Hosting sphinx doc in github de Luca Sbardella. image1Usando github-tools.

La sanguijuela de cuevana

UPDATE Hay una nueva versión con interfaz gráfica acá

Parece que se me hizo hobby chupar links de cuevana.tv y el experimento ahora tiene su versión pythonica: Cuevanalinks .

Es un pequeño proyecto que permite "conseguir links" de contenidos ofrecidos en cuevana, sirviendo estos como fuentes a manejadores de descargas como Tucan o JDownloader.

Más allá de los resultados, me ha tenido entretenido algunas horas y me permitió aprender (o al menos resolver) algunas cosas: cómo se usa mercurial (y en particular un merge conflictivo con Meld), cómo se escribe un setup.py, como se distribuye via PyPi, etc.

También, por supuesto, me permitió usar dos utilidades que me gustan mucho: PyQuery y plac.

La aplicación tiene dos módulos/componentes:

  1. Una biblioteca que intenta funcionar como API de Cuevana y es la encargada de scrappear la web en busca de la info interesante.
  2. Una interfaz de línea de comandos que permite buscar links y bajar subtitulos de contenidos específicos

System Message: WARNING/2 (<string>, line 37)

Explicit markup ends without a blank line; unexpected unindent.

Para qué sirve

Por ejemplo, para bajar la temporada 4 completa de Mad Men, con subtitulos, se podría hacer esto:

$ cuevanalinks 'mad men' s04 -s > madmen.txt && tucan -d -i madmen.txt

Instalación

Para instalarlo, basta con usar pip

$ sudo pip install cuevanalinks

O con easy_install:

$ sudo easy_install cuevanalinks

O bien, bajar el paquete y ejecutar :

$ tar xvfz CuevanaLinks-0.1.tar.gz
$ cd CuevanaLinks-0.1
$ sudo python setup.py install

Algunas posibilidades de la API

El CLI por ahora sólo expone una parte pequeña de la API, pero hay varias posibilidades. Por ejemplo:

>>> from cuevanalinks import cuevanaapi
>>> api = cuevanaapi.CuevanaAPI ()
>>> house = api.get_show ('house')
>>> house.plot
u'El doctor Gregory House, especialista en el tratamiento de enfermedades infecciosas, trabaja en un hospital universitario de Princetown, donde dirige una unidad especial encargada de pacientes afectados por dolencias extrañas y en la que colabora con un selecto grupo de aventajados ayudantes.'
>>> house7x1 = house.get_episode (7, 1)
>>> house7x1.title
'Now What?'
>>> house7x1.cast
['Hugh Laurie',
 'Lisa Edelstein',
 'Omar Epps',
 'Jesse Spencer',
 'Jennifer Morrison',
 'Robert Sean Leonard',
 'Olivia Wilde',
 'Peter Jacobson']
>>> house7x1.sources
['http://www.megaupload.com/?d=DM58TA0J',
 'http://www.filesonic.com/file/36841721/?',
 'http://bitshare.com/?f=67z435xm',
 'http://www.filefactory.com/file/caf85b9']
>>> house7x1.subs
{'ES': 'http://www.cuevana.tv/download_sub?file=s/sub/7888_ES.srt'}

Lo que falta

Si bien es lo más prolijito que he hecho, todavía está lejos de ser un trabajo completo, tanto en funcionalidades como en SQA

Un aspecto esencial es hacer test (perdón Nati Bidart ;-) ), para lo cual tengo que aprender a usar nose y minimock.

Respecto a funciones, algo importante es definir cómo resuelve el CLI el manejo de múltiples resultados para una búsqueda. Actualmente devuelve el resultado "más relevante" sin anoticiar al usuario de otras opciones.

También falta documentación! Veremos la próxima.

Comentarios, sugerencias, bugs

Todo aporte (ideas, código, etc.) es bienvenido. Si encuentran problemas, reportenlos.

No estoy seguro cuánto puede durar esto funcionando, ya que depende de que el funcionamiento del sitio no cambie o yo tenga mucho tiempo y ganas de andar parchando detrás. Por eso, si hay más interesados y usuarios, seguramente podremos hacerlo durar más.

Veinteañero

Suse 7.0 fue la primera distro Linux que mi gloriosa Pentium II cobijó. Al tiempo usé Mandrake, después Debian y desde su primera versión (2004) Ubuntu.

Un largo camino de aprendizaje... que alguna vez recorreré ;-)