Merge branch 'feat/06_main'

Author: Esteban Echeverry

docs/_static/.gitinclude

@@ -10,37 +10,102 @@ mantener en el tiempo.
 SOLID
 *****
 
-- S-ingle Responsability Principle
+- **S-ingle Responsability Principle**
 
-Cada componente del sistema debería tener una única reponsabilidad.
+    *Un módulo debería tener una, y sólo una, razón para cambiar*
 
-- O-pen/Closed Principle
+    *Un módulo debería ser responsabilidad de un sólo actor*
 
-Abierto para extensión, cerrado para modificación.
+.. todo::
+   Ejemplo de clase "Empleado" con métodos calculatePay (CFO),
+   reportHours (COO) y save (CTO)
 
-- L-iskov Substitution Principle
 
-- I-nterface Segregation Principle
+- **O-pen/Closed Principle**
 
-- D-ependency Inversion Principle
+    *Un artefacto de software debería estar abierto para su extensión
+    pero cerrado para su modificación*
+
+.. todo::
+   Esto impacta como estructuramos los componentes de nuestras aplicaciones,
+   para dirigir las *dependencias* eficientemente. Se trata sobre todo de
+   evitar ciclos de dependencias y de proteger aquellos componentes que cambian
+   con menos frecuencia y son más abstractos (i.e. son de más alto *nivel*).
+
+- **L-iskov Substitution Principle**
+
+    *Lo que se quiere aquí es algo como la siguiente propiedad de substitución:
+    Si para cada objeto *o1* de tipo *S* hay un objeto *o2* de tipo *T*, tal que
+    para todos los programas *P* definidos en términos de *T*, el comportamiento
+    de *P* no se modifica cuando *o1* es substituido por *o2* entonces *S* es
+    un subtipo de *T*.
+
+    *Barbara Liskov, 1988*
+
+.. todo::
+   Este principio podría ser la definición formal de lo que conocemos como
+   *duck-typing*. Seguir este principio, nos permite crear aplicaciones que
+   sean extensibles a través de *plugins*.
+
+
+- **I-nterface Segregation Principle**
+
+   *Es perjudicial depender de módulos que contienen más de lo que se necesita*
+
+   *Varias interfaces específicas por cliente son mejores que una sóla interfaz
+   de propósito general*
+
+.. graphviz:: media/interface-segregation.dot
+
+.. todo::
+   No es tan crítico en Python al ser un lenguaje dinámico dónde un cambio en
+   las dependencias no implica recompilación.
+
+- **D-ependency Inversion Principle**
+
+    *Los sistemas más flexibles son aquellos en los que las dependencias de
+    código se refieren a abstracciones y no a concreciones*
+
+.. graphviz:: media/dependency-inversion-1.dot
+.. graphviz::
+
+   digraph foo {
+      "VS";
+   }
+.. graphviz:: media/dependency-inversion-2.dot
+
+.. todo::
+   Se debe tener cuidado con la *volatilidad* de componentes *concretos* y no
+   depender de ellos.
 
 Tipos de Programación
 *********************
 
-- Programación Estructurada
+- **Programación Estructurada**
+
+    *Impone disciplina en la transferencia directa de control*
+
+    *Resuelve el problema de los 'GOTO' mediante la iteración y selección*
 
-Secuencia y selección e iteración. (def, if, while, for)
+- **Programación Orientada a Objetos**
 
-- Programación Orientada a Objetos
+    *Impone disciplina en la la transferencia indirecta de control*
 
-Clases, Objetos, Herencia.
+    *Resuelve el problema de los punteros a funciones mediante clases y objetos*
 
-- Programación Funcional
+- **Programación Funcional**
 
-Funciones. No se persiste el estado.
+    *Impone disciplina en la asignación*
+
+    *Resuelve problemas de condiciones de carrera mediante la inmutabilidad*
 
 Modelado del Dominio
 ********************
 
 El núcleo de una aplicación es el dominio que tiene como propósito modelar.
 Este dominio se representa a través de lo que llamamos, la lógica de negocio.
+
+.. image:: media/bounded-context.png
+   :width: 400px
+   :height: 300px
+   

docs/fundamentos/index.rst

@@ -0,0 +1,4 @@
+digraph foo {
+    "Presentation" -> "Business Logic";
+    "Business Logic" -> "Data";
+}

docs/fundamentos/media/accounting-screaming.png

@@ -0,0 +1,4 @@
+digraph foo {
+    "Presentation" -> "Business Logic";
+    "Data" -> "Business Logic";
+}

docs/fundamentos/media/bounded-context.png

@@ -0,0 +1,5 @@
+digraph foo {
+    "User1" -> "OPS\n+op1 +op2 +op3";
+    "User2" -> "OPS\n+op1 +op2 +op3";
+    "User3" -> "OPS\n+op1 +op2 +op3";
+}

docs/fundamentos/media/dependency-inversion-1.dot

@@ -1,44 +1,60 @@
 Implementación
 ##############
 
+.. image:: media/clean-graph.jpg
+   :height: 400px
 
 !Arquitectura que Grita!
 ************************
 
 El propósito de nuestras aplicaciones debe hacerse notar de primera mano.
 
+.. image:: media/file-tree.png
+   :height: 400px
+   :width: 300px
+
 La Regla de las Dependencias
 ****************************
 
 Las dependencias de una aplicación deben dirigirse en la vía de mayor
 abstracción.
 
+.. graphviz:: media/three-layers.dot
+
 Capas y Fronteras
 *****************
 
 Los componentes de una aplicación se comunican entre sí a través de fronteras
 bien definidas.
 
+.. image:: media/ports-adapters.png
+   :height: 250px
+
 Los Detalles
 ************
 
 Las consideraciones de infraestructura son sólo *detalles* del sistema.
 La base de datos, el framework web, las librerías de consola, son sólo
 herramientas de nuestras aplicaciones y no su esencia.
 
-```
-For the framework author, coupling to his or her own framework is not a risk...
 
-The author wants you to couple to the framework, because once coupled in this
-way, it is very hard to break away.
-```
+    *"For the framework author, coupling to his or her own framework
+    is not a risk..."*
+
+    *"The author wants you to couple to the framework, because once
+    coupled in this way, it is very hard to break away."*
+
+    *Uncle Bob*
+
 
 El Componente Principal
 ***********************
 
 El más sucio de los componentes. Es el encargado de instanciar el arbol de
 dependencias para crear la aplicación final.
 
+.. graphviz:: media/main.dot
+
 Las Pruebas
 ***********
 
@@ -47,5 +63,6 @@ pesar de que no pueden asegurar que nuestras aplicaciones son correctas, si
 pueden informarnos que *no son incorrectas* y prevenir regresiones durante el
 desarrollo.
 
-.. todo::
-   agregar imagen de un escalador con su arnés
+.. image:: media/climb.jpg
+   :width: 100%
+   :height: 250px

docs/fundamentos/media/dependency-inversion-2.dot

@@ -0,0 +1,8 @@
+digraph foo {
+    "Presentation" -> "Business Logic";
+    "Data" -> "Business Logic";
+    "Main" -> "Presentation";
+    "Main" -> "Business Logic";
+    "Main" -> "Data";
+
+}

docs/fundamentos/media/interface-segregation.dot

@@ -0,0 +1,4 @@
+digraph foo {
+    "Presentation" -> "Business Logic";
+    "Data" -> "Business Logic";
+}

docs/implementacion/index.rst

@@ -8,7 +8,6 @@ Clean Architecture con Python
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contenido:
 
    introduccion/index.rst
    fundamentos/index.rst

docs/implementacion/media/clean-graph.jpg

@@ -5,10 +5,9 @@ Clean Architecture o arquitectura limpia, es un compendio de principios y
 patrones de desarrollo que tienen como objetivo el facilitar el proceso de
 construcción del software, así como su mantenimiento.
 
-.. todo::
-   Agregar imágen introductoria
-
-Entre sus principales beneficios podemos encontrar:
+.. image:: media/galaxy.jpg
+   :height: 300px
+   :width: 100%
 
 Beneficios
 **********
@@ -24,5 +23,6 @@ Usos
 
 - Aplicaciones de negocios proyectadas para estar en operación indefinidamente.
 - Sistemas distribuidos que se beneficien de un diseño desacoplado (e.g. usando
-microservicios).
-- Infraestructuras heterogeneas a nivel de bases de datos, servicios web, etc.
+  microservicios).
+- Infraestructuras heterogeneas a nivel de bases de datos, servicios web, etc.
+- Aplicaciones pensadas para ser extendidas por terceros a través de plugins.

docs/implementacion/media/climb.jpg

@@ -1,42 +1,37 @@
 Descripción
 ***********
 
-
-- **Tarea** (task): Unidad básica de gestión del trabajo cuyos atributos serán:
-  - UID (uid: str)
-  - Nombre (name: str)
-  - Fecha Límite (due_date: datetime)
-  - Prioridad (priority: int)
-  - ID Proyecto (project_id: str)
-  - ID Etapa (stage_id: str)
-  - Comentarios (comments: str)
-
-- **Proyecto** (project): Contenedor de tareas con un mismo propósito cuyos atributos serán:
-  - UID (uid: str)
-  - Nombre (name: str)
-  - Etapas (stage_ids: List[str])
-  - Comentarios (comments: str)
-
-- **Etapa** (stage): Estado en el que puede estar cada tarea. Un proyecto tiene múltiples etapas. Sus atributos son:
-  - UID (uid: str)
-  - Nombre (name: str)
-  - Cierre (closure: bool)
+Realizaremos una aplicación para gestionar nuestras tareas por realizar.
+En general, la estructura de la aplicación estará compuesta por:
+
+`Taskit Repo <https://github.com/nubark/clean-architecture-python.git>`_
+
+|  - **Tarea** (task): Unidad básica de gestión del trabajo cuyos atributos serán:
+|    UID (uid: str)
+|    Nombre (name: str)
+|    Fecha Límite (due_date: datetime)
+|    Prioridad (priority: int)
+|    ID Proyecto (project_id: str)
+|    Etapa (stage: str)
+|    Comentarios (comments: str)
+
+|  - **Proyecto** (project): Contenedor de tareas con un mismo propósito cuyos
+   atributos serán:
+|    UID (uid: str)
+|    Nombre (name: str)
+|    Comentarios (comments: str)
 
 La aplicación nos permitirá:
 
-- Crear, leer, modificar y eliminar nuevas tareas, proyectos y etapas.
+- Crear, leer, modificar y eliminar nuevas tareas y proyectos.
 - Asignar tareas a proyectos específicos.
-- Definir la prioridad y fecha límite de cada tarea.
-- Mover las tareas por las distintas etapas del proyecto hasta el estado de cierre.
-
-Igualmente, implementaremos algunas restricciones:
-
-- Un proyecto sólo podrá tener una etapa de cierre.
-- No se podrán eliminar tareas en estado de cierre.
-- Habrá un proyecto, entre todos, que se usará por defecto cuando no se especifique alguno en las tareas.
+- Mover las tareas por las distintas etapas del proyecto hasta el
+  estado de cierre.
 
-Finalmente, obtendremos información valiosa para analizar detalladamente nuestro trabajo pudiendo:
+Obtendremos información valiosa para analizar detalladamente
+nuestro trabajo pudiendo:
 
-- Reportar las tareas con fecha límite igual o inferior al día actual, los próximos 7 días, etc.
-- Reportar las tareas que se encuentran en un mismo proyecto.
-- Reportar las tareas que se encuentran en una misma etapa (a través de todos los proyectos).
+- Reportar todas las tareas registradas.
+- Reportar todos los proyectos registrados.
+- Reportar todas las tareas pertenecientes a un mismo proyecto.
+- Reportar todas las tareas con la misma etapa.

docs/implementacion/media/file-tree.png

@@ -0,0 +1,48 @@
+Ejecución
+*********
+
+El repositorio contiene 6 ramas de desarrollo incremental:
+
+- feat/01_models
+- feat/02_repositories
+- feat/03_coordinators
+- feat/04_infrastructure
+- feat/05_reports
+- feat/06_main
+
+Cada una de ellas construye una capa o componente de la aplicación. En el
+proceso de recrear esta construcción, usaremos un enfoque de desarrollo
+guiado por pruebas (i.e. *TDD*). Esto asegurará que los componentes que
+diseñemos, se encuentren desacoplados desde el inicio y sean fáciles de
+extender.
+
+Todos iniciarán en la rama *feat/docs* la cuál no contiene código. En el
+proyector se presentará el *estado* o rama objetivo. En la primera iteración
+esta rama será la *feat/01_models*. En la segunda iteración, cuando hayamos
+alcanzado el estado de la rama *feat/01_models*, la rama objetivo será la
+*feat/02_repositories*. Así lo haremos sucesivamente hasta completar la 
+aplicación.
+
+Dedicaremos un tiempo máximo de 15 minutos a cada fase. Si al completarse los
+15 minutos no se ha terminado la totalidad de la funcionalidad requerida,
+lamentablemente tendremos que ejecutar **git reset --hard**. Por supuesto,
+pueden guardar sus cambios en una rama temporal si quieren (e.g. my/01_models).
+La idea es contar con el tiempo suficiente para abordar la totalidad de la
+aplicación. No se preocupen, tendrán tiempo de sobra para seguir el paso a
+paso en la comodidad de sus casas ;D
+
+Comandos Importantes
+====================
+
+- Correr los tests con pytest:
+
+    pytest -s --cov-report term-missing --cov-branch --cov taskit tests
+
+- Empaquetar nuestra 
+
+    pyinstaller -F taskit/__main__.py -n taskit
+
+Finalmente
+==========
+
+**¡Manos a la obra!**

docs/implementacion/media/main.dot

@@ -1,12 +1,14 @@
 Proyecto *Taskit*
 #################
 
-Realizaremos una aplicación para gestionar nuestras tareas por realizar. En general, la estructura de la aplicación estará compuesta por:
+*¡Para que no se te olvide!*
 
 .. toctree::
    :maxdepth: 2
    :caption: Contenido:
 
    descripcion.rst
+   preparacion.rst
+   ejecución.rst