Meu Contracheque :bookmark_tabs:

Sobre este repositório :open_book:

Meu contracheque é um pacote Python, acessível via interface CLI, utilizado para buscar informações de contracheques via web scraping.

A primeira versão deste pacote conta com a busca de contracheques dos servidores públicos do Estado de Minas Gerais, disponibilizados na aba "Emissão de Contracheque" do site Portal do Servidor.

Orientações gerais

• Instalação de Python 3.

• Utilização de navegador Google Chrome.

• Não copie e cole os comandos abaixo cegamente, modifique os textos entre "< >" com as informações pertinente à sua realidade.

Setup da máquina

Recomendo utilizar uma pasta específica para execução dos comandos do pacote, criando e ativando ambiente Python dentro da mesma, conforme sugerido abaixo:

Pasta para execução dos comandos e ativação de ambiente python

• Necessário instalação de Python 3 antes da execução os comandos abaixo para ambos os sistemas operacionais.

• Sistema operacional Linux:

# Criação da pasta para execução do projeto
$ mkdir <nome-desejado-para-pasta>

# Acessando a pasta criada
$ cd <nome-desejado-para-pasta>

# Criação ambiente python
$ python3 -m venv venv

# Ativação ambiente python
$ source venv/bin/activate

• Sistema operacional Windows:
  • Recomendo a utilização de Git Bash disponível com instalação de Git para Windows.

# Criação da pasta para execução do projeto
$ mkdir <nome-desejado-para-pasta>

# Acessando a pasta criada
$ cd <nome-desejado-para-pasta>

# Criação ambiente python
$ python -m venv venv

# Ativação ambiente python
$ source venv/Scripts/activate

Instalação cromedriver

• Identifique a versão do navegador Chrome instalado em sua máquina digitando chrome://version/ na barra de navegação do mesmo.

• Realize o download do drive específico para versão chrome instalada em sua máquina.

• Necessário descompactar arquivo baixado.

• Para sistema operacional Windows basta incluir o caminho do arquivo descompactado no path.

• Para sistema operacional Linux incluir o arquivo no caminho /usr/local/bin.

Passando suas credenciais para buscar o contracheque

• As credenciais masp e senha para busca de contracheque poderão ser passadas de duas maneiras, a saber:

  • Utilização das flags -m e -s durante a chamada das funções

  $ meu-contracheque mg -m <masp-usuario> -s <senha-usuario> mais-recente
  

  • Arquivo .env na raiz da pasta aonde os comandos serão executados.

  # Estrutura arquivo .env a ser criado
  MASP=<masp-usuario>
  PORTAL_PWD=<senha-usuario>
  

Visualizando Navegador Chrome durante a execução

• Por padrão execução não mostra navegador Chrome "trabalhando". Flag --headless foi criada e definida como padrão True para tal. Possível utilizar flag --no-headless durante a execução para que o navegador seja acionado na tela, conforme demostrado abaixo:

$ meu-contracheque mg -m <masp-usuario> -s <senha-usuario> --no-headless

Baixando arquivo pdf

• Por padrão execução fará o download do arquivo pdf. Flag --pdf foi criada e definida como padrão True para tal. Possível utilizar flag --no-pdf durante a execução sem o download, conforme demostrado abaixo:

$ meu-contracheque mg -m <masp-usuario> -s <senha-usuario> --no-pdf

obs.: Arquivo pdf gerado será salvo na pasta contracheques. A mesma será criada caso não exista.

Instalação

O meu-contracheque está disponível no Python Package Index - PyPI e pode ser instalado utilizando-se o comando abaixo:

# Antes de executar o comando abaixo lembre-se que ambiente Python deverá estar ativo
$ pip install meu-contracheque

Utilização

O resultado da execução dos comandos abaixo será a criação do arquivo "contracheques.csv". As informações retornadas estão organizadas em formato tabular. Toda execução subscreve o arquivo "contracheques.csv" anteriormente gerado.

• Buscar informações do contracheque mais recente:

$ meu-contracheque mg mais-recente

• Buscar informações de todos os contracheques emitidos:

Obs.: Este comando deve ser utilizado para períodos sem interrupção na geração dos contracheques.

$ meu-contracheque mg todos

Obs.: Esta opção poderá demorar, a depender do número de contracheques a serem exportados. O log de execução do comando será exibido no terminal, facilitando o entendimento que está acontecendo.

• Buscar informações de todos os contracheques emitidos com períodos em que a emissão foi interrompida:

Obs.: Deverá ser informado período para qual a busca se encerrará. Exemplo. Primeiro contracheque emitido em 01/2010 deverá ser passado flag -sp 12/2009 (para que seja retornado o contracheque de 01/2010 e a rotina seja encerrada no mês 12/2009).

$ meu-contracheque mg ate-periodo-inicial -sp 12/2009

Obs.: Esta opção poderá demorar, a depender do número de contracheques a serem exportados. O log de execução do comando será exibido no terminal, facilitando o entendimento que está acontecendo.

Encontrou algo errado no código ou quer melhorá-lo

Abra um Issue ou um Pull Request!!! Este tipo de contribuição auxiliará no crescimento do código de maneira exponencial! Se deseja colocar a mão na massa, acesse as sugestões de melhorias já documentadas nos Issues com a tag "enhancement".

Controle de alterações

Documentação das principais alterações sofridas por este repositório. Baseado na filosofia Mantenha um Changelog.

[0.3.1] - 2022-11-16

• Implementa flag --no-headless na busca do último contracheque

[0.3.0] - 2022-11-13

• Refaz o processo para novo portal do servidor mg
• Somente função last period funcionando no momento

[0.2.5] - 2022-03-09

• Melhora geração arquivo pdf

[0.2.4] - 2022-03-09

• Corrige nome arquivo pdf

[0.2.3] - 2022-03-09

• Cria flag para pdf para determinar download do contracheque (--pdf/--no-pdf)
• Melhora Readme.md

[0.2.2] - 2022-03-09

• Flags --masp e --senha passados após subcomando mg
• Cria flag para determinar se Chrome ficará headless durante execução (--headless/--no-headless)
• Melhora Readme.md

[0.2.1] - 2022-03-08

• Chrome headless durante execução

[0.2.0] - 2021-12-27

• Inclusão comando ate-periodo-inicial
• Trocando print por click.echo para melhorar interface usuário no windows

[0.1.1] - 2021-12-08

• Correção encoding utf-8 durante extração código fonte da página em sistema operacional windows

[0.1.0] - 2021-12-06

• Versão inicial
  • Comando contracheque mg mais-recente para busca das informações do último contracheque disponível.
  • Comando contracheque mg todos para busca das informações de todos os contracheque disponíveis.

[0.0.1.900] - 2021-11-27

• Versão para teste de setup do pacote
  • Criação de arquivos de configuração inicial do pacote:
    • README.md,
    • CHANGELOG.md,
    • Makefile,
    • Manifest.in
    • Requirements.txt
    • setup.py