Liquibase

Una de las tareas en todo desarrollo es tener versionado las diferentes versiones de los esquemas de las bases de datos asociados a las versiones del código y su migración de forma automática. Para realizar esta labor, hay varias herramientas; en la presente entrada, me centraré en la herramienta Liquibase.

Liquibase es una solución madura open source para la migración de esquemas de base de datos para desarrollos de aplicaciones. No voy a descubrir una herramienta nueva e innovadora. Mi objetivo en la entrada es realizar unas notas básicas para poder trabajar con ella. Una de las alternativas de Liquibase es Flyway.

Liquibase tiene dos versiones: la versión de la comunidad y la versión enterprise. La versión sobre la que he realizado los ejemplos es con la versión de la comunidad.

Instalación

El proceso de instalación que he realizado es sencillo: he descargado la versión para el sistema de la máquina con la que trabajo (hay versiones para Windows, Linux y Mac), he verificado la versión de la máquina virtual de Java (recomendado la versión 11); y, para finalizar, he descomprimido el fichero; una vez realizado, ya estás en disposición para trabajar con Liquibase.

La estructura de carpetas de Liquibase no es muy amplia. La estructura es la siguiente:

  • Carpeta lib.- Contiene las librería y driver preconfigurados.
  • Carpeta licenses.- Contiene las licencias de Liquibase.
  • Carpeta examples.- Contiene los ejemplos de la documentación.

Además, en la raíz de la carpeta Liquibase, contiene un conjunto de ficheros que van desde ficheros ejecutables a ficheros de texto.

Conceptos

La forma de trabajar con Liquibase consiste en realizar lo siguiente:

  1. Creación de los ficheros con las operaciones de base de datos.
  2. Ejecutar Liquibase con el fichero de la operaciones de base de datos. Evidentemente, con la configuración de una base de datos determinada.
  3. Comprobación en base de datos de los cambios definidos en las operaciones.

El fichero con las operaciones de base de datos se denomina fichero de changelog en el cual se definen las operaciones de base de datos; estas operaciones, representan un changeset. Así, un fichero changelog está compuesto por un conjunto de changeset las cuales representan las operaciones.

Los ficheros changelog pueden estar definidos en varios formatos: JSON, XML, YAML o bien SQL. Los ejemplos de los siguientes apartados los realizaré en formato SQL.

Desde un punto de vista visual los elementos de Liquibase quedan descritos en la siguiente imagen:

Liquibase necesita conocer la base de datos a la que se tiene que conectar así como las credenciales de la misma. Para almacenar esta información, se define un fichero de properties con los datos necesarios para la conexión y la configuración. La ubicación del fichero de propiedades está en la carpeta raíz de Liquibase.

Ejemplos prácticos

Liquibase puede trabajar con varios tipos de base de datos; por ejemplo: H2, MySQL, PostgreSQL, Microsoft SQL Server,… Los ejemplos de los siguientes apartados los realizaré en una base de datos Microsoft SQL Server.

Para trabajar en local, he descargado una imagen Docker con Microsoft SQL Server, he arrancado un contenedor con la imagen descargada y he creado una base de datos de prueba.

El driver de Microsoft SQL Server no está en la instalación de Liquibase con lo cual, es necesario realizar la descarga del driver y el copiado del fichero jar en la carpeta de Liquibase.

Una vez arrancada la base de datos e instalado el driver de la base de datos en Liquibase, necesitamos configurar Liquibase para que se pueda ejecutar los changelog de los ejemplos en la base datos. Para realizar la configuración, crearemos un fichero de propiedades de la carpeta raíz de Liquibase con nombre liquibase.properties. El contenido del fichero es el siguiente:

changeLogFile:<PATH_AL_FICHERO_CHANGELOG>
liquibase.command.url:  jdbc:sqlserver://localhost:1433;databaseName=<NOMBRE_BASE_DE_DATOS>
liquibase.command.username:  sa
liquibase.command.password:  <PASSWORD>
classpath:  mssql-jdbc-10.2.0.jre11.jar

liquibase.hub.mode=off

Ejemplo1: changelog con un fichero

El primer ejemplo consistirá en definir un changelog sencillo formado por un conjunto de changeset en los cuales se define un par de tablas y unas modificaciones sobre las mismas.

El fichero changelog definido es el siguiente:

--liquibase formatted sql

--changeset ams.caso_uso_1:1
create table person (
    id int primary key,
    name varchar(50) not null,
    address1 varchar(50),
    address2 varchar(50),
    city varchar(30)
)
--rollback DROP TABLE person;

--changeset your.name:2
create table company (
    id int primary key,
    name varchar(50) not null,
    address1 varchar(50),
    address2 varchar(50),
    city varchar(30)
)
--rollback DROP TABLE company;

--changeset other.dev:3
alter table person add country varchar(2)
--rollback ALTER TABLE person DROP COLUMN country;


--changeset ams.caso_uso2:1
alter table person add other_field varchar(2)
--rollback ALTER TABLE person DROP COLUMN country;

La primera línea del fichero changelog define el formato del fichero. En nuestro case definimos que el changelog está definido en SQL.

Las siguientes partes del fichero están compuestas por changeset. Los changeset deben de tener definidos un autor y un número de orden, normalmente, un número secuencial para cada autor. Para el primer changeset, el nombre del autor es ams.caso_uso_1 y, el número de orden, lo representa el número uno.

Los changeset, en formato SQL, finalizan con el elemento rollback el cual define la política de rollback para el changelog definido. Este tema se abordará en el apartado de rollback.

Una vez definido el changelog, podemos ejecutar Liquibase para que se realizan los cambios en base de datos. El comando a ejecutar si el fichero changelog está en la carpeta raíz de Liquibase es el siguiente.

./liquibase update

El resultado por consola de comandos es un listado de los changeset ejecutados. Si existe algún error Liquibase no se ejecuta. El resultado en base de datos es el siguiente:

  1. Creación de la tablas DATABASECHANGELOG y DATABASECHANGELOGLOCK. Estas tablas son aquellas tablas en donde Liquibase va almacenando la información de los despliegues. En la tabla DATABASECHANGELOG se almacena el campo autor e id, respectivamente, valores definidos en cada changeset; nombre del fichero del changelog ejecutado, fecha ejecución y otros campos de ejecución.
  2. Creación de las tablas en base de datos.

Una segunda forma de ejecutar Liquibase es pasándole los parámetros de configuración de base de datos desde la línea de comandos.

Ejemplo 2: changelog con N ficheros

Supongamos que tenemos definidos varios ficheros changelog y queremos que estén definidos en nuestra migración porque representan N operativas. La solución consiste en definir un changelog que indique la ubicación de los ficheros de changelog; estos changelog, deben de estar almacenados en una carpeta.

Supongamos que tengamos dos ficheros de changelog en una carpeta sql dentro de Liquibase. Los ficheros son ejemplo2-db-changelog.sqlserver.sql y ejemplo3-db-changelog.sqlserver.sql. El contenido
de los ficheros es análogo al ejemplo anterior.

El fichero changelog necesario con la indicación del conjunto de ficheros sql debe de ser un fichero changelog definido en XML. El contenido del fichero xml con nombre multiple-file-db-changelog-sqlserver.xml es el siguiente:

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
  xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:pro="http://www.liquibase.org/xml/ns/pro"
  xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.4.xsd
      http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-4.5.xsd">

  <includeAll path="sql" />

</databaseChangeLog>

En el snippet anterior se define una etiqueta raíz con nombre databaseChangeLog y, dentro de esta, la etiqueta includeAll la cual indica que en este changelog debe de incluir todo aquello que se encuentra ubicado en el path definido.

En el atributo changeLogFile del fichero liquibase.properties se debe de definir el fichero multiple-file-db-changelog-sqlserver.xml

De la misma manera que el ejemplo anterior , ejecutamos el comando liquibase update para realizar los cambios en base de datos. El resultado por consola y en base de datos sigue el mismo criterio.

Ejemplo 3: changelog con procedimientos almacenados y vistas

Supongamos que queremos definir un procedimiento almacenado o una vista. Con Liquibase, podemos realizarlo si definimos el procedimiento y la vista en un changeset. Un ejemplo de un changeset con un procedimiento y una vista en un changelog determinado es el siguiente:

[...]
-- changeset ams:5
CREATE PROCEDURE prueba.sp_insert_denominador
AS
BEGIN

	INSERT INTO prueba.person
    (id, name, address1, address2, city)
  VALUES
    (1, 'name_test1', 'address_test1', 'address_test1', 'city_test1')

END
--rollback DROP PROCEDURE IF EXISTS prueba.person

-- changeset ams:6
CREATE view prueba.v_person
AS
SELECT
  id as 'Identificador',
  name as 'Nombre',
  address1 as 'Dirección 1',
  address2 as 'Dirección 2',
  city as 'Ciudad'
FROM prueba.person
--rollback DROP VIEW IF EXISTS prueba.v_person
[...]

Para ejecutar los changeset del snippet anterior hay que seguir pasos de ejecución realizados en los ejemplos anteriores.

Creación de tags

Los tags son etiquetas que se definen en un momento determinado para etiquetar qué despliegues se han realizado; por ejemplo, cuando hemos terminado una versión, se puede crear una etiqueta para identificar el punto de la vista de base de datos correspondiente para esa versión.

En Liquibase la creación de una etiqueta es muy sencilla, simplemente hay que ejecutar el comando tag con el número de etiquetado. Un ejemplo puede ser el siguiente:

./liquibase tag --tag=1.0

El resultado en base de datos es la inserción en el campo tag de la tabla DATABASECHANGELOG el valor definido en el atributo tag, en nuestro caso 1.0, correspondiente al registro del último despliegue.

Rollbacks

Un rollback en base de datos consiste en deshacer lo que se ha definido. En una herramienta como Liquibase definir las operaciones de rollback y tener claro las políticas de rollback es un tarea importante y fundamental.

¿Dónde se definen los rollback? Como se ha mostrado en los ejemplos anteriores, los rollback se definen en los changeset de los changelog en la sección –rollback.

¿Hasta qué punto se ejecuta un rollback? Hay dos estrategias, ejecutar el rollback de la última ejecución o bien ejecutar hasta un instante pasado en el tiempo identificado por etiquetas tag.

El comando de ejecución de un rollback hasta un tag, por ejemplo con valor 1.0, es el siguiente:

./liquibase rollback --tag=1.0

El comando de ejecución de un rollback del último despliegue es el siguiente:

./liquibase rollbackCount 1

El resultado del rollback en la tabla DATABASECHANGELOG de la base de datos es la eliminación de los despliegues hasta el tag o bien el último despliegue realizado.

Comandos

Liquibase proporciona otras herramientas que ofrecen información de los despliegues. Estas herramientas lo representan comandos como el comando update. Unas posibles herramientas comunes para ser utilizadas son:

  • history.- Permite visualizar el históricos de changeset ejecutados. Para ejecutar este comando se realiza de la siguiente manera: ./liquibase history.
  • status.- Permite visualizar el estado de los despliegue realizados. Para ejecutar este comando se realiza de la siguiente manera: ./liquibase status.

Liquibase es una herramienta que permite automatizar las migraciones de esquemas de base de datos permitiendo a los desarrolladores tener controlado los esquemas y datos de las base de datos. Además, de ser una herramienta que puede ser integrada en los procesos de integración continua. La elección de Liquibase o herramientas alternativas como Flyway será en función del equipo, del problema a resolver y las tecnologías empleadas.

Decoradores en Python

En la anterior entrada, Closures , defino los closures en Python y muestro ejemplos; en esta entrada, Decoradores en Python, presentaré los decoradores con dos ejemplos.

Según Wikipedia, definimos el patrón Decorator como sigue:

El patrón Decorator responde a la necesidad de añadir dinámicamente funcionalidad a un Objeto. Esto nos permite no tener que crear sucesivas clases que hereden de la primera incorporando la nueva funcionalidad, sino otras que la implementan y se asocian a la primera.

En Python podemos definir clases decoradoras las cuáles añaden funcionalidad a otras clases; pero, cuando hablamos de decoradores en Python, nos referimos a funciones decoradoras que son utilizadas por otras funciones mediante el empleo de anotaciones.

Para comprender el concepto de decorador es necesario entender el concepto de Closures ya que un decorador es un closure al cual se le pasa la referencia de la función sobre la que se ejecuta y, si fuere necesario, parámetros de entrada.

En los siguientes apartados, muestro ejemplos de decoradores: el primero, un decorador básico con un registro de las funciones clientes; y, en el segundo, un decorador al que se le pasan parámetros.

Un decorador está formado por una función que en su interior puede tener la definición de otras funciones. En tiempos de ejecución, al cargar el módulo donde se encuentra la función cliente con la anotación del decorador, se ejecuta el contenido de la primera función del decorador, ejecutándose la función del decorador con la referencia a la función cliente cuando se produce la invocación de la función cliente con el decorador.

Ejemplo básico

Supongamos que queremos cuantificar las funciones decoradoras que son ejecutadas. Para ello, definimos un módulo con una función decoradora y una lista para que almacene las funciones que son ejecutadas. El resultado es el siguiente: módulo my_decorator_ej1.py en el cuál definimos la función decoradora:

#my_decorators_ej1.py
func_registry = []

def my_decorator_ej1(func):

    print(f'Entramos en my_decorator_ej1')

    def inner():
        print('Ejecutamos función (%s)' % func)
        result = func()
        func_registry.append(func)

        return result

    return inner

Supongamos el siguiente módulo cliente que hace uso de la función decoradora definida anteriormente:

#example1.py
from my_decorators_ej1 import my_decorator_ej1, func_registry

@my_decorator_ej1
def function2() -> None:
    print('Entramos en función 2')

@my_decorator_ej1
def function1() -> None:
    print('Entramos en función 1')
    function2()

def run() -> None:
    function1()
    print(f'Funciones ejecutadas...{len(func_registry)}')
    for fun in func_registry:
        print(fun)

Al ejecutar el snippet de código anterior, lo primero que se realizar es la carga del módulo de los decoradores; y, al cargarlos, se escribe por consola el mensaje ‘Entramos en my_decorator_ej1’ de la primera función del decorador; cuando se ejecutan las funciones clientes, se ejecutan las funciones decoradoras.

La salida por consola del ejemplo anterior es la siguiente:

Entramos en my_decorator_ej1
Entramos en my_decorator_ej1
Ejecutamos función (<function function1 at 0x10d40cee0>)
Entramos en función 1
Ejecutamos función (<function function2 at 0x10d40c940>)
Entramos en función 2
Funciones ejecutadas...2
<function function2 at 0x10d40c940>
<function function1 at 0x10d40cee0>

Función decoradora con parámetros

En el siguiente ejemplo vamos a suponer que deseamos mostrar por consola las funciones que son llamadas, los parámetros y su tiempo de ejecución. El patrón del mensaje por consola es un valor por defecto pero este puede ser diferente en función del patrón definido en la anotación del decorador.

La definición del decorador del ejemplo es la siguiente:

#my_decorators_ej1.py
DEFAULT_FMT = '[{end:0.8f}s] {name}({args}) Resultado={result}'
def my_decorator_ej2(fmt=DEFAULT_FMT):
    print(f'Entramos en my_decorator_ej2')

    def decorator(func):

        def print_console(*_args):
            start = time.time()
            _result = func(*_args)
            end = time.time() - start

            name = func.__name__
            result = repr(_result)
            args = ', '.join(repr(arg) for arg in _args)
            print(fmt.format(**locals()))

            return _result

        return print_console

    return decorator

La definición de la clase cliente que usa el módulo de la función decoradora es la siguiente:

from my_decorators_ej1 import my_decorator_ej2

@my_decorator_ej2()
def function1(param: str) -> int:
    print('Ejecuto function1()...')
    return 33

@my_decorator_ej2()
def function2(param: str) -> None:
    print('Ejecuto function2()...')

@my_decorator_ej2('{name}({args}) => {result}')
def function3(param: str) -> int:
    print('Ejecuto function3()...')
    return 66


def run() -> None:
    function1('param1')

    function2('param1')

    function3('param1')

La salida por consola de la ejecución del snippet anterior es la siguiente:

Entramos en my_decorator_ej2
Entramos en my_decorator_ej2
Entramos en my_decorator_ej2
Ejecuto function1()...
[0.00003290s] function1('param1') Resultado=33
Ejecuto function2()...
[0.00002384s] function2('param1') Resultado=None
Ejecuto function3()...
function3('param1') => 66

De la ejecución anterior los primeros mensajes que se muestran en la consola son los correspondientes a los mensajes que se escriben en la primera función del decorador; los siguientes mensajes, son los correspondientes a la ejecución de cada función cliente en función del patrón definido en la anotación del decorador.

Closures

Los closures es un concepto de programación que se encuentra en diferentes lenguajes de programación, como pueden ser: Java, Groovy, Scala, Python,… En la entrada de hoy, Closures, definiré el concepto de closures y mostraré unos ejemplos en lenguaje Python.

Un Closure es aquella función que hereda el contexto de otra función con lo cual permite heredar las variables utilizadas en la primera. No hay que confundir un closures con el concepto de función anónima.

Las funciones closures pueden ser definidas en una clase o bien en funciones pertenecientes a un módulo. El ejemplo típico que mostraré es el cálculo de una media. En los siguientes apartados, mostraré ejemplos con diferentes escenarios.

Closures en una clase

En el presente ejemplo, definiré una clase Averager que define la función __call__ en la cual se define la funcionalidad para el cálculo de la media a partir de los valores que se le pasan por parámetro; y, el almacén de los valores insertados, será una lista que será atributo de la clase. El snippet del código de ejemplo es el siguiente:

class Averager():
    def __init__(self):
        self.series = []

    def __call__(self, new_value):
        self.series.append(new_value)
        total = sum(self.series)
        return total/len(self.series)
        
def __ejemplo1() -> None:
    print(f'-*- Ejemplo de Clouser: cálculo de la media utilizando una clase con método call -*-')
    avg = Averager()
    print(f'avg(10)={avg(10)}')
    print(f'avg(11)={avg(11)}')
    print(f'avg(12)={avg(12)}')

La salida por consola del snippet mostrado es el siguiente:

    -*- Ejemplo de Clouser: cálculo de la media utilizando una clase con método call -*-
    avg(10)=10.0
    avg(11)=10.5
    avg(12)=11.0 

Closures en una función

El cálculo de un closure se puede definir en una función de un módulo con estructura parecida a la de una clase; la diferencia reside en dónde se encuentra el almacén de valores, los cuáles estarán en una función cuyos valores serán heredados por otra función ubicada en un nivel superior, es decir, una función se define dentro de otra función. El snippet del código de ejemplo es el siguiente:

def make_averager():
    series = []

    def averager(new_value):
        series.append(new_value)
        total = sum(series)
        return total/len(series)

    return averager

def __ejemplo2() -> None:
    print(f'-*- Ejemplo de Clouser: cálculo de la media utilizando un clouser  -*-')
    avg = make_averager()
    print(f'avg(10)={avg(10)}')
    print(f'avg(11)={avg(11)}')
    print(f'avg(12)={avg(12)}')

La salida por consola del snippet mostrado es el siguiente:

-*- Ejemplo de Clouser: cálculo de la media utilizando un clouser  -*-
avg(10)=10.0
avg(11)=10.5
avg(12)=11.0  

Para el cálculo de la media se utiliza las funciones sum y len; y, además, se utiliza una lista con los valores que son insertados en el conjunto de cálculo.

Closures en una función usando el operador nonlocal

El ejemplo anterior puede ser definido de una forma más eficiente, si se va realizando la suma y el conteo de elementos de una forma directa conforme se van añadiendo los elementos. Para realizar este enfoque, hay que definir dos variables count y total en la función de primer nivel; y, en la función de segundo nivel, utilizar el operador nonlocal para identificar que no son variables locales y son variables de la función del nivel superior. El cálculo de la media se realiza con los valores de estas variables eliminando el uso de funciones y el almacén de valores. El snippet del código es el siguiente:

def make_averager2() -> None:
    count = 0
    total = 0

    def averager(new_value):
        nonlocal count, total
        count += 1
        total += new_value
        return total/count

    return averager


def __ejemplo3() -> None:
    print(f'-*- Ejemplo de Couser: utilizando una función con la clausula nonlocal -*-')
    avg = make_averager2()
    print(f'avg(10)={avg(10)}')
    print(f'avg(11)={avg(11)}')
    print(f'avg(12)={avg(12)}')

La salida por consola del snippet mostrado es el siguiente:

-*- Ejemplo de Couser: utilizando una función con la clausula nonlocal -*-
avg(10)=10.0
avg(11)=10.5
avg(12)=11.0 

Como se puede comprobar en los ejemplos, un closure es una definición de un función la cual contiene otra función; y, en está última, se pueden utilizar el contexto de ejecución de la primera.

Este concepto de closures es la base de los decoradores en Python los cuales son aquellas funciones que se ejecutan al invocar a una función.

ZIO IV: modulación por capas

Finalizamos la serie de entradas de ZIO con la presente entrada, ZIO IV: modulación por capas, en la cual presentaré cómo la librería ZIO permite definir módulos funcionales conectados horizontal o verticalmente. Las entradas publicadas hasta la fecha son las siguientes:

El ejemplo práctico ha realizar consistirá en resolver un problema básico de ingeniero de datos del ámbito de BigData. Todo ingeniero de datos debe de dar solución a una ingesta de datos, transformar los datos conforme a unas reglas de negocio y, para finalizar, almacenar o cargar los datos transformados en un data lake o cualquier tipo de almacén de datos; este proceso, se denomina ETL (Extract, Transform and Load). Así, el caso de uso consiste en realizar un proceso de extracción, transformación y carga de datos solicitado por un actor el cual puede ser un sistema o una persona física.

La solución está compuesta por cuatro elementos: el primero, un módulo con la funcionalidad encargada de la extracción de datos; el segundo, el módulo transformador, encargado de transformar los datos en función de unas reglas de negocio; el tercero, el módulo cargador, encargado de realizar la carga de los datos transformados al almacén de datos; y, para finalizar, el elemento coordinador de las operaciones de los módulos el cual contendrá la definición de las secuencias del programa ETL. En el ejemplo, los procesos de extracción y carga son tareas simbólicas ya que el objetivo del ejercicio reside en el desarrollo de los módulos. Desde un punto de vista gráfico la vista de elementos y los intercambios de mensajes entre ellos queda definido en el siguiente diagrama de secuencia UML siguiente:

El diagrama de secuencia anterior define los elementos que intervienen desde un punto de vista del intercambio de mensajes los cuales son: Extractor, el cual realiza las operaciones de extracción con la función extractData(); Transformed, el cual realiza la transformación de los datos con la función doTransformer(); Loader, el cual realiza las operaciones de carga con la función doLoader(); ModuleLayer, el cual contiene el programa que define las operaciones de coordinación del resto de elementos utilizados en la función run(); y, por último, un actor que activa el inicio de las operaciones.

Una vez identificados las entidades abstractas y el intercambio de mensajes, estamos en disposición de profundizar en los elementos físicos que intervienen en la solución y, para ello, emplearemos un diagrama de clases UML para definir la vista estática de la solución. Así, el diagrama de clases con la arquitectura software es la siguiente:

Comenzando en la parte superior del diagrama, tenemos los elementos que definen el extractor. Se define un objeto con nombre Extractor el cual tiene una relación de composición por valor con un trait llamado Service el cual define la operación de extracción con la función extractData; esta función, retorna un elemento de la librería ZIO de tipo IO el cual tiene los siguientes tipos: como valor erróneo, retorna una excepción de tipo ExtractException; y, como retorno de éxito, retorna un ADT de tipo ExtractDataResult. El objeto Extractor tiene un atributo con nombre live el cual define el módulo de ZIO ZLayer asociado a la clase que implementa el servicio ExtractorImpl. Para finalizar, se define un objeto de paquete para enlazar las funciones del objeto Extractor. El snippet del código es el siguiente:

  type Extractor = Has[Extractor.Service]
  object Extractor {
    trait Service {
      def extractData(): IO[ExtractorException, ExtractDataResult]
    }

    case class ExtractorImpl() extends Extractor.Service {
      override def extractData(): IO[ExtractorException, ExtractDataResult] =
        ZIO.succeed(OkExtract(id = 1, name = "Test1", result = true))
    }

    val live: ZLayer[Any, Nothing, Extractor] = ZLayer.succeed(ExtractorImpl())
  }
[...]
 import ModuleLayerExample4Module.Extractor
 package object extractor {
   def extractData = ZIO.accessM[Extractor](_.get.extractData())
 }

Continuando en la parte media del diagrama tenemos los elementos que definen el transformador Transformer. Se define un objeto con nombre Transformer el cual tiene una relación de composición por valor con un trait llamado Service el cual define la operación de transformación con la función doTransformer; esta función, retorna un elemento de la librería ZIO de tipo IO el cual tiene los siguientes tipos: como valor erróneo, retorna una excepción de tipo TransformerException; y, como retorno de éxito, retorna un ADT de tipo TransformedResult. El objeto Transformer tiene un atributo con nombre live el cual define el módulo de ZIO ZLayer asociado a la clase que implementa el servicio TransformedImpl. Para finalizar, se define un objeto para enlazar las funciones del objeto Transformer. El snippet del código es el siguiente:

  type Transformer = Has[Transformer.Service]
  object Transformer {
    trait Service {
      def doTransformer(data: ExtractDataResult): IO[TransformedException, TransformedResult]
    }

    case class TransformerImpl() extends Transformer.Service {
      override def doTransformer(data: ExtractDataResult): IO[TransformedException, TransformedResult] =
        data match {
          case dataIn: OkExtract => ZIO.succeed(OkTransformed(id = dataIn.id, name = dataIn.name, result = true))
          case _                 => ZIO.fail(BasicTransformedException())
        }
    }

    val live: ZLayer[Any, Nothing, Transformer] = ZLayer.succeed(TransformerImpl())
  }
[...]
import ModuleLayerExample4Module.Transformer
package object transformer {
  def transformer(data: ExtractDataResult) = ZIO.accessM[Transformer](_.get.doTransformer(data))
}

En la parte inferior del diagrama tenemos los elementos que definen el cargador Loader. Se define un objeto con nombre Loader el cual tiene una relación de composición por valor con un trait llamado Service el cual define la operación de carga con la función doLoader; esta función, retorna un elemento de la librería ZIO de tipo Task con un ADT de tipo LoaderResult. El tipo Task de ZIO es aquel tipo definido para tareas asíncronas. El objeto Loader tiene un atributo con nombre live el cual define el módulo de ZIO ZLayer asocoado a la clase que implementa el servicio LoaderImpl. Para finalizar, se define un objeto de paquete para enlazar las funciones del objeto Transformer. El snippet del código es el siguiente:

  type Loader = Has[Loader.Service]
  object Loader {
    trait Service {
      def doLoader(data: TransformedResult): Task[LoaderResult]
    }

    case class LoaderImpl() extends Loader.Service {
      override def doLoader(data: TransformedResult): Task[LoaderResult] =
        data match {
          case dataIn: OkTransformed =>
            ZIO.fromFuture(implicit ec => loaderData(dataIn)).mapError(msg => new ErrorLoaderException())
          case _ => ZIO.fail(BasicLoaderException())
        }
    }

    val live: ZLayer[Any, Nothing, Loader] = ZLayer.succeed(LoaderImpl())
  }
[...]
import ModuleLayerExample4Module.Loader
package object loader {
  def loader(data: TransformedResult) = ZIO.accessM[Loader](_.get.doLoader(data))
}

En la parte izquierda del diagrama, se define el módulo controlador ModuleLayerExample4 con el cual declaramos el programa con las definiciones de las operaciones del proceso ETL. El snippet del módulo es el siguiente:

  type Services = Extractor with Transformer with Loader with Logging

  // Log layer
  val envLog =
    Logging.console(
      logLevel = LogLevel.Info,
      format = LogFormat.ColoredLogFormat()
    ) >>> Logging.withRootLoggerName("ModuleLayerExample4")

  val appEnvironment = envLog >+> Extractor.live >+> Transformer.live >+> Loader.live

  def program(): ZIO[Services, Throwable, Boolean] = {
    (for {
      _               <- log.info("[START]")
      dataExtracted   <- extractData
      _               <- log.info(s"[extrated done] data = ${dataExtracted}")
      dataTransformed <- transformer(dataExtracted)
      _               <- log.info(s"[transformed done] data = ${dataTransformed}")
      dataLoaded      <- loader(dataTransformed).catchAllCause(cause => log.info(s"Exception Loader=${cause.prettyPrint}"))
      _               <- log.info(s"[loaded done] data = ${dataLoaded}")
      _               <- log.info(s"[END]")

    } yield { true }) orElse ZIO.succeed(false)

  }

  override def run(args: List[String]): URIO[ZEnv, ExitCode] = {
    (program()
      .catchAllCause(cause => putStrLn(s"Exception=${cause.prettyPrint}"))
      .exitCode)
      .provideCustomLayer(appEnvironment)

  }

Lo primero que se define es el tipo Services el cual contiene las funciones a utilizar; en nuestro caso, definimos un tipo con un conjunto de tipos: Extractor, Transforamer, Loader y Logging definidos previamente. El objetivo de este tipo es definir todas aquellas funciones que estarán disponibles en el programa a declarar, en nuestro caso, el programa que declara la funcionalidad del proceso ETL, así, podremos «inyectar» al programa las funciones que necesitemos.

A continuación, se define la referencia al log y al entorno de ejecución del programa, es decir, define aquellos elementos que contienen las implementaciones de las funciones a utilizar.

Para finalizar se define la función que contiene el programa con las operaciones de la ETL. La función retorna un tipo ZIO con la siguiente composición: como entorno de ejecución, tiene un tipo de tipo Services; como tipo de retorno de error define un tipo Throwable; y, como tipo de resultado de éxito, retorna un tipo Boolean.

Dado que el módulo ModuleLayerExample4 es un objeto de la clase zio.App se debe de definir e implementar la función run() la cual realiza la invocación del la función del programa ETL suministrando las capas de los módulos definidas en el elemento appEnvironment.

Al lector interesado puede acceder al código en el siguiente enlace.

La utilización de la librería ZIO permite tener programas modulares, declarativos y seguros. No tenemos que preocuparnos de realizar una inyección de dependencias sino que hay que definir conjunto de tipos con la funcionalidad necesarias la cual utilizaremos en los programas; y, sobre todo, aclarar el proceso de diseño y desarrollo ya que permite definir los componentes o módulos que intervienen en la solución y sus relaciones. Una vez que se tienen claros los módulos y las firmas de los métodos nos permite sin haber desarrollado cada función una estructura de la solución final.

ZIO III: testing

Continuamos con al serie de la librería ZIO. En la entrada que estamos tratando, ZIO III: testing, me centraré en la definición de test. Las entradas publicadas hasta la fechas son las siguientes:

Los ejemplos mostrados en las entradas anteriores, se han realizado utilizando aserciones de test de prueba o bien mediante código no definido en un test. Para definir test y aserciones claras y concisas, definiremos unos patrones y ejemplos en los siguientes apartados, lo cuáles son:

  • Ejemplo de plantillas.
  • Generación de propiedades en los test.
  • Ejemplo de aserciones.

1.- Ejemplo de plantillas

Las pruebas unitarias tienen que ser categorizadas por funcionalidad y, para conseguir categorias funciones de test, empleamos la función suite. La función suite permite definir pruebas agrupados por una funcionalidad a probar. El conjunto de todas las agrupaciones forman las pruebas de una entidad.

Un requerimiento para la definición de test es que cada clase de test debe de heredar de la clase DefaultRunnableSpec la cual proporciona todos los módulos de ZIO; como por ejemplo: Clock o Random. Un ejemplo de test es el descrito en la siguiente entrada:

import zio.test._
import zio.clock.nanoTime
import Assertion._

import zio.test.DefaultRunnableSpec

object TemplateZioTest extends DefaultRunnableSpec {

    val suite1 = suite("suite1")(
      testM("s1.t1") { assertM(nanoTime)(isGreaterThanEqualTo(0L)) },
      testM("s1.t2") { assertM(nanoTime)(isGreaterThanEqualTo(0L)) }
    )

    val suite2 = suite("suite2")(
      testM("s2.t1") { assertM(nanoTime)(isGreaterThanEqualTo(0L)) },
      testM("s2.t2") { assertM(nanoTime)(isGreaterThanEqualTo(0L)) },
      testM("s2.t3") { assertM(nanoTime)(isGreaterThanEqualTo(0L)) }
    )

    val suite3 = suite("suite3")(
      testM("s3.t1") { assertM(nanoTime)(isGreaterThanEqualTo(0L)) }
    )

    def spec = suite("All test")(suite1, suite2, suite3)

}

2.- Generación de propiedades en los test.

En cierto tipo de test requerimos de datos para ejecutar las pruebas. Los datos pueden ser generados de forma automática por generadores los cuales pueden generar datos primitivos, case class o bien objetos. La entidad para la generación de datos es la entidad Gen definida en zio.test.Gen.

Un requisito fundamental es la necesidad de utilizar el módulo Random con Sized en la definición de los generadores.
Las dependencias de los módulos de los ejemplos es el siguiente:

import zio.test.Assertion.{equalTo, isTrue}
import zio.test.{DefaultRunnableSpec, Gen, Sized, assert, check, suite, testM}
import zio.random.Random
import zio.test.magnolia._
  • Ejemplo de generación de tipos primitivos.

Para la generación de tipos primitivos invocaremos a la función anyXXX, siendo XXX un tipo primitivo, en la definición de test. Un ejemplo de uso de generadores primitivos es el que se define en el siguiente snippet.

testM("Gen Int") {
   check(Gen.anyInt, Gen.anyInt, Gen.anyInt) { (x, y, z) =>
     assert((x + y) + z)(equalTo(x + (y + z)))
   }
},
  • Ejemplo de generación de una case class.

Sea una case class que represente una entidad con nombre Point. Para poder definir una generador de la clase Point, utilizamos la entidad DeriveGen cuyo tipo sea la case class Point. La definición de la clase y el generador de la clase Point es la siguiente:

final case class Point(x: Double, y: Double) {
   def isValid(): Boolean = true
}
val genPoint: Gen[Random with Sized, Point] = DeriveGen[Point]

Para definir el test de la entidad Point con su generador utilizaremos la función check como se muestra en el siguiente ejemplo:

testM("Gen Point") {
  check(genPoint) { (point) =>
     assert(point.isValid())(equalTo(true))
   }
},
  • Ejemplo de generación de objetos.

De la misma manera que el caso anterior para definir un generador de unos objetos a partir de un trait, se realiza de la misma manera. En el siguiente ejemplo, se define el test en donde se utiliza un generador de objetos basados en la definición de un trait:

sealed trait Color {
  def isValid(): Boolean = true
}
case object Red   extends Color
case object Green extends Color
case object Blue  extends Color
val genColor: Gen[Random with Sized, Color] = DeriveGen[Color]

testM("Gen Color") {
   check(genColor) { (color: Color) =>
      assert(color.isValid())(isTrue)
   }
}

3.- Ejemplo de aserciones.

La capacidad de poder verificar todo tipo de dato en una prueba permite definir con más exactitud la ejecución de una prueba. En ZIO empleamos las funciones definidas en la entidad zio.test.Assertion; como pueden ser: equalTo, hasField, isRight,etc…

A continuación, muestro unos ejemplos de pruebas con diferentes tipos de aserciones:

  • Ejemplo de un String.

Supongamos que necesitamos verificar el resultado de un efecto cuyo resultado es un String y, del valor del resultado,
necesitamos verificar que contenga un determinado valor y finalice con otro. La aserción la realizamos empleando la función assert y las funciones containsString y endsWithString de la siguiente manera:

testM("Assertion examples: string") {
  for {
    word <- IO.succeed("The StringTest")
  } yield {
    assert(word)(
       Assertion.containsString("StringTest") &&
          Assertion.endsWithString("Test")
     )
   }
},
  • Ejemplo de un Either.

Supongamos que necesitamos verificar el resultado de un efecto cuyo resultado es un Either. El esquema del test es parecido al anterior pero empleando funciones específicas para el contenedor binario. El ejemplo del snippet es el siguiente:

testM("Assertion examples: either") {
  for {
     either <- IO.succeed(Right(Some(2)))
  } yield {
     assert(either)(isRight(isSome(equalTo(2))))
  }
},
  • Ejemplo de una case class.

Supongamos que necesitamos verificar el resultado de un efecto que retorna una entidad definida en una case class. El esquema del test es como los anteriores pero utilizando la función hasField para acceder a los atributos de la entidad. El ejemplo del snippet es el siguiente:

testM("Assertion examples: case class") {
   final case class Address(country: String, city: String)
   final case class User(name: String, age: Int, address: Address)

   for {
      test <- IO.succeed(User("Nat", 25, Address("France", "Paris")))
   } yield {
      assert(test)(
        hasField("age", (u: User) => u.age, isGreaterThanEqualTo(18)) &&
          hasField("country", (u: User) => u.address.country, not(equalTo("USA")))
      )
   }
},

En la siguiente entrada, ZIO IV: modularización, me centraré en la definición de módulos funcionales.

ZIO II: manejo de errores y recursos

En la entrada anterior, ZIO I: presentación, presenté la librería ZIO y ejemplos con la creación de efectos y operaciones básicas. En la presente entrada, ZIO II: manejo de errores y recursos, describiré cómo podemos manejar errores en la ejecución de efectos con ZIO y el manejo de recursos.

ZIO

La estructura de la entrada está compuesta de los siguientes apartados:

  1. Manejo de errores.
  2. Manejo de recursos.

1.- Manejo de errores

Dada la definición de un efecto en ZIO, sabemos cómo proporcionar el entorno y ejecutar dicho efecto; pero, tenemos que dar respuesta a la siguiente pregunta: ¿cómo podemos realizar el control de la ejecución si se produce un error en la ejecución del efecto? La respuesta es sencilla, el control del efecto se realiza capturando y controlando las excepciones que se puedan originar, así como, si se produce un error tener la posibilidad de poder volver a ejecutar el efecto.

  • Tratamiento de error con el contenedor binario Either.

La primera estrategia es empleando un contenedor binario Either mediante la función either en la cual podemos tener los siguientes valores: en Left, el valor de error; o bien en right, el resultado correcto. Este primer ejemplo es el más sencillo porque se asemeja al control de errores de una función.

El ejemplo más básico de la definición de un ejemplo es el siguiente:

val zeither: UIO[Either[String, Int]] = IO.fail("Boom!").either
val result: Either[String, Int]       = Runtime.default.unsafeRun(zeither)
assertResult(Left("Boom!"))(result)
  • Tratamiento de error en un efecto con el tipo explícito.

Supongamos que tenemos un efecto cuyo posible error lo conocemos; supongamos que el efecto, es la lectura de un fichero y, como conocemos, el error en el tratamiento de un fichero es la generación de una excepción de tipo IOException. La solución consiste en la definición de un efecto en el que definamos el tipo de error y su resultado; en concreto, la solución consiste en definir un efecto cuyo tipo de error es una excepción de tipo IOException y su resultado es un tipo List[String] definiendo un tipo UIO[IOException, List[String]].

En el siguiente ejemplo, se define una función que realiza la lectura de un fichero mediante un efecto de tipo UIO, su ejecución y verificación de tratamiento.

def readFile(nameFile: String): UIO[List[String]] = {
  IO.succeed(Source.fromFile(nameFile).getLines().toList)
}
val readFileResult: IO[IOException, List[String]] = readFile(getURIFileTest(nameFile).getPath)
val resultReadFileOK: List[String]                = Runtime.default.unsafeRun(readFileResult)
assert(resultReadFileOK.isEmpty === false)
assertResult(List("1 2 3", "4 5 6"))(resultReadFileOK)
  • Tratamiento de errores con la función catchAll.

Supongamos que realizamos la lectura de un fichero y queremos capturar todas las posibles excepciones que se puedan producir; para este escenario, utilizamos la función catchAll definida en ZIO. En el siguiente ejemplo, realizamos la lectura de las líneas de un fichero cuyo nombre es pasado por parámetro y, con la función catchAll, capturamos todas las excepciones. Si se produce una excepción entonces realizamos la lectura de un fichero cuyos datos son valores por defecto. El snippet de ejemplo es el siguiente:

 def readFileCatchAll(nameFile: String): Task[List[String]] = {
   ZIO(Source.fromFile(nameFile).getLines().toList).catchAll {
     case _ => {
       val uriFile = this.getClass.getClassLoader.getResource("default.data").toURI
       readFile(uriFile.getPath)
     }
   }
 }

 val readFileOK: Task[List[String]] = readFileCatchAll(getURIFileTest(nameFile).getPath)
 val resultReadFileOK: List[String] = Runtime.default.unsafeRun(readFileOK)
 assert(resultReadFileOK.isEmpty === false)
 assertResult(List("1 2 3", "4 5 6"))(resultReadFileOK)

 val readFileKO: Task[List[String]] = readFileCatchAll("errorFile.data")
 val resultReadFileKO: List[String] = Runtime.default.unsafeRun(readFileKO)
 assert(resultReadFileKO.isEmpty === false)
 assertResult(List("OK"))(resultReadFileKO)
  • Tratamiento de un error con la función catchSome.

Supongamos que queremos capturar un tipo determinado de excepción, en este supuesto utilizamos la función catchSome. En el siguiente ejemplo, se muestra el mismo ejemplo del apartado anterior pero realizando el tratamiento para la excepción FileNotFoundException. El snippet del ejemplo es el siguiente:

 def readFileOrDefault(nameFile: String): Task[List[String]] = {
   ZIO(Source.fromFile(nameFile).getLines().toList).catchSome {
     case _: FileNotFoundException => {
       val uriFile = this.getClass.getClassLoader.getResource("default.data").toURI
       readFile(uriFile.getPath)
     }
   }
 }

val readFileOK: Task[List[String]] = readFileOrDefault(getURIFileTest(nameFile).getPath)
val resultReadFileOK: List[String] = Runtime.default.unsafeRun(readFileOK)
assert(resultReadFileOK.isEmpty === false)
assertResult(List("1 2 3", "4 5 6"))(resultReadFileOK)

val readFileKO: Task[List[String]] = readFileOrDefault("errorFile.data")
val resultReadFileKO: List[String] = Runtime.default.unsafeRun(readFileKO)
assert(resultReadFileKO.isEmpty === false)
assertResult(List("OK"))(resultReadFileKO)
  • Ejecución de un efecto alternativo con la función orElse.

Supongamos que queremos ejecutar un efecto y, suponiendo que se produzca un error en el efecto, deseamos que se ejecute un efecto secundario; para este supuesto, utilizamos la función orElse. En el siguiente snippet de código se muestra el ejemplo con la función orElse.

def readFileFallback(nameFile: String): Task[List[String]] = {
   ZIO(Source.fromFile(nameFile).getLines().toList).orElse {
     val uriFile = this.getClass.getClassLoader.getResource("default.data").toURI
     readFile(uriFile.getPath)
    }
}

val readFileOK: Task[List[String]] = readFileFallback(getURIFileTest(nameFile).getPath)
val resultReadFileOK: List[String] = Runtime.default.unsafeRun(readFileOK)
assert(resultReadFileOK.isEmpty === false)
assertResult(List("1 2 3", "4 5 6"))(resultReadFileOK)

val readFileKO: Task[List[String]] = readFileFallback("errorFile.data")
val resultReadFileKO: List[String] = Runtime.default.unsafeRun(readFileKO)
assert(resultReadFileKO.isEmpty === false)
assertResult(List("OK"))(resultReadFileKO)
  • Tratamiento de un efecto de forma no pura.

Supongamos que queremos retornar el resultado y no realizar un tratamiento específico, es decir, si el efecto se ejecuta sin problemas retornamos el resultado; pero, si se produce un error retornamos un resultado del tipo esperado; para este supuesto, utilizamos la función fold. En el siguiente snippet de código se muestra el ejemplo con la función fold:

def readFileFold(nameFile: String): Task[List[String]] = {
  ZIO(Source.fromFile(nameFile).getLines().toList).fold(_ => List("OK"), data => data)
}

val readFileOK: Task[List[String]] = readFileFold(getURIFileTest(nameFile).getPath)
val resultReadFileOK: List[String] = Runtime.default.unsafeRun(readFileOK)
assert(resultReadFileOK.isEmpty === false)
assertResult(List("1 2 3", "4 5 6"))(resultReadFileOK)

val readFileKO: Task[List[String]] = readFileFold("errorFile.data")
val resultReadFileKO: List[String] = Runtime.default.unsafeRun(readFileKO)
assert(resultReadFileKO.isEmpty === false)
assertResult(List("OK"))(resultReadFileKO)
  • Tratamiento de un efecto de forma pura.

El caso contrario al ejemplo anterior es definir un efecto para el caso de éxito y caso de error mediante la función foldM. En el siguiente snippet de código se muestra el ejemplo con la función foldM.

def readFileFoldM(nameFile: String): Task[List[String]] = {
  ZIO(Source.fromFile(nameFile).getLines().toList)
    .foldM(_ => ZIO.succeed(List("OK")), data => ZIO.succeed(data))
}

val readFileOK: Task[List[String]] = readFileFoldM(getURIFileTest(nameFile).getPath)
val resultReadFileOK: List[String] = Runtime.default.unsafeRun(readFileOK)
assert(resultReadFileOK.isEmpty === false)
assertResult(List("1 2 3", "4 5 6"))(resultReadFileOK)

val readFileKO: Task[List[String]] = readFileFoldM("errorFile.data")
val resultReadFileKO: List[String] = Runtime.default.unsafeRun(readFileKO)
assert(resultReadFileKO.isEmpty === false)
assertResult(List("OK"))(resultReadFileKO)
  • Tratamiento con reintento de ejecución.

Supongamos que queremos reintentar ejecutar un efecto si se produce un error un número determinado de veces y,
si dado ese número de reintentos no tenemos éxito, capturar la excepción y retornar un efecto con un resultado por defecto; para este caso, utilizamos la función retry para definir un número de reintentos con un Schedule y la función catchAll. El snippet de código con el ejemplo es el siguiente:

import zio.clock.Clock
  [...]
  def readFileRetrying(nameFile: String): ZIO[Clock, Throwable, List[String]] = {
    ZIO(Source.fromFile(nameFile).getLines().toList)
      .retry(Schedule.recurs(5))
      .catchAll { case _ =>
        ZIO.succeed(List("OK"))
      }
}

val readFileOK: ZIO[Clock, Throwable, List[String]] = readFileRetrying(getURIFileTest(nameFile).getPath)
val resultReadFileOK: List[String]                  = Runtime.default.unsafeRun(readFileOK)
assert(resultReadFileOK.isEmpty === false)
assertResult(List("1 2 3", "4 5 6"))(resultReadFileOK)

val readFileKO: ZIO[Clock, Throwable, List[String]] = readFileRetrying("errorFile.data")
val resultReadFileKO: List[String]                  = Runtime.default.unsafeRun(readFileKO)
assert(resultReadFileKO.isEmpty === false)
assertResult(List("OK"))(resultReadFileKO)

Para el lector interesado en el código de los ejemplos, puede acceder al mismo a través del siguiente enlace.

2.- Manejo de recursos

Para el manejo de recursos es necesario definir un patrón estructural basado en la estructura try/finally. Supongamos que definimos un efecto y, una vez que finaliza su ejecución, queremos ejecutar un segundo efecto de finalización; para ello, utilizamos la función ensuring. Un ejemplo de patron try/finally con efectos en ZIO es el siguiente:

val finalizer2: UIO[Unit] = UIO.effectTotal(println("finally"))
val operation: UIO[Unit] = IO.succeed(println("Finalizing 2!")).ensuring(finalizer2)
val resultOperation      = Runtime.default.unsafeRun(operation)
assertResult(())(resultOperation)

Otra forma de aplicar el patrón try/finally es utilizando la función bracket en la cual se realiza una adquisición de un recurso, una tratamiento y un cierre de recurso. Un ejemplo de utilización de función bracket con un fichero es el siguiente:

def readFileBracket(nameFile: String): Task[List[String]] =
  UIO(Source.fromFile(nameFile)).bracket(bufferedSource => UIO(bufferedSource.close())) { file =>
    UIO(file.getLines().toList)
  }

val file: Task[List[String]] = readFileBracket(getURIFileTest(nameFile).getPath)
val resultFile               = Runtime.default.unsafeRun(file)
assertResult(List("1 2 3", "4 5 6"))(resultFile)

Para el lector interesado en el código de los ejemplos, puede acceder al mismo a través del siguiente enlace.

En el siguiente ejemplo, ZIO III: testing, describiré unos patrones para la realización de test con ZIO.

ZIO I: presentación

Inicio una serie de entradas de la librería ZIO. En la presente entrada, ZIO I: presentación, realizaré una presentación y realizaré unos ejemplos básicos introductorios.

ZIO es aquella librería en Scala para ejecutar tareas asíncronas y tareas de programación concurrente la cual es una librería funcional pura. La librería está inspirada en la mónada IO de Haskell.

El tipo de dato ZIO está compuesta por tres parámetros como sigue: ZIO[R, E, A]. Los tipos tienen la siguiente definición semántica:

  • R , Tipo de entorno.- El efecto requiere un tipo de entorno representado por R. Si el tipo está definido como Any, significa que no tiene requerimiento porque no necesitas un valor.
  • E , Tipo de fallo.- El efecto puede terminar en error con un tipo definido en E. Si puede terminar con error, se define con el tipo Throwable; si no puede terminar con error, se define con el tipo Nothing.
  • A, Tipo de éxito.- El efecto puede terminar con un tipo de éxito representado por el tipo A. Si el tipo es Unit, significa que el efecto no retorna información; si el tipo es Nothing, significa que el efecto está corriendo de forma indefinida

Unos ejemplos de definición de un tipo ZIO pueden ser los siguientes:

  • ZIO[Any, IOException, String].- Definición de un tipo que no tiene un requerimiento, retorna un valor de tipo String y, si se produce un error, retorna un elemento de tipo IOException.
  • ZIO[String, Throwable, Int].- Definición de un tipo con un requerimiento de tipo String, retorna un valor de tipo entero y, si se produce un error, retorna un elemento de tipo Throwable.

El requerimiento hay que visualizarlo como el valor de entrada al efecto para que sea procesado.

La librería ZIO define un conjunto de alias para poder trabajar de forma sencilla. Los alias definidos son las siguientes:

  • IO[E, A].- IO es el alias de ZIO[Any, E, A]. Define un efecto que no tiene requerimientos, el error puede ser de tipo E y el resultado es de tipo A.
  • UIO[A].- UIO es el alias de ZIO[Any, Nothing, A]. Define un efecto que no tiene requerimientos,
  • URIO[R, A].- URIO es el alias de ZIO[R, Nothing, A]. Define un efecto que tiene un requerimiento de tipo R, no puede tener un error y el resultado es de tipo A.
  • Task[A].- Task es el alias de ZIO[Any, Throwable, A]. Define un efecto que no tiene un requerimiento, el tipo de error es de tipo Throwable y el resultado es de tipo A.
  • RIO[R, A].- RIO es el alias de ZIO[R, Throwable, A]. Define un efecto que tiene un requerimiento de tipo R, el tipo de error es de tipo Throwable y el resultado de de tipo A.

La definición de las dependencias de la librería ZIO en un proyecto gestionado con sbt son las siguientes:

val zio = "1.0.3"
lazy val zio_core  = "dev.zio" %% "zio" % Versions.zio
lazy val zio_streams  = "dev.zio" %% "zio-streams" % Versions.zio
lazy val zio_test = "dev.zio" %% "zio-test"  % Versions.zio % "test"
lazy val zio_test_sbt = "dev.zio" %% "zio-test-sbt"  % Versions.zio % "test"
lazy val zio_test_magnolia = "dev.zio" %% "zio-test-magnolia" % Versions.zio % "test" 

La estructura de la entrada está compuesta de los siguientes apartados:

  1. Creación de efectos.
  2. Operaciones básicas.

1.- Creación de efectos

En el presente apartado, mostraré ejemplos básicos para la definición de efectos con ZIO. Son ejemplos muy simples pero son aclaratorios para dar los primeros pasos. La definición de efectos se muestra en los siguientes puntos:

  • Efecto succeed.- empleamos la función succeed para crear un efecto cuyo resultado es exitoso.
val int42 = for {
   intS1 <- ZIO.succeed(42)
} yield (intS1)
val resultInt42 = Runtime.default.unsafeRun(int42)
assert(42 === resultInt42)
  • Efecto fail.- empleamos la función fail para crear un efecto cuyo resultado no es satisfactorio.
val f1: zio.URIO[Any, Either[String, Nothing]] = ZIO.fail("Uh oh!").either
val resultFailf1: Either[String, Nothing]      = Runtime.default.unsafeRun(f1)
assertResult(resultFailf1)(Left("Uh oh!"))
  • Efecto effectTotal.- empleamos la función effectTotal cuando estamos seguro que el efecto no tiene un efecto de lado.
val effectTotal: Task[Long] = ZIO.effectTotal(System.currentTimeMillis())
val resultEffectTotal: Long = Runtime.default.unsafeRun(effectTotal)
assert(resultEffectTotal > 0)
  • Efecto fromOption.- empleamos la función fromOption para crear un efecto a partir de un tipo Option.
val zoption: IO[Option[Nothing], Int] = ZIO.fromOption(Some(2))
val resultZOption: Int                = Runtime.default.unsafeRun(zoption)
assert(2 === resultZOption)
  • Efecto fromEither.- empleamos la función fromEither para crear un efecto a partir de un tipo Either.
val zeither: IO[Either[Exception, String], String] = ZIO.fromEither(Right("Success"))
val resultZeither: String                                         = Runtime.default.unsafeRun(zeither)
assert("Success" === resultZeither)
  • Efecto fromTry.- empleamos la función fromTry para crear un efecto a partir de un tipo Try.
 val ztry: Task[Int] = ZIO.fromTry(Try(40 / 2))
 val resultZTry: Int = Runtime.default.unsafeRun(ztry)
 assert(20 === resultZTry)
  • Efecto fromFunction.- empleamos la función fromFuction para crear un efecto a partir de una función.
val zfun: URIO[Int, Int] = ZIO.fromFunction((i: Int) => i * i)
val resultZfun: Int      = Runtime.default.unsafeRun(zfun.provide(5))
assert(25 === resultZfun)
  • Efecto fromFuture.- empleamos la función fromFuture para crear un efecto a partir de un Future.
lazy val future = Future.successful("Hi!")
val zfuture: Task[String] = ZIO.fromFuture { implicit ec =>
   future.map(_ => "Goodbye!")
}
val resultZFuture: String = Runtime.default.unsafeRun(zfuture)
assert("Goodbye!" === resultZFuture)
  • Efecto desde un efecto de lado.- Definimos una función con un efecto de lado, en el ejemplo, escribir un texto en la consola.
def putStrLn(line: String): UIO[Unit] =
  ZIO.effectTotal(println(line))
val resultPut: Unit = Runtime.default.unsafeRun(putStrLn("Test"))
assert(resultPut === ())

Para el lector interesado, puede acceder al código de los ejemplos del apartado mediante el siguiente enlace.

2.- Operaciones básicas

Una vez visto cómo podemos crear efectos en ZIO, estamos en disposición de mostrar ejemplos de operaciones básicas. Las operaciones consisten en la declaración de un programa con un conjunto de operaciones; esas operaciones, pueden ser puras, o bien, pueden tener efectos de lado, por ejemplo: la lectura desde consola, o bien, escribir en la salida estándar. El primer ejemplo que voy a mostrar es la definición de una función que muestre un mensaje por pantalla y la lectura de consola. Para realizar el programa, definiremos dos funciones: getStrlLn, función que realiza la lectura por consola; putStrLn, función que escribe un mensaje en la consola. La definición de las funciones son las siguientes:

val getStrLn: Task[String] = ZIO.effect(StdIn.readLine())
def putStrLn(line: String): UIO[Unit] = ZIO.effectTotal(println(line))

Una vez definido las funciones básicas, definimos el programa que realiza la concatenación de las funciones anteriores mediante la función exampleChaining y, como segunda opción, definimos el mismo programa utilizando for comprehension. Los snippet de las funciones son las siguientes:

def exampleChaining(): Unit = {
      val operation1 = getStrLn.flatMap(input => putStrLn(s"-->${input}"))
      Runtime.default.unsafeRun(operation1)
}

def exampleForComprenhensions(): Unit = {
      val program = for {
        _    <- putStrLn("Nombre")
        name <- getStrLn
        _    <- putStrLn(s"Value=${name}")
      } yield ()
      Runtime.default.unsafeRun(program)
}

Otra forma de encadenar efectos es utilizando la función zip, zipRight, o bien, zipLeft. En el siguiente ejemplo, se muestan ejemplos parecidos a los anteriores con la función zipRight y su alias *>. Hay que destacar que la función zipRight realiza la concatenación de efectos y, además, ejecuta una función map para tratar el resultado del primer efecto. El snippet del código es el siguiente:

def exampleZipping(): Unit = {
      val zipRight1               = putStrLn("Name Right 1?").zipRight(getStrLn)
      val resultZipRight1: String = Runtime.default.unsafeRun(zipRight1)
      println(s"=>${resultZipRight1}")
      val zipRight2               = putStrLn("Name Right 2?") *> getStrLn
      val resultZipRight2: String = Runtime.default.unsafeRun(zipRight2)
      println(s"=>${resultZipRight2}")
}

Para el lector interesado, puede acceder al código de los ejemplos del apartado mediante el siguiente enlace.

En la siguiente entrada, ZIO II: manejo de errores y recursos, continuaremos describiendo la librería ZIO centrándonos en cómo se manejan errores y recursos mediante.

Numpy III

Terminamos la serie de entradas de la librería Numpy. En la presente entrada, Numpy III, presento unos ejemplos finales para el uso de la librería. Además de la librería Numpy, utilizaré la librería matplotlib para la visualización de datos.

Para el lector interesado, puede acceder a las entradas previas en los siguientes enlaces:

Los ejemplos de utilización de la librería Numpy a presentar en esta entrada son los siguientes:

  1. Generación aleatoria de números.
  2. Transformación de arrays de una dimensión a otra.
  3. Álgebra linear.
  4. Operaciones sobre conjuntos.
  5. Serialización de arrays.

1.- Generación aleatoria de números.

Para la generación de números aleatorios emplearemos la función randn; para la definición de la semilla de generación, emplearemos la función seed; y, para definir un objeto de estado para la generación de números, emplearemos el objeto RandomState.

Para definir una distribución, empleados la función scatter del módulo matplotlib.pyplot; y, para representar desde un punto de vista gráfico, se emplea la función show. El snippet de código de ejemplo es el siguiente:

seed = np.random.seed(123)
randn = np.random.randn(3)
print(f'randn=\n{randn}\n')

rang1 = np.random.RandomState(seed=123)
array_rang1 = rang1.randn(3)
print(f'array_rang1=\n{array_rang1}\n')

rang2 = np.random.RandomState(seed=123)
array_rang2 = rang2.randn(100, 2)  # Retorna una distribución normal
print(f'array_rang2=\n{array_rang2}\n')

plt.scatter(array_rang2[:, 0], array_rang2[:, 1])

rang3 = np.random.RandomState(seed=123)
normal_distribution = 2. * rang3.randn(100, 2) + 5.
plt.scatter(normal_distribution[:, 0], normal_distribution[:, 1])
plt.show()

La salida por consola son los siguientes:

randn=
[-1.0856306   0.99734545  0.2829785 ]

array_rang1=
[-1.0856306   0.99734545  0.2829785 ]

array_rang2=
[[-1.08563060e+00  9.97345447e-01]
   ...
 [-3.41261716e-01 -2.17946262e-01]]

La gráfica generada en el ejemplo anterior es la que se muestra en el siguiente gráfico:

2.- Transformación de arrays de una dimensión a otra.

La creación de array n-dimensionales los podemos crear a partir de un array de una dimensión. Para realizar el cambio de dimensión, se realiza con la función reshape; con esta función, se puede especificar las dimensiones de forma explícita o implícito. Para realizar el proceso inverso, empleamos la función flatten; y, por último, para concatenar arrays, se emplea la función concatenate. En el siguiente snippet se muestra ejemplos de uso:

array = np.array([1, 2, 3, 4, 5, 6])
print(f'array=\n{array}\n')
array_23 = array.reshape(2, 3)  
print(f'array_23=\n{array_23}\n')
print(f'may_share_memory=\n{np.may_share_memory(array_23, array)}\n')

array_2_1 = array.reshape(2, -1)  
print(f'array_2_1=\n{array_2_1}\n')

array_1_2 = array.reshape(-1, 2)  
print(f'array_1_2=\n{array_1_2}\n')

array2 = np.array([[1, 2, 3],
                      [4, 5, 6]])
print(f'array2=\n{array2}\n')
array2_1 = array2.reshape(-1)  
print(f'array2_1=\n{array2_1}\n')
print(f'array2.ravel()=\n{array2.ravel()}\n')  # ravel es flatten

print(f'np.may_share_memory(array2.flatten(), array2)={np.may_share_memory(array2.flatten(), array2)}')  # False
print(f'np.may_share_memory(array2.ravel(), array2)  ={np.may_share_memory(array2.ravel(), array2)}')  # True

ary = np.array([1, 2, 3])
ary_concatenate = np.concatenate((ary, ary))
print(f'ary_concatenate=\n{ary_concatenate}\n')

La salida por consola es la siguiente:

array=
 [1 2 3 4 5 6]

array_23=
  [[1 2 3]
   [4 5 6]]

may_share_memory=
    True

array_2_1=
  [[1 2 3]
  [4 5 6]]

array_1_2=
  [[1 2]
   [3 4]
   [5 6]]

array2=
  [[1 2 3]
   [4 5 6]]

array2_1=
 [1 2 3 4 5 6]

array2.ravel()=
 [1 2 3 4 5 6]

np.may_share_memory(array2.flatten(), array2)=False
np.may_share_memory(array2.ravel(), array2)  =True
ary_concatenate=
   [1 2 3 1 2 3]

3.- Algebra linear.

La multiplicación de matrices así como la operación con la matriz transpuesta es una operación típica, en el presente apartado, presentamos dos funciones para realizar el producto de dos matrices: función matmul, multiplica dos matrices pasadas por parámetro; y, la función dot, realiza la misma funcionalidad pero más eficiente. Para calcular la función transpuesta, empleamos la función T de un array. En el siguiente ejemplo, se muestra un snippet de código con ejemplos de productos de matrices.

matrix = np.array([[1, 2, 3],
                    [4, 5, 6]])
column_vector = np.array([[1, 2, 3]]).reshape(-1, 1)
print(f'matrix=\n{matrix}\n')
print(f'column_vector=\n{column_vector}\n')

result = np.matmul(matrix, column_vector)
print(f'matrix X column_vector=\n{result}\n')

# Más eficiente con dot.
print(f'np.dot(row_vector, row_vector)=\n{np.dot(row_vector, row_vector)}\n')
print(f'np.dot(matrix, row_vector)=\n{np.dot(matrix, row_vector)}\n')
print(f'np.dot(matrix, column_vector)=\n{np.dot(matrix, column_vector)}\n')

print(f'matrix.transpose()=\n{matrix.transpose()}\n')
print(f'matrix.T=\n{matrix.T}\n')
print(f'np.dot(matrix, matrix.T)=\n{np.dot(matrix, matrix.T)}\n')
print(f'np.matmul(matrix, matrix.T)=\n{np.matmul(matrix, matrix.T)}\n')

La salida por consola es la siguiente:

matrix=
   [[1 2 3]
    [4 5 6]]

column_vector=
   [[1]
    [2]
    [3]]

matrix X column_vector=
  [[14]
   [32]]

np.dot(row_vector, row_vector)=
  14

np.dot(matrix, row_vector)=
    [14 32]

np.dot(matrix, column_vector)=
    [[14]
     [32]]

matrix.transpose()=
    [[1 4]
     [2 5]
     [3 6]]

matrix.T=
    [[1 4]
     [2 5]
     [3 6]]

np.dot(matrix, matrix.T)=
    [[14 32]
     [32 77]]

np.matmul(matrix, matrix.T)=
    [[14 32]
     [32 77]]

4.- Operaciones sobre conjuntos.

Las operaciones de intersección, diferencia, unión o conjunto único sin repeticiones, se realizan respectivamente con las siguientes funciones: intersect1d, setdiff1d, union1d y unique. En el siguiente snippet de código se muestra ejemplos de uso:

array = np.array([1, 1, 2, 3, 1, 5])
array_set = np.unique(array)
print(f'array_set=\n{array_set}\n')

array1 = np.array([1, 2, 3])
array2 = np.array([3, 4, 5, 6])
print(f'array1=\n{array1}\n')
print(f'array2=\n{array2}\n')

array_intersec = np.intersect1d(array1, array2, assume_unique=True)
print(f'array_intersec=\n{array_intersec}\n')

array_diff = np.setdiff1d(array1, array2, assume_unique=True)  # aaray1 - array2
print(f'array_diff=\n{array_diff}\n')

array_union = np.union1d(array1, array2)La librería Numpy es aquella librería pensada y preparada para realizar operaciones matemáticas orientadas a distintos ámbitos de la ciencia la cual, en mi caso, me permita profundizar en casos prácticos de Machine Learning.
print(f'array_union=\n{array_union}\n')

La salida por consola es la siguiente:

array_set=
[1 2 3 5]

array1=
[1 2 3]

array2=
[3 4 5 6]

array_intersec=
[3]

array_diff=
[1 2]

array_union=
[1 2 3 4 5 6]

5.- Serialización de arrays.

Para almacenar los valores de un array en un fichero, empleamos la función save; para almacenar un array con los índices, se emplea la función savez; y, para realizar la carga de un fichero en memoria, se emplea la función load. Los ficheros con los que se operan tienen extensión .npz.

En el siguiente snippet de código se muestra unos ejemplos de uso de estas funciones:

array = np.array([1, 2, 3])
np.save('ary-data.npy', array)

data_file = np.load('ary-data.npy')
print(f'data_file=\n{data_file}\n')

array2 = np.array([1, 2, 3, 4, 5, 6])
np.savez('ary2-data.npz', array, array2)  

ary2_data = np.load('ary2-data.npz')
print(f'ary2_data=\n{ary2_data}\n')

array2_key = ary2_data.keys()
print(f'array2_key=\n{array2_key}\n')
print(f'ary2_data["arr_0"]=\n{ary2_data["arr_0"]}\n')  
print(f'ary2_data["arr_1"]=\n{ary2_data["arr_1"]}\n')

kwarg = {'ary1': array, 'ary2': array2}
np.savez('ary3-data.npz', **kwarg)

ary3_data = np.load('ary3-data.npz')
print(f'ary3_data=\n{ary3_data}\n')
print(f'ary3_data["ary1"]=\n{ary3_data["ary1"]}\n')  
print(f'ary3_data["ary2"]=\n{ary3_data["ary2"]}\n')

La salida por consola es la siguiente:

data_file=
[1 2 3]

ary2_data=
<numpy.lib.npyio.NpzFile object at 0x7f580fa5a128>

array2_key=
KeysView(<numpy.lib.npyio.NpzFile object at 0x7f580fa5a128>)

ary2_data["arr_0"]=
 [1 2 3]

ary2_data["arr_1"]=
  [1 2 3 4 5 6]

ary3_data=
  <numpy.lib.npyio.NpzFile object at 0x7f57e8b7def0>

ary3_data["ary1"]=
  [1 2 3]

ary3_data["ary2"]=
  [1 2 3 4 5 6]

La librería Numpy es aquella librería pensada y preparada para realizar operaciones matemáticas orientadas a distintos ámbitos de la ciencia la cual, en mi caso, me permita profundizar en casos prácticos de Machine Learning.

Numpy II

En la entrada anterior, Numpy I, realicé una presentación de la librería Numpy y realicé la descripción de unos ejemplos básicos. En la presenta entrada, Numpy II, continuaré presentando ejemplos de operaciones con la Numpy.

Los ejemplos de utilización de la librería Numpy a presentar en esta entrada son los siguientes:

  1. Operaciones de arrays con sus dimensiones.
  2. Indexación avanzada.
  3. Operaciones de comparación.

1.- Operaciones de arrays con sus dimensiones.

Los arrays son estructuras n-dimensionales con los cuáles podemos realizar sumas a pesar de tener diferente número de dimensión. A continuación, muestro una serie de ejemplos.

Sean dos arrays con la misma dimensión y número de elementos por dimensión, la operación suma se realiza con el operador +. El snippet del código es el siguiente:

array1 = np.array([1, 2, 3])
array2 = np.array([4, 5, 6])
print(f'array1 + array2={array1 + array2}')

La salida por consola es la siguiente:

array1 + array2=[5 7 9]

Sea un array de dos dimenciones con tres elementos por dimensión y un array de una dimensión e igual número de elementos que el primero. El snippet del código es el siguiente:

array3 = np.array([[7, 8, 9], [3, 2, 1]])
print(f'array3 + array1={array3 + array1}')

La salida por consola es la siguiente:

array3 + array1=[[ 8 10 12]
 [ 4  4  4]]

Sea un array de dos dimensiones con tres elementos y un array de dos dimensiones de un elemento por dimensión. El resultado es una array de dos dimensiones de tres elementos en el que se ha incrementado el valor del segundo array. El snippet del código es el siguiente:

array_21 = np.array([[1], [2]])
print(f'array3 + array_21={array3 + array_21}')  

La salida por consola es la siguiente:

array3 + array_21=[[ 8  9 10]
 [ 5  4  3]]

2.- Indexación avanzada.

Para realizar operaciones con parte de los elmentos de un array, se deben de crear referencias a la estructura con la que se desea operar. Si se desea incrementar en 100 la segunda posición de las dimensiones que forman parte de un array, se crea una referencia a las posiciones de todas las dimensiones y se incrementa en 100 con el operador +=, en nuestro ejemplo, center_array; una vez operado, el array inicial contiene el resultado. Hay que destacar que las operaciones no son inmutables y se trabaja con referencias. El snippet del código es el siguiente:

array = np.array([[1, 2, 3], [4, 5, 6]])
center_array = array[:, 1]
center_array += 100
print(f'center_array=\n{center_array}')
print(f'array=\n{array}')

La salida por consola es la siguiente:

center_array=
[102 105]
array=
[[  1 102   3]
 [  4 105   6]]

Si se desea realizar una copia de una dimensión se utiliza la función copy. En el siguiente ejemplo, se realiza una copia de una dimensión de una array inicial. El snippet de ejemplo es el siguiente:

array2 = np.array([[1, 2, 3], [4, 5, 6]])
second_row = array2[1].copy()  
second_row += 100
print(f'second_row=\n{second_row}')
print(f'array2=\n{array2}')

La salida por consola es la siguiente:

second_row=
[104 105 106]
array2=
[[1 2 3]
 [4 5 6]]

Para determinar si una referencia es una copia o forma parte de una estructura se emplea la función may_share_memory. A continuación, se muestran dos ejemplos de ejemplos previos. El snippet de código es el siguiente:

  first_row = array2[:1]
  np.may_share_memory(first_row, array2)
  print(f'np.may_share_memory(first_row, array2)=\n{np.may_share_memory(first_row, array2)}')
  print(f'np.may_share_memory(second_row, array2)=\n{np.may_share_memory(second_row, array2)}')

La salida por consola es la siguiente:

  np.may_share_memory(first_row, array2)=
  True
  np.may_share_memory(second_row, array2)=
  False

Para obtener arrays que sean subconjuntos de un array, podemos realizar seleccion de posiciones de una determinada dimensión. En el siguiente ejemplo, se imprimen todos los elementos de la primera dimensión y el primer y último elemento de la segundo; y, por último, el caso contrario, último y primero. El snippet del código es el siguiente:

array3 = np.array([[1, 2, 3], [4, 5, 6]])
print(f'array3=\n{array3}')  
print(f'array3[:, [0,2]]=\n{array3[:, [0,2]]}')  
print(f'array3[:, [2,0]]=\n{array3[:, [2,0]]}')  

La salida por consola es la siguiente:

array3=
[[1 2 3]
 [4 5 6]]
array3[:, [0,2]]=
[[1 3]
 [4 6]]
array3[:, [2,0]]=
[[3 1]
 [6 4]]

Por último, se pueden realizar operaciones de comparación de los elementos y obtener array lógicos con el resultado. En el siguiente ejemplo, se imprimen los elementos mayores a 3; impresión de los elementos que son mayores a 3; y, por último, se compone un predicado lógico. El snippet del código es el siiguiente:

array3 = np.array([[1, 2, 3], [4, 5, 6]])
print(f'array3 > 3=\n{array3 > 3}')  
print(f'array3[array3 > 3]=\n{array3[array3 > 3]}')  
print(f'array3[(array3 > 2) & (array3 <5)]=\n{array3[(array3 > 2) & (array3 <5)]}')

La salida por consola es la siguiente:

array3 > 3=
[[False False False]
 [ True  True  True]]
array3[array3 > 3]=
[4 5 6]
array3[(array3 > 2) & (array3 <5)]=
[3 4]

3.- Operaciones de comparación.

En el apartado anterior, se presentó la operación de comparación y, en el presente apartado, profundizaremos en las operaciones de comparación. En este primer ejemplo, se muestra una selección de elementos de un array mayores a 2. El snippet del código es el siguiente:

array = np.array([1, 2, 3, 4])
array_mayor_2 = array > 2
print(f'array_mayor_2=\n{array_mayor_2}\n')

La salida por consola es la siguiente:

array_mayor_2=
[False False  True  True]

Con los resultados lógicos podemos realizar operaciones para poder operar con ellos. Para ello, podemos emplear las siguientes funciones:

  • Función sum.- función que cuantifica el número de elementos que cumplen la función.
  • Función nonzero.- función que retorna el índice de la posición en la dimensión.

En el siguiente snippet se muestran ejemplos a partir del array inicial:

print(f'array[array_mayor_2]=\n{array[array_mayor_2]}\n')
print(f'array_mayor_2.sum()=\n{array_mayor_2.sum()}\n')  
print(f'array_mayor_2.nonzero()=\n{array_mayor_2.nonzero()}\n')  
print(f'(array > 2).nonzero()=\n{(array > 2).nonzero()}\n')  

La salida por consola es la siguiente:

array[array_mayor_2]=
[3 4]

array_mayor_2.sum()=
 2

array_mayor_2.nonzero()=
(array([2, 3]),)

(array > 2).nonzero()=
(array([2, 3]),)

Para poder realizar un tratamiento más específico, podemos utilizar la función where en la cuál podemos declarar qué valor asignar al resultado si cumple una condición, o bien, cuando no la cumple. En el siguiente snippet se muestra un ejemplo de uso de la función where:

array_where = np.where(array > 2)
print(f'np.where(array > 2)=\n{array_where}\n')
array_where_2 = np.where(array > 2, 1, 0)  
print(f'np.where(array > 2, 1, 0)=\n{array_where_2}\n')

La salida por consola es la siguiente:

 np.where(array > 2)=
  (array([2, 3]),)

  np.where(array > 2, 1, 0)=
  [0 0 1 1]

Otra forma de trabajar con predicados sin la función where es declarando un predicado con una condición. Una vez creado el predicado, lo aplicamos en el array como una indexación asignando el valor para el caso de éxito, o bien, utilizando el carácter ~ para el caso de no cumplirse. En el siguiente snippet se muestra un ejemplo de uso de ejemplo:

array2 = np.array([1, 2, 3, 4])
array2_mayor_2 = array2 > 2
array2[array2_mayor_2] = 1  
array2[~array2_mayor_2] = 0  
print(f'array2={array2}')

La salida por consola es la siguiente:

array2=[0 0 1 1]

En la siguiente entrada con título Numpy III presentaré los últimos ejemplos y finalizaré la serie de entradas relacionadas con la librería Numpy.

Numpy I

Numpy es una librería Python open-source para computación científica que permite tener el poder de computación de lenguajes como C o Fortran en lenguaje Python. En la presente entrada, Numpy I, realizaré una breve presentación y realizaré unos ejemplos básicos.

Las características generales de Numpy son las siguientes:

  1. Permite trabajar con matrices N dimensionales.
  2. Proporciona herramientas de computación numérica ofreciendo un conjunto de funciones matemáticas complejas.
  3. Es interoperable, con lo cual, permite trabajar con amplias plataformas, funciona con bibliotecas distribuidas y de GPU.
  4. El núcleo de la librería es código C bien optimizado.
  5. Fácil de usar.
  6. Es una librería de código abierto.

Los ejemplos practicos que mostraré en los siguientes apartados están desarrollados con Python 3.6. Las dependencias de las librerías utilizadas son las siguientes: numpy y matplotlib; y, para la utilización de las funciones en cada módulo, es necesario importar la librería de la siguiente forma:

import numpy as np

Los ejemplos de utilización de la librería Numpy a presentar en esta entrada son los siguientes:

  1. Creación de arrays n-dimensionales.
  2. Generación e inicialización de arrys n-dimensionales.
  3. Indexación de elementos en arrays n-dimensionales.
  4. Funciones básicas en arrays n-dimensionales.

1.- Creación de arrays N dimensaionales.

La creación de un array la realizaremos empleando la función array y, para determinar el tipo de los elementos del array, emplearemos la función dtype. En el siguiente ejemplo se define una array de dos dimensiones a partir de una lista.

lst = [[1, 2, 3],
       [4, 5, 6]]
arrayld = np.array(lst)
print(f'Array integer:\n{arrayld}')
print(f'Type={arrayld.dtype}')

La salida por consola es la siguiente:

Array integer:
[[1 2 3]
[4 5 6]]
Type=int64

Para crear un array de elementos de tipos reales a partir del array anterior, utilizamos la función astype con el tipo float32 definidos en Numpy, el snippet ejemplo es el siguiente:

array_float_32 = arrayld.astype(np.float32)
print(f'Array float32:\n{array_float_32}')
print(f'Type={array_float_32.dtype}\n')

La salida por consola es la siguiente:

Array float32:
[[1. 2. 3.]
[4. 5. 6.]]
Type=float32

Para crear un array de dos dimensiones de elementos enteros a partir de una lista, se utiliza la función array y se especifica el tipos int64. Una vez creado el array, podemos conocer sus características con las siguientes funciones:

  • itemsize.- para determinar el tamaño en bit que ocupan en el array.
  • size.- para determinar el número de elementos del array.
  • ndim.- para determinar el número de dimensiones.
  • shap.- para determinar el número de elementos por dimensión.

El snippet ejemplo es el siguiente:

array_2_dimesion = np.array([[1, 2, 3], [4, 5, 6]], dtype='int64')
print(f'array_2_dimesion=\n{array_2_dimesion}')
print(f'array_2_dimesion.itemsize={array_2_dimesion.itemsize}') 
print(f'array_2_dimesion.size={array_2_dimesion.size}') 
print(f'array_2_dimesion.ndim={array_2_dimesion.ndim}') 
print(f'array_2_dimesion.shape={array_2_dimesion.shape}\n') 

La salida por consola es la siguiente:

array_2_dimesion=
[[1 2 3]
 [4 5 6]]
array_2_dimesion.itemsize=8
array_2_dimesion.size=6
array_2_dimesion.ndim=2
array_2_dimesion.shape=(2, 3)

En el caso de un array de una dimensión, el resultado de la función shape sería el siguiente:

array_ahape =  np.array([1, 2, 3]).shape
print(f'array_ahape={array_ahape}')  

La salida por consola es la siguiente:

array_ahape=(3,)

2.- Generación e inicialización de arrays n-dimensionales.

La creación de un array n-dimensional de forma dinámica con un generador se realiza con la función fromiter. El generador debe de ser pasado como parámetro ya sea una función explícita, o bien, mediante una sentencia que defina un generador. El snippet con un ejemplo es el siguiente:

 def generator():
     for i in range(10):
         if not (i % 2):
             yield i
 gen = generator()
 array_generator = np.fromiter(gen, dtype=int)
 print(f'array_generator={array_generator}')
 generator_expression = (i for i in range(10) if i % 2)
 array_generator_expression = np.fromiter(generator_expression, dtype=int)
 print(f'array_generator_expression={array_generator_expression}')

La salida por consola es la siguiente:

array_generator=[0 2 4 6 8]
array_generator_expression=[1 3 5 7 9]
array_3_3_1=
  [[1. 1. 1.]
   [1. 1. 1.]
   [1. 1. 1.]]

Otra forma de crear arrays con inicializaciones determinadas se pueden realizar con las siguientes funciones:

  • ones.- Creación de un array n-dimensional de números reales con valor 1.
  • zeros.- Creación de un array n-dimensional de números reales con valor 0.
  • eye.- Creación de un array n-dimensional cuya diagonal tiene valor 1.
  • diag.- Creación de un array n-dimensional cuya diagonal tiene un valor pasado por parámetro.
  • arrange.- Creación de un array n-dimensional cuya diagonal tiene el rango de valores pasados por parámetro.
  • linspace.- Creación de un array n-dimensional cuyos de x elementos pasados por paámetros y valores comprendidos entre un valor mínimo y máximo.

El snippet de código con ejemplos es el siguiente:

 # Inicializadores de arrays.
 array_3_3_1 = np.ones((3, 3))
 print(f'array_3_3_1=\n{array_3_3_1}\n')
 array_3_3_0 = np.zeros((3, 3))
 print(f'array_3_3_0=\n{array_3_3_0}\n')
 array_eye_diagonal = np.eye(3)
 print(f'array_eye_diagonal=\n{array_eye_diagonal}\n')
 array_diagonal = np.diag((3, 3, 3))
 print(f'array_diagonal=\n{array_diagonal}\n')
 array_arange_float = np.arange(4., 10.)  
 print(f'array_arange_float=\n{array_arange_float}\n')
 array_arange_int = np.arange(5)  
 print(f'array_arange_int=\n{array_arange_int}\n')
 array_arange_interval = np.arange(1., 11., 2)  
 print(f'array_arange_interval=\n{array_arange_interval}\n')
 array_insterval_space_1 = np.linspace(0., 1., num=5)  
 print(f'array_insterval_space_1=\n{array_insterval_space_1}\n')
 array_insterval_space_2 = np.linspace(0., 1., num=6)  
 print(f'array_insterval_space_2=\n{array_insterval_space_2}\n')

La salida por consola es la siguiente:

  array_3_3_0=
  [[0. 0. 0.]
   [0. 0. 0.]
   [0. 0. 0.]]
  array_eye_diagonal=
  [[1. 0. 0.]
   [0. 1. 0.]
   [0. 0. 1.]]
  array_diagonal=
  [[3 0 0]
   [0 3 0]
   [0 0 3]]
  array_arange_float=
  [4. 5. 6. 7. 8. 9.]
  array_arange_int=
  [0 1 2 3 4]
  array_arange_interval=
  [1. 3. 5. 7. 9.]
  array_insterval_space_1=
  [0.   0.25 0.5  0.75 1.  ]
  array_insterval_space_2=
  [0.  0.2 0.4 0.6 0.8 1. ]

3.- Indexación de elementos en arrays n-dimensionales.

El acceso a los elementos de los array se realiza indicando la posición entre corchetes. Unos ejemplos de acceso a elementos de un array de una y dos dimensiones son los que se muestran en el siguiente snippet de código:

array = np.array([1, 2, 3])
print(f'array=\n{array}\n')
print(f'array[0]=\n{array[0]}')
print(f'array[1]=\n{array[1]}\n')
print(f'array[:2]=\n{array[:2]}\n')
print(f'array[1:]=\n{array[1:]}\n')
array_22 = np.array([[1, 2, 3], [4, 5, 6]])
print(f'array=\n{array_22}\n')
print(f'array_22[0,0]=\n{array_22[0, 0]}')
print(f'array_22[-1,-1]=\n{array_22[-1, -1]}\n')
print(f'array_22[0]=\n{array_22[0]}\n') 
print(f'array_22[:, 0]=\n{array_22[:, 0]}\n')
print(f'array_22[:, :2]=\n{array_22[:, :2]}\n')

La salida por consola es la siguiente:

array=
[1 2 3]
array[0]=
1
array[1]=
2
array[:2]=
[1 2]
array[1:]=
[2 3]
array=
[[1 2 3]
 [4 5 6]]
array_22[0,0]=
1
array_22[-1,-1]=
6
array_22[0]=
[1 2 3]
array_22[:, 0]=
[1 4]
array_22[:, :2]=
[[1 2]
 [4 5]]

4.- Funciones básicas en arrays n-dimensionales.

La manipulación de los elementos de los array n-dimensionales se puede realizar accediendo de forma directo, o bien, utilizando operadores matemáticos. En el siguiente snippet, se muestra unos ejemplos de manipulación de elementos:

 # Forma1: Suma 1 a los elementos de la lista
 list = [[1, 2, 3], [4, 5, 6]]
 list_mas_1 = [[cell + 1 for cell in row] for row in list]  # Incrementamos en 1
 print(f'list_mas_1=\n{list_mas_1}\n')
 # Forma2: Suma 1
 array_nd_list_mas_1 = np.add(list, 1)
 print(f'array_nd_list_mas_1=\n{array_nd_list_mas_1}\n')
 # Forma3: Suma 1
 ndarray_3 = np.array(list)
 array_nd_list_mas_12 = ndarray_3 + 1
 print(f'array_nd_list_mas_12=\n{array_nd_list_mas_12}\n')
 ndarray_cuadrada = np.array(list)
 array_nd_list_cuadrado = ndarray_cuadrada**2
 print(f'array_nd_list_cuadrado=\n{array_nd_list_cuadrado}\n')

La salida por consola es la siguiente:

list_mas_1=
[[2, 3, 4], [5, 6, 7]]
array_nd_list_mas_1=
[[2 3 4]
 [5 6 7]]
array_nd_list_mas_12=
[[2 3 4]
 [5 6 7]]
array_nd_list_cuadrado=
[[ 1  4  9]
 [16 25 36]]

Otras funciones básicas pueden ser las siguientes:

  • reduce.- función de suma de columnas de un array n-dimensional.
  • sum.- función de suma de elemntos de una terminada dimensión.
  • mean.- función de cálculo de la media.
  • std.- función de cálculo de la desviación típica.
  • var.- función de la varianza.
  • max.- función de cálculo del valor máximo.
  • min.- función de cálculo del vfalor mínimo

El snippet con ejemplos de utilización de uso de dichas funciones es el siguiente:

  ndarray = np.array(list)
  print(f'np.add.reduce(ndarray)={np.add.reduce(ndarray)}')  
  print(f'np.sum(ndarray, axis=0)={np.sum(ndarray, axis=0)}')  
  print(f'np.sum(ndarray, axis=1)={np.sum(ndarray, axis=1)}')  
  print(f'ndarray.sum()={ndarray.sum()}')  
  print(f'ndarray.mean()={ndarray.mean()}')
  print(f'ndarray.std()={ndarray.std()}')
  print(f'ndarray.var()={ndarray.var()}')
  print(f'ndarray.max()={ndarray.max()}')
  print(f'ndarray.min()={ndarray.min()}')
  print(f'ndarray.argmax()={ndarray.argmax()}')
  print(f'ndarray.argmin()={ndarray.argmin()}')

La salida por consola es la siguiente:

np.add.reduce(ndarray)=[5 7 9]
np.sum(ndarray, axis=0)=[5 7 9]
np.sum(ndarray, axis=1)=[ 6 15]
ndarray.sum()=21
ndarray.mean()=3.5
ndarray.std()=1.707825127659933
ndarray.var()=2.9166666666666665
ndarray.max()=6
ndarray.min()=1
ndarray.argmax()=5
ndarray.argmin()=0

En la siguiente entrada, Numpy II, continuaré describiendo operaciones con arrays en Numpy.