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!
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).
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.
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:
Vas a tu proyecto , click en Admin -> Services
Agregás el servicio "POST"
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:
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)
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í:
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.
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:
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.
$ 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.
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é ;-)
La manera más fácil para aprobar una tesis de ingeniería es mentir.
Llenar páginas y páginas, preferentemente con tablas y viñetas, de
contenidos vacuos y tediosos que seguramente nadie, mucho menos los
evaluadores, leerán. Sólo hay que prestar atención a que sean muchas
páginas y lo más simétricas posibles.
Pero también el UML, me atrevo a decir, en su mayor parte y nivel de
detalle es secuaz de esta ignominia que pauperiza el nivel del software
académico: en vez de saber programar y poder leer código, se presta
atención a los dibujitos, poniendo el grito en el cielo si la flechita
es negra en vez de blanca, como dice
Sommerville
que debe ser.
Como no me gusta mentir, la facilidad no me seduce de más (tampoco la
dificultad) y estoy bastante conforme con lo que
hice me animé a ser sensato en
expresar cómo hice mi trabajo.
No me encerré 6 meses a hacer dibujitos que resultarían perfectos,
inescrutables y luego harían la programación trivial. Eso, al menos en
mi experiencia, no existe (sospecho que ellos todos lo saben, lo que
exacerba la hipocresía). Sí, en cambio, hice algunos dibujitos que me
ayudaran a entender (y dar a entender) cómo iba la cosa, mientras iba
programando y evaluando si estaba bien encaminado.
Este espíritu es el que cobijan las prácticas
ágiles, que es el marco conceptual
(metodológico) que adopté.
La cuestión es que, para ganarle al unknow how de los hombres de
corbata, hay que justificar con nombres que les suenen admirables. Hay
que mencionar mucho IBM, Microsoft, C#, Intel. Esas son las voces que
respetan, aunque sean pura
falacia
Aunque sigas un proceso ágil, estarás realizando cierto grado de
modelado – sólo que no lo realizarás tanto como si utilizaras un
proceso tradicional. La falta de formalidad en el modelado ágil
no significa que no estás modelando, sino que te pones el foco
en los beneficios de este sin las desventajas y confusiones de
documentos extraños y burocráticos.
Por su parte, Robert Martin sostiene en *Agile Principles,
Patterns, and Practices in
C#*
que el modelado basado en UML en el desarrollo ágil es útil como
instrumento de comunicación, pero su detalle no aporta valor
significativo:
No gastes mucho tiempo en esta tarea, no necesitas tanto
detalle. Los modelos y los planos son necesarios en la
arquitectura y la construcción civil porque es caro construir
una casa para demostrar que su diseño funciona. El software no
es así – puedes validar tu idea con sólo codificarla, en igual
tiempo que el que insume hacer un modelo UML que nada prueba por
sí mismo.
Aun más escéptico, Alans Stevens, reconocido ingeniero en software
[1] y
conferencista, opina en un
artículo:
No uso UML y noto que ninguno de mis colegas lo usa. Tengo
sensaciones mezcladas acerca de su necesidad. Parece
perfectamente razonable que debamos acordar como industria un
conjunto de símbolos comunes para representar la programación
orientada a objetos, pero UML tiene la típica apariencia de
"diseñado por un comité".
(...) El aspecto más crítico en un diseño inicial, en mi
experiencia, es la interfaz entre la UI y el modelo de objetos.
Lamentablemente UML no aborda este problema y en cambio parece
obsesionado por las minucias en una parodia de distracción
académica.
El Zen de Python es
también el Zen del Barça, el de Pep Guardiola. La "Pep" 20
[1]:
