From 455790b6efa47216418078ef6de908a2dd9198e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=8Dtalo=20Epif=C3=A2nio?= Date: Sat, 7 Oct 2023 09:45:23 -0300 Subject: [PATCH] Translate using-the-toolbox.rst --- docs/using-the-toolbox.rst | 90 ++++++++++++++++++++++++++++++++++- docs/utilizando-a-toolbox.rst | 30 +++++++----- 2 files changed, 108 insertions(+), 12 deletions(-) diff --git a/docs/using-the-toolbox.rst b/docs/using-the-toolbox.rst index 09e5ca5c..02135053 100644 --- a/docs/using-the-toolbox.rst +++ b/docs/using-the-toolbox.rst @@ -1,4 +1,92 @@ Using the Toolbox ======================== -Soon \ No newline at end of file +|python_version_img| +|pypi_img| + +The objective of `querido-diario-toolbox`_ is to equip Querido Diário's (QD) +community with the tools necessary to conduct their own analyses and data +manipulations using data obtained through QD. Additionally, the library +will be integrated into the production applications used by Querido Diário, +meaning that anyone using the library will be able to locally reproduce the +same data processing steps performed by QD. + +The library provides many levels of abstractions to work with the data. +Ranging from simple text cleaning using strings to converting files from +various formats into plain text. + +Installing +---------- + +.. code-block:: python + + pip install querido-diario-toolbox + +Currently, `querido-diario-toolbox` is compatible with Python 3.8+. + +To perform the text extractions it's necessary to install `Tesseract OCR`_, as +well as the ``.jar`` files from `Apache Tika`_ (last tested version: 1.24.1) and +`Tabula`_ (last tested version: v1.0.4) accessible in order to pass their file +paths as arguments. + +Use case +--------------- + +More elaborate examples are available in the `examples`_ folder. You can view +them (and interact if you wish) using `Jupyter`_ notebooks. + +Removing unnecessary spaces in text +............................................ + +.. code-block:: python + + from querido_diario_toolbox.process.text_process import remove_breaks + + texto = "\n\n\nThis text has many white spaces\n\n \nunnecessary.\n" + + remove_breaks(texto) + 'This text has many white spaces unnecessary.' + +Finding valid `CNPJs`_ in text +..................................... + +.. code-block:: python + + from querido_diario_toolbox.process.edition_process import extract_and_validate_cnpj + + texto = "The companies with valid CNPJs 00.000.000/0001-91 and 00.360.305/0001-04 exist, but the one with CNPJ 12.123.123/1234.12 does not exist..." + + extract_and_validate_cnpj(texto) + ['00.000.000/0001-91', '00.360.305/0001-04'] + +Converting file from closed format to plain text and extracting metadata +............................................................................ + +.. code-block:: python + + from querido_diario_toolbox import Gazette + from querido_diario_toolbox.etl.text_extractor import create_text_extractor + + config = {"apache_tika_jar": "caminho/apache/tika/jar/tika-app-1.24.1.jar"} + extrator = create_text_extractor(config) + + diario = Gazette(filepath="caminho/diario/fechado/diario.pdf") + + extrator.extract_text(diario) + extrator.extract_metadata(diario) + extrator.load_content(diario) + +After the execution of ``extrator.load_content(diario)``, two files (a ``.txt`` +with pure text and a ``.json`` with metadata) will be created. + +.. |python_version_img| image:: https://img.shields.io/pypi/pyversions/querido-diario-toolbox + :target: https://pypi.org/project/querido-diario-toolbox/ +.. |pypi_img| image:: https://img.shields.io/pypi/v/querido-diario-toolbox + :target: https://pypi.org/project/querido-diario-toolbox/ +.. _querido-diario-toolbox: https://pypi.org/project/querido-diario-toolbox/ +.. _Tesseract OCR: https://tesseract-ocr.github.io/tessdoc/ +.. _Apache Tika: https://tika.apache.org/download.html +.. _examples: https://github.com/okfn-brasil/querido-diario-toolbox/tree/main/examples +.. _Tabula: https://github.com/tabulapdf/tabula-java/releases +.. _Jupyter: https://jupyter.org/ +.. _CNPJs: https://en.wikipedia.org/wiki/CNPJ diff --git a/docs/utilizando-a-toolbox.rst b/docs/utilizando-a-toolbox.rst index 901769b2..9ab27016 100644 --- a/docs/utilizando-a-toolbox.rst +++ b/docs/utilizando-a-toolbox.rst @@ -4,13 +4,16 @@ Utilizando a Toolbox do Querido Diário |python_version_img| |pypi_img| -.. *`Click here`_ to read this article in english.* - -O objetivo da `querido-diario-toolbox` é dar à comunidade do Querido Diário o ferramental para executar suas próprias análises e manipulações com os dados -que são obtidos pelo QD. Além disso, a biblioteca também será integrada nas aplicações utilizadas em produção pelo Querido Diário. Ou seja, quem utilizar a biblioteca poderá reproduzir localmente as mesmas etapas de +O objetivo da `querido-diario-toolbox`_ é dar à comunidade do Querido Diário o +ferramental para executar suas próprias análises e manipulações com os dados +que são obtidos pelo QD. Além disso, a biblioteca também será integrada nas +aplicações utilizadas em produção pelo Querido Diário. Ou seja, quem utilizar a +biblioteca poderá reproduzir localmente as mesmas etapas de processamento que o QD realiza. -A biblioteca dá diferentes níveis de abstrações para trabalhar com os dados. Desde uma simples limpeza de texto a partir de strings até conversão de arquivos de vários formatos para texto puro. +A biblioteca dá diferentes níveis de abstrações para trabalhar com os dados. +Desde uma simples limpeza de texto a partir de strings até conversão de arquivos +de vários formatos para texto puro. Instalação @@ -22,12 +25,16 @@ Instalação Atualmente, a `querido-diario-toolbox` é compatível com Python 3.8+. -Para executar extrações de texto é necessário ter o `Tesseract OCR`_ instalado. Assim como ter os `.jar` do `Apache Tika`_ (última versão testada: 1.24.1) e `Tabula`_ (última versão testada: v1.0.4) acessíveis para poder passar seus caminhos de arquivo como argumentos. +Para executar extrações de texto é necessário ter o `Tesseract OCR`_ instalado. +Assim como ter os ``.jar`` do `Apache Tika`_ (última versão testada: 1.24.1) e +`Tabula`_ (última versão testada: v1.0.4) acessíveis para poder passar seus +caminhos de arquivo como argumentos. Exemplos de uso --------------- -Exemplos mais elaborados estão disponíveis na pasta `./examples`_. Você pode visualizá-los (e interagir se desejar) utilizando notebooks `Jupyter`_. +Exemplos mais elaborados estão disponíveis na pasta `examples`_. Você pode +visualizá-los (e interagir se desejar) utilizando notebooks `Jupyter`_. Removendo espaços desnecessários em um texto ............................................ @@ -36,7 +43,7 @@ Removendo espaços desnecessários em um texto from querido_diario_toolbox.process.text_process import remove_breaks - texto = "\n\n\nEste texto tem vários espaços em branco\n\n \ndesnecessários.\n" + texto = "\n\n\nEste texto tem vários espaços em branco\n\n \ndesnecessários.\n" remove_breaks(texto) 'Este texto tem vários espaços em branco desnecessários.' @@ -70,17 +77,18 @@ Convertendo arquivo de formato fechado para texto puro e extraindo metadados extrator.extract_metadata(diario) extrator.load_content(diario) -Após a execução de `extrator.load_content(diario)`, dois arquivos (um `.txt` com o texto puro e um `.json` com os metadados) serão criados. +Após a execução de ``extrator.load_content(diario)``, dois arquivos (um ``.txt`` +com o texto puro e um ``.json`` com os metadados) serão criados. -.. _Click here: how-to-use-toolbox.rst .. |python_version_img| image:: https://img.shields.io/pypi/pyversions/querido-diario-toolbox :target: https://pypi.org/project/querido-diario-toolbox/ .. |pypi_img| image:: https://img.shields.io/pypi/v/querido-diario-toolbox :target: https://pypi.org/project/querido-diario-toolbox/ +.. _querido-diario-toolbox: https://pypi.org/project/querido-diario-toolbox/ .. _Tesseract OCR: https://tesseract-ocr.github.io/tessdoc/ .. _Apache Tika: https://tika.apache.org/download.html -.. _./examples: examples +.. _./examples: https://github.com/okfn-brasil/querido-diario-toolbox/tree/main/examples .. _Tabula: https://github.com/tabulapdf/tabula-java/releases .. _Jupyter: https://jupyter.org/