Skip to content
Snippets Groups Projects
Commit 00b01775 authored by Henrique Varella Ehrenfried's avatar Henrique Varella Ehrenfried
Browse files

Create a english readme

parent 5c0a23c6
Branches
No related tags found
No related merge requests found
[submodule "mapping_protocols"]
path = mapping_protocols
url = git@gitlab.c3sl.ufpr.br:simcaq/mapping_protocols.git
# Administrador de base de dados SimCAQ/SMPPIR #
Esse repositório implementa a classe DatabaseTable e funções para verificar pareamento entre
diferentes anos inseridos no banco de dados. A ferramenta é desenvolvida em Python 3, e usa
como base arquivos de mapeamento em formato CSV.
Para a utilização a partir da linha de comando, a CLI manage.py pode ser utilizada sem
que se invoque manualmente as funções a partir da linha de comando Python.
## Requisitos ##
O utilitário foi desenvolvido em Python 3 usando a biblioteca SQLAlchemy com vistas ao banco
de dados MonetDB. Versões futuras podem ter modificações visando a compatibilidade com outros
bancos de dados, aproveitando as capacidades da biblioteca base.
Para a instalação dos requisitos conforme usados durante o desenvolvimento, o arquivo
requirements.txt pode ser usado como base (Recomenda-se o uso de um ambiente virtual).
```bash
(env) $ pip install -r requirements.txt
```
A CLI depende do módulo manage.py. Demais dependências serão listadas a seguir.
### Requisitos para a interface com a base de dados ###
* pymonetdb
* SQLAlchemy
* sqlalchemy-monetdb
### Requisitos para geração de pareamentos ###
* numpy
* pandas
* xlrd
* XlsxWriter
## Interface de linha de comando ##
A invocação da CLI utiliza o padrão do pacote manage.py, que é:
```bash
$ python manage.py [commando] [argumentos posicionais] [argumentos opcionais com valor]
```
Os comandos já implementados são:
* create: Cria a tabela conforme definido no protocolo de mapeamento.
```bash
$ python manage.py create <nome da tabela>
```
O único argumento usado é o nome da tabela. O script procurará por um protocolo de
mapeamento com o mesmo nome para a busca do esquema das colunas.
* insert: insere um arquivo de dados em formato CSV ou similar em uma tabela existente.
```bash
$ python manage.py insert <caminho para o arquivo> <nome da tabela> <ano> [--sep separador] [--null valor_nulo]
```
O caminho para o arquivo deve ser absoluto. A tabela utilizada deve existir e estar
sincronizada com o protocolo de mapeamento correspondente. O separador padrão utilizado
é ponto e vírgula (';'); caso outros separadores sejam utilizados pelo arquivo fonte,
devem ser especificados com --sep (por exemplo --sep \\| para pipe). O valor nulo padrão
é string vazia. Caso outro valor seja usado, deve ser especificado com --null.
* drop: derruba uma tabela do banco de dados.
```bash
$ python manage.py drop <nome da tabela>
```
O comando não contorna chaves estrangeiras que apontem para a tabela, e o banco de dados
pode retornar um erro caso exista alguma.
* remap: sincroniza uma tabela com o protocolo de mapeamento.
```bash
$ python manage.py remap <nome da tabela>
```
Esse comando deve ser utilizado sempre que um protocolo de mapeamento for atualizado.
O remapeamento permite a criação de novas colunas, derrubada de colunas existentes,
renomeamento de colunas e mudança de tipo. Dependendo do tamanho da tabela, o uso de
memória primária pode ser intenso.
* generate_pairing_report: gera relatórios de pareamento para comparação de dados ano
a ano.
```bash
$ python manage.py generate_pairing_report [--output xlsx|csv]
```
Os relatórios são criados na pasta pairing. Caso o formato não seja especificado,
csv será utilizado (um arquivo será criado para cada tabela). Caso xlsx seja o formato
utilizado, um arquivo será criado com todas as tabelas separadas em diferentes planilhas.
* generate_backup: Cria/Atualiza o arquivo monitorado para o backup.
```bash
$ python manage.py generate_backup
```
O arquivo é criado ou atualizado na máquina onde o banco de dados da produção está,
o procedimento de backup da equipe de infraestrutura o monitora para realizar o procedimento.
\ No newline at end of file
# Administrador de base de dados SimCAQ/SMPPIR # # HOTMapper #
Esse repositório implementa a classe DatabaseTable e funções para verificar pareamento entre This repository implements the HOTMapper, a tool that allows the user to manage his historical data using a mapping protocol
diferentes anos inseridos no banco de dados. A ferramenta é desenvolvida em Python 3, e usa
como base arquivos de mapeamento em formato CSV.
Para a utilização a partir da linha de comando, a CLI manage.py pode ser utilizada sem ## Requirements ##
que se invoque manualmente as funções a partir da linha de comando Python.
## Requisitos ## * Python 3 (It's recommended that you use a virtual environment, such as virtualenv)
* MonetDB (We plan to make other databases to work with HOTMapper in the future)
O utilitário foi desenvolvido em Python 3 usando a biblioteca SQLAlchemy com vistas ao banco ## Installation ##
de dados MonetDB. Versões futuras podem ter modificações visando a compatibilidade com outros
bancos de dados, aproveitando as capacidades da biblioteca base.
Para a instalação dos requisitos conforme usados durante o desenvolvimento, o arquivo ----
requirements.txt pode ser usado como base (Recomenda-se o uso de um ambiente virtual). **NOTICE:**
We suppose that you already have Python 3.x installed in you computer and that all the following commands that use Python will use the Python 3.x
--
1) Install virtualenv
1a) On Linux/macOS
```bash ```bash
(env) $ pip install -r requirements.txt $ sudo -H pip install virtualenv
``` ```
A CLI depende do módulo manage.py. Demais dependências serão listadas a seguir. 1b) On Windows (with administrator privilleges)
### Requisitos para a interface com a base de dados ### ```cmd
$ pip install virtualenv
```
* pymonetdb
* SQLAlchemy
* sqlalchemy-monetdb
### Requisitos para geração de pareamentos ### 2) Clone this repository
```bash
$ git clone git@gitlab.c3sl.ufpr.br:tools/hotmapper.git
```
* numpy 3) Go to the repository
* pandas
* xlrd
* XlsxWriter
## Interface de linha de comando ## ```bash
$ cd hotmapper
```
A invocação da CLI utiliza o padrão do pacote manage.py, que é: 4) Create a virtual environment
```bash ```bash
$ python manage.py [commando] [argumentos posicionais] [argumentos opcionais com valor] $ virtualenv env
``` ```
Os comandos já implementados são: 5) Start the virtual environment
* create: Cria a tabela conforme definido no protocolo de mapeamento. 5a) On Linux/macOS
```bash ```bash
$ python manage.py create <nome da tabela> $ source env/bin/activate
``` ```
O único argumento usado é o nome da tabela. O script procurará por um protocolo de 5b) On Windows (with administrator privilleges)
mapeamento com o mesmo nome para a busca do esquema das colunas.
```cmd
$ .\env\Scripts/activate
```
* insert: insere um arquivo de dados em formato CSV ou similar em uma tabela existente. 6) Install dependencies
```bash ```bash
$ python manage.py insert <caminho para o arquivo> <nome da tabela> <ano> [--sep separador] [--null valor_nulo] $ pip install -r requirements.txt
``` ```
O caminho para o arquivo deve ser absoluto. A tabela utilizada deve existir e estar ## Interface de linha de comando ##
sincronizada com o protocolo de mapeamento correspondente. O separador padrão utilizado
é ponto e vírgula (';'); caso outros separadores sejam utilizados pelo arquivo fonte,
devem ser especificados com --sep (por exemplo --sep \\| para pipe). O valor nulo padrão
é string vazia. Caso outro valor seja usado, deve ser especificado com --null.
* drop: derruba uma tabela do banco de dados. The CLI (Command Line Interface) uses the standart of the manage.py package, which means that to invoke a command you should use the following pattern:
```bash ```bash
$ python manage.py drop <nome da tabela> $ python manage.py [COMMAND] [POSITIONAL ARGUMENTS] [OPTIONAL ARGUMENTS]
``` ```
O comando não contorna chaves estrangeiras que apontem para a tabela, e o banco de dados Where COMMAND can be:
pode retornar um erro caso exista alguma.
* remap: sincroniza uma tabela com o protocolo de mapeamento. * create: Create a table using the mapping protocol.
```bash ```bash
$ python manage.py remap <nome da tabela> $ python manage.py create <table_name>
``` ```
Esse comando deve ser utilizado sempre que um protocolo de mapeamento for atualizado. **Notice** that the HOTMapper will use the name of the protocol as the name of the table.
O remapeamento permite a criação de novas colunas, derrubada de colunas existentes,
renomeamento de colunas e mudança de tipo. Dependendo do tamanho da tabela, o uso de
memória primária pode ser intenso.
* generate_pairing_report: gera relatórios de pareamento para comparação de dados ano * insert: Insert a CSV file in an existing table.
a ano.
```bash
$ python manage.py insert <full/path/for/the/file> <table_name> <year> [--sep separator] [--null null_value]
```
```
<full/path/for/the/file> : The absolute file path
<table_name>: The name of the table where the file will be inserted
<year>: The column of the mapping protocol that the HOTMapper should use to insert data
[--sep separator]: The custom separtor of the CSV. To change it you should just replace 'separator' with the token your file uses
[--null null_value]: Define what will replace the null value. Replace the 'null_value' with what you wish to do.
```
* drop: Delete a table from the database
```bash
$ python manage.py drop <table_name>
```
**NOTICE:** The command does not take care of foreign keys that points to the table that are being deleted. Therefore, the database can produce errors.
* remap: syncronize a table with the mapping protocol.
```bash
$ python manage.py remap <table_name>
```
You should use this command everytime a mapping protocol is updated.
The remap allows the creation of new columns, the drop of existent columns, the renaming of columns and the change of type of columns. Be aware that the bigger the table the bigger the usegae of RAM memory.
* generate_pairing_report: generate reports to compare data from diferent years.
```bash ```bash
$ python manage.py generate_pairing_report [--output xlsx|csv] $ python manage.py generate_pairing_report [--output xlsx|csv]
``` ```
Os relatórios são criados na pasta pairing. Caso o formato não seja especificado, The reports will be created in the folder "pairing"
csv será utilizado (um arquivo será criado para cada tabela). Caso xlsx seja o formato
utilizado, um arquivo será criado com todas as tabelas separadas em diferentes planilhas.
* generate_backup: Cria/Atualiza o arquivo monitorado para o backup.
* generate_backup: Create/Update a file to backup the database.
```bash ```bash
$ python manage.py generate_backup $ python manage.py generate_backup
``` ```
\ No newline at end of file
O arquivo é criado ou atualizado na máquina onde o banco de dados da produção está,
o procedimento de backup da equipe de infraestrutura o monitora para realizar o procedimento.
\ No newline at end of file
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment