.. module:: csv_utils

Eines per tractar fitxers CSV
-----------------------------

Un fitxer en format *Comma-Separated Values* (CSV) conté dades
tabulades. Normalment, la primera línia del fitxer conté una capçalera
amb els noms de les columnes i la resta de línies contenen les dades
de cada columna. Tant els noms de les columnes a la capçalera com les
dades a cada una de les línies del fitxer estan separats per una coma
(``,``) o un altre caràcter *separador*.

L'objectiu de les dues funcions següents és calcular un diccionari a
partir de la capçalera amb els noms de les columnes, una línia, el
caràcter separador de les dades (columnes) de la línia i una altra
informació que permeti seleccionar algunes de les columnes. Aquesta
altra informació és una llista amb els noms de les columnes
seleccionades en la primera funció i una llista de booleans en la
segona.

Dissenya les funcions següents i desa-les al mòdul :mod:`csv_utils`
(fitxer :file:`csv_utils.py`).

.. function:: linia_noms_cols_a_dic(capcalera, linia, separador, columnes)

   Calcula un diccionari a partir d'una línia amb dades separades pel
   caràcter `separador`. Les claus del diccionari són els noms de les
   columnes en `columnes` i els valors són els corresponents dins
   `linia`.

   `columnes` conté un subconjunt dels noms de les columnes
   de `capcalera`.

   :param list[str] capcalera: llista amb els noms de totes les
                               columnes
   :param str linia: dades de les columnes separades amb el caràcter
                     `separador`
   :param str separador: caràcter que separa les dades de `linia`
   :param list[str] columnes: subconjunt de nom de les columnes de
			      `capcalera`
   :rtype: dict[str, str]
   :return: diccionari en què les claus són les de la llista
            `columnes` i els valors de les claus s'extreuen de
            `linia`.

	    Un cop separades les dades de `linia` mitjançant el
	    caràcter `separador`, la dada *i*-èssima correspon a la
	    columna *i*-èssima de la capçalera, és a dir, a
	    :code:`capcalera[i]`.

   Per exemple:

   .. literalinclude:: test-linia_noms_cols_a_dic.txt
      :language: pycon
      :start-after: ---- inici
      :end-before: ---- fi
   
   Disposes de més tests al fitxer :download:`test-linia_noms_cols_a_dic.txt`.

|

.. function:: linia_bools_a_dic(capcalera, linia, separador, bools)

   Calcula un diccionari a partir d'una línia amb dades separades pel
   caràcter `separador`. Les claus del diccionari són els noms de les
   columnes en `capcalera` que la seva posició corresponent en `bools`
   és :code:`True` i els valors són els corresponents dins `linia`.

   :param list[str] capcalera: llista amb els noms de totes les
                               columnes
   :param str linia: dades de les columnes separades amb el caràcter
                     `separador`
   :param str separador: caràcter que separa les dades de `linia`
   :param list[bool] bools: llista de booleans de la mateixa longitud
			    que `capcalera`
   :rtype: dict[str, str]
   :return: diccionari en què les claus són :code:`capcalera[i]`, per
	    tots els índexs :code:`i` de `capcalera` que compleixen
	    que :code:`bools[i]` és :code:`True`.
            
	    Els valors de les claus s'extreuen de `linia` de manera
            que un cop separades les dades de `linia` mitjançant el
            caràcter `separador`, la dada *i*-èssima correspon a la
            columna *i*-èssima de la capçalera, és a dir, a
            :code:`capcalera[i]`.

   Per exemple:

   .. literalinclude:: test-linia_bools_a_dic.txt
      :language: pycon
      :start-after: ---- inici
      :end-before: ---- fi
   
   Disposes de més tests al fitxer :download:`test-linia_bools_a_dic.txt`.