API

Adaptador Base

calculadora_do_cidadao.adapters.import_from_json(path: Path, json_path: List[str]) → Iterable[NamedTuple]

Imports data form a JSON file path creating an iterable of named tuples similar to the Rows’s import functions.

json_path is a sequence of keys or array indexes to get to the array with the desired data.

class calculadora_do_cidadao.adapters.Adapter(exported_csv: Optional[Path] = None)

This is the base adapter, all adapters should inherit from it. Its children require at least a url and file_type class variables.

adjust(original_date: Union[date, datetime, int, float, str], value: Optional[Union[Decimal, float, int]] = 0, target_date: Optional[Union[date, datetime, int, float, str]] = None) → Decimal

Main method of an adapter API, the one that actually makes the monetary correction using adapter’s data. It requires a datetime.date used as the reference for the operation.

If no value if given, it returns considering the value is decimal.Decimal(‘1’).

If no target_date is given, it returns considering the target date is datetime.date.today().

aggregate()

Being disaggregated here means the index for each month is a percentage relative to the previous month. However the adjust method gets way simpler if the indexes as stored as the percentage of the month before the first month of the series. For example, if a given index starts at January 1994, and all values should be a percentage referring to December 1993.

property cookies: dict

Wrapper to get COOKIES if set, avoiding error if not set.

download() → Iterable[Tuple[date, Decimal]]

Wrapper to use the Download class and pipe the result to rows imported method, yielding a series of rows parsed by rows.

export(include_name: bool = False) → Iterable[dict]

Wraps adapter’s data in a sequence of dictionaries to be used with rows.import_from_dicts.

export_index(key, include_name: bool = False) → dict

Export a given index as a dictionary to be used with rows.import_from_dicts.

abstract property file_type: str

File type of the response from the url, usually html or xls.

from_csv(path: Path) → Iterable[Tuple[date, Decimal]]

Load adapter’s data from a CSV file. If the CSV file has two columns it is assumed it was generated with the to_csv method. If it has 3 columns, it is assumed it is a export of all adapters’ data generated by the CLI.

property headers: Optional[dict]

Wrapper to get HEADERS if set, avoiding error if not set.

property import_kwargs: Iterable[dict]

Wrapper to get IMPORT_KWARGS if set, avoiding error if not set.

invalid_date_error_message(wanted: date) → str

Helper to generate an error message usually used together with AdapterDateNotAvailableError.

property post_data: Optional[dict]

Wrapper to get POST_DATA if set, avoiding error if not set.

round_date(obj: Union[date, datetime, int, float, str], validate: bool = False) → date

Method to round Date objects to hold day = 1, as indexes usually refers to monthly periods, not daily periods. It also validates if the intended date is valid and in the adapter data range.

abstract serialize(row: NamedTuple) → Iterable[Optional[Tuple[date, Decimal]]]

This method should be a generator that receives a row from rows (which is a NamedTuple) and yields None if the row does not hold any valid index data, or yields calculadora_do_cidadao.typing.Index type if the row has valid data. A row can yield more than one calculadora_do_cidadao.typing.Index.

property should_aggregate: bool

Wrapper to get SHOULD_AGGREGATE if set, avoiding error if not set.

property should_unzip: bool

Wrapper to get SHOULD_UNZIP if set, avoiding error if not set.

to_csv(path: Path) → Path

Export the adapter’s data to a CSV file.

abstract property url: str

The URL where to get data from.

exception calculadora_do_cidadao.adapters.AdapterNoImportMethod

To be used when the adapter has no rows import method set.

exception calculadora_do_cidadao.adapters.AdapterDateNotAvailableError

To be used when using a date outside of the range available.

Adaptadores

DIEESE Cesta Básica

class calculadora_do_cidadao.CestaBasica(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index. If no cities variable is created, it averages the value of all available cities in any given date (this is used in subclasses).

static post_processing(body: bytes) → bytes

Fixes broken HTML syntax in DIEESE’s the source file.

serialize(row: NamedTuple) → Iterable[Optional[Tuple[date, Decimal]]]

Serialize method to unpack rows’s row into a tuple. Calculates the mean for adapters including different cities if needed.

class calculadora_do_cidadao.CestaBasicaCentroOeste(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index including Brasília, Cuiabá, Campo Grande and Goiânia.

class calculadora_do_cidadao.CestaBasicaNordeste(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index including Aracajú, Fortaleza, João Pessoa, Maceió, Natal, Recife, Salvador, São Luís and Teresina.

class calculadora_do_cidadao.CestaBasicaNorte(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index including Belém, Boa Vista, Macapá, Manaus, Palmas, Porto Velho and Rio Branco.

class calculadora_do_cidadao.CestaBasicaSudeste(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index including Belo Horizonte, Rio de Janeiro, São Paulo and Vitória.

class calculadora_do_cidadao.CestaBasicaSul(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index including Curitiba, Florianópolis and Porto Alegre.

class calculadora_do_cidadao.CestaBasicaAracaju(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Aracajú.

class calculadora_do_cidadao.CestaBasicaBelem(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Belém.

class calculadora_do_cidadao.CestaBasicaBeloHorizonte(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Belo Horizonte.

class calculadora_do_cidadao.CestaBasicaBoaVista(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Boa Vista.

class calculadora_do_cidadao.CestaBasicaBrasilia(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Brasília.

class calculadora_do_cidadao.CestaBasicaCampoGrande(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Campo Grande.

class calculadora_do_cidadao.CestaBasicaCuiaba(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Cuiabá.

class calculadora_do_cidadao.CestaBasicaCuritiba(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Curitiba.

class calculadora_do_cidadao.CestaBasicaFlorianopolis(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Florianópolis.

class calculadora_do_cidadao.CestaBasicaFortaleza(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Fortaleza.

class calculadora_do_cidadao.CestaBasicaGoiania(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Goiânia.

class calculadora_do_cidadao.CestaBasicaJoaoPessoa(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for João Pessoa.

class calculadora_do_cidadao.CestaBasicaMacae(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Macaé.

class calculadora_do_cidadao.CestaBasicaMacapa(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Macapá.

class calculadora_do_cidadao.CestaBasicaMaceio(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Maceió.

class calculadora_do_cidadao.CestaBasicaManaus(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Manaus.

class calculadora_do_cidadao.CestaBasicaNatal(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Natal.

class calculadora_do_cidadao.CestaBasicaPalmas(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Palmas.

class calculadora_do_cidadao.CestaBasicaPortoAlegre(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Porto Alegre.

class calculadora_do_cidadao.CestaBasicaPortoVelho(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Porto Velho.

class calculadora_do_cidadao.CestaBasicaRecife(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Recife.

class calculadora_do_cidadao.CestaBasicaRioBranco(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Rio Branco.

class calculadora_do_cidadao.CestaBasicaRioDeJaneiro(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Rio de Janeiro.

class calculadora_do_cidadao.CestaBasicaSalvador(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Salvador.

class calculadora_do_cidadao.CestaBasicaSaoLuis(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for São Luís.

class calculadora_do_cidadao.CestaBasicaSaoPaulo(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for São Paulo.

class calculadora_do_cidadao.CestaBasicaTeresina(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Teresina.

class calculadora_do_cidadao.CestaBasicaVitoria(exported_csv: Optional[Path] = None)

Adapter for DIEESE’s basic shopping basket (cesta básica) price index for Vitória.

FED’s Consumer Price Index for All Urban Consumers: All Items

class calculadora_do_cidadao.AllUrbanCityAverage(exported_csv: Optional[Path] = None)

Adapter for FED’s Consumer Price Index for All Urban Consumers: All Items.

serialize(row: NamedTuple) → Iterable[Optional[Tuple[date, Decimal]]]

Serialize method to unpack Rows’s row into a tuple.

IGP-M

class calculadora_do_cidadao.Igpm(exported_csv: Optional[Path] = None)

Adapter for FGV’s IGPM series.

serialize(row: NamedTuple) → Iterable[Optional[Tuple[date, Decimal]]]

Serialize method to discard the rows that are not valid data.

Família IPCA & INPC

class calculadora_do_cidadao.adapters.ibge.IbgeAdapter(exported_csv: Optional[Path] = None)

This base class is incomplete and should not be used directly. It missed the url class variable to be set in its children. In spite of that, it implements the serialize and settings that work with most price adjustment indexes done by IBGE.

serialize(row: NamedTuple) → Iterable[Optional[Tuple[date, Decimal]]]

Serialize used for different IBGE price adjustment indexes.

class calculadora_do_cidadao.Inpc(exported_csv: Optional[Path] = None)

Adapter for IBGE’s INPC series.

class calculadora_do_cidadao.Ipca(exported_csv: Optional[Path] = None)

Adapter for IBGE’s IPCA series.

class calculadora_do_cidadao.Ipca15(exported_csv: Optional[Path] = None)

Adapter for IBGE’s IPCA-15 series.

class calculadora_do_cidadao.IpcaE(exported_csv: Optional[Path] = None)

Adapter for IBGE’s IPCA-E series.

Download

class calculadora_do_cidadao.download.Download(url: str, should_unzip: bool = False, headers: Optional[dict] = None, cookies: Optional[dict] = None, post_data: Optional[Union[dict, Iterable[dict]]] = None, post_processing: Optional[Callable[[bytes], bytes]] = None)

Abstraction for the download of data from the source.

It can be initialized informing that the resulting file is a Zip archive that should be unarchived.

Cookies and headers are just relevant if the URL uses HTTP (and, surely both are optional).

The post_data dictionary is used to send an HTTP POST request (instead of the default GET). If this field is a sequence of dictionaries, it will result in one request per dictionary.

The post_processing as a bytes to bytes function that is able to edit the contents before saving it locally, allowing adapter to fix malformed documents.

http() → Iterable[bytes]

Download the source file(s) using HTTP.

static unzip(path: Path, target: Path) → Path

Unzips the first file of an archive and returns its path.

exception calculadora_do_cidadao.download.DownloadMethodNotImplementedError

To be used when the Download class does not have a method implemented to download a file using the protocol specified in the url argument.

Campos

class calculadora_do_cidadao.fields.DateField

DateField which supports different date formats, including Brazilian

classmethod deserialize(value: Union[date, datetime, int, float, str], *args, **kwargs) → date

Deserialize a value just after importing it

cls.deserialize should always return a value of type cls.TYPE or None.

class calculadora_do_cidadao.fields.PercentField

Field for reading percentage in Brazilian Portuguese format.

classmethod deserialize(value: str) → Decimal

Deserialize decimals using a comma as a decimal separator.