globaldatafinance 0.1.0__tar.gz

globaldatafinance-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Support. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Jordan Estralioto
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

globaldatafinance-0.1.0/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: globaldatafinance
+Version: 0.1.0
+Summary: Library for extracting, normalizing and processing global financial and economic data — including market data from exchanges worldwide, regulatory filings, company fundamentals and historical quotes; optimized for high-performance storage and analysis (e.g., Parquet).
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: finance,financial-data,economic-data,market-data,global-markets,exchanges,fundamentals,historical-quotes,macroeconomics,parquet,b3,cvm
+Author: Jordan Estralioto
+Author-email: estraliotojordan@gmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: httpx[http2] (>=0.28.1,<0.29.0)
+Requires-Dist: pandas (>=2.3.3,<3.0.0)
+Requires-Dist: polars (>=1.0.0,<2.0.0)
+Requires-Dist: psutil (>=5.9.0,<7.0.0)
+Requires-Dist: pyarrow (>=22.0.0,<23.0.0)
+Requires-Dist: pydantic-settings (>=2.11.0,<3.0.0)
+Project-URL: Bug Tracker, https://github.com/jor0105/Global-Data-Finance/issues
+Project-URL: Documentation, https://github.com/jor0105/Global-Data-Finance
+Project-URL: Homepage, https://github.com/jor0105/Global-Data-Finance
+Project-URL: Repository, https://github.com/jor0105/Global-Data-Finance
+Description-Content-Type: text/markdown
+
+# 📊 Global-Data-Finance
+
+<div align="center">
+
+**Biblioteca Python profissional para extração e processamento de dados financeiros globais com arquitetura limpa e alto desempenho.**
+
+[![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI version](https://img.shields.io/pypi/v/globaldatafinance.svg)](https://pypi.org/project/globaldatafinance/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/jor0105/Global-Data-Finance/blob/develop/LICENSE)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue)](http://mypy-lang.org/)
+
+[Documentação Oficial](https://jor0105.github.io/Global-Data-Finance/) • [Instalação](#-instalação) • [Quick Start](#-quick-start) • [API Reference](#-api-reference) • [Contribuir](#-contribuindo)
+
+</div>
+
+---
+
+## 🎯 Sobre
+
+**Global-Data-Finance** é uma solução robusta e de alto desempenho para engenharia de dados financeiros. Projetada para desenvolvedores, cientistas de dados e analistas quantitativos, a biblioteca abstrai a complexidade de extrair e normalizar dados de fontes regulatórias (CVM) e de mercado (B3).
+
+Construída sobre os princípios de **Clean Architecture** e **SOLID**, a biblioteca garante não apenas performance excepcional, mas também um código manutenível, testável e extensível.
+
+### 🌟 Por que escolher Global-Data-Finance?
+
+- **🚀 Performance Extrema**: Utiliza `asyncio` e processamento paralelo para downloads até **10x mais rápidos** que métodos tradicionais.
+- **🛡️ Robustez**: Sistema inteligente de retries, monitoramento de recursos e tratamento de erros granular.
+- **💾 Otimização de Dados**: Extração nativa para **Parquet**, garantindo eficiência de armazenamento e leitura rápida para Pandas/Polars.
+- **🧩 Arquitetura Modular**: Design desacoplado que permite fácil substituição de componentes (adapters) e extensão de funcionalidades.
+- **✨ Developer Experience**: Type hints completos, logging detalhado e API intuitiva.
+
+---
+
+## ✨ Funcionalidades
+
+### 📈 Fontes de Dados Suportadas
+
+| Fonte   | Tipo de Dado            | Detalhes                                  | Status      |
+| :------ | :---------------------- | :---------------------------------------- | :---------- |
+| **CVM** | Documentos Regulatórios | DFP, ITR, FRE, FCA, CGVN, VLMO, IPE       | ✅ Produção |
+| **B3**  | Cotações Históricas     | Ações, ETFs, BDRs, Opções, Termo, Futuros | ✅ Produção |
+
+### ⚙️ Destaques Técnicos
+
+- **Download Manager Assimétrico**:
+  - Gerenciamento automático de concorrência.
+  - Backoff exponencial para falhas de rede.
+  - Validação de integridade de arquivos (ZIP/MD5).
+- **Processamento de Cotações (B3)**:
+  - Parser otimizado para arquivos posicionais legados.
+  - Modos de execução: `fast` (in-memory) e `slow` (low-memory).
+  - Filtragem avançada por tipo de ativo (Ações, Opções, etc.).
+
+---
+
+## 🚀 Instalação
+
+Requer **Python 3.12+**.
+
+### Via Pip (Recomendado)
+
+```bash
+pip install globaldatafinance
+```
+
+### Via Poetry
+
+```bash
+poetry add globaldatafinance
+```
+
+---
+
+## 💡 Quick Start
+
+### 1. Dados Fundamentais (CVM)
+
+Baixe demonstrações financeiras (DFP, ITR) e formulários de referência de forma massiva e resiliente.
+
+```python
+from globaldatafinance import FundamentalStocksDataCVM
+import logging
+
+# (Opcional) Configurar logging para ver o progresso detalhado
+logging.basicConfig(level=logging.INFO)
+
+# Inicializar cliente
+cvm = FundamentalStocksDataCVM()
+
+# Baixar e extrair automaticamente para Parquet
+cvm.download(
+    destination_path="./dados_cvm",
+    list_docs=["DFP", "ITR"],    # Tipos de documentos
+    initial_year=2023,           # Ano inicial
+    last_year=2024,              # Ano final
+    automatic_extractor=True     # Converte ZIP -> Parquet
+)
+```
+
+### 2. Cotações Históricas (B3)
+
+Processe a série histórica da B3, transformando arquivos de texto complexos em DataFrames prontos para análise.
+
+```python
+from globaldatafinance import HistoricalQuotesB3
+
+# Inicializar cliente
+b3 = HistoricalQuotesB3()
+
+# Extrair cotações de Ações e ETFs
+result = b3.extract(
+    path_of_docs="./dados_brutos_b3",  # Onde estão os ZIPs da B3 (COTAHIST_A2023.ZIP)
+    destination_path="./dados_processados",
+    assets_list=["ações", "etf"],
+    initial_year=2023,
+    processing_mode="fast"  # Modo otimizado
+)
+
+print(f"Processamento concluído! Registros extraídos: {result['total_records']:,}")
+print(f"Arquivo salvo em: {result['output_file']}")
+```
+
+### 3. Analisando os Dados
+
+Os dados são salvos em formato **Parquet**, ideal para análise com Pandas ou Polars.
+
+```python
+import pandas as pd
+
+# Ler o arquivo gerado
+df = pd.read_parquet("./dados_processados/cotahist_extracted.parquet")
+
+# Analisar
+print(df.head())
+print(df.groupby("cod_negociacao")["preco_fechamento"].mean())
+```
+
+---
+
+## 🏗️ Arquitetura
+
+A arquitetura do projeto é um diferencial chave, separando claramente responsabilidades para garantir longevidade e qualidade do software.
+
+```mermaid
+graph TD
+    User[Usuário / Script] --> Presentation
+
+    subgraph "Global-Data-Finance"
+        Presentation[Presentation Layer<br>FundamentalStocksDataCVM / HistoricalQuotesB3]
+
+        Presentation --> Application
+
+        subgraph "Core Logic"
+            Application[Application Layer<br>Use Cases & Interfaces]
+            Domain[Domain Layer<br>Entities & Business Rules]
+            Application --> Domain
+        end
+
+        Application --> Infrastructure
+
+        subgraph "Infrastructure"
+            Infrastructure[Infrastructure Layer<br>Adapters, Parsers, IO]
+        end
+    end
+
+    Infrastructure --> External[Web / File System]
+```
+
+### Estrutura de Diretórios
+
+```text
+src/
+└── globaldatafinance/
+    ├── brazil/
+    │   ├── cvm/
+    │   │   └── fundamental_stocks_data/  # Módulo CVM
+    │   └── b3/
+    │       └── historical_quotes/        # Módulo B3
+    ├── core/                             # Logging, Config, Utils
+    └── macro_infra/                      # Adapters Genéricos (HTTP, FileIO)
+```
+
+---
+
+## 📊 API Reference
+
+### `FundamentalStocksDataCVM`
+
+Gerenciador de downloads de documentos da CVM.
+
+| Método                    | Assinatura                                                                                                                                 | Descrição                                                     |
+| :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |
+| **`download`**            | `(destination_path: str, list_docs: list[str]=None, initial_year: int=None, last_year: int=None, automatic_extractor: bool=False) -> None` | Realiza o download e opcionalmente a extração dos documentos. |
+| **`get_available_docs`**  | `() -> dict`                                                                                                                               | Retorna lista de documentos disponíveis e suas descrições.    |
+| **`get_available_years`** | `() -> dict`                                                                                                                               | Retorna o intervalo de anos disponíveis para download.        |
+
+### `HistoricalQuotesB3`
+
+Extrator de cotações históricas da B3.
+
+| Método                     | Assinatura                                                                                                                                                                                             | Descrição                                                          |
+| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------- |
+| **`extract`**              | `(path_of_docs: str, assets_list: list[str], initial_year: int=None, last_year: int=None, destination_path: str=None, output_filename: str="cotahist_extracted", processing_mode: str="fast") -> dict` | Processa arquivos ZIP da B3 e gera um arquivo Parquet consolidado. |
+| **`get_available_assets`** | `() -> list[str]`                                                                                                                                                                                      | Retorna tipos de ativos suportados (ex: 'ações', 'opções').        |
+| **`get_available_years`**  | `() -> dict`                                                                                                                                                                                           | Retorna o intervalo de anos disponíveis para os dados históricos.  |
+
+---
+
+## 🤝 Contribuindo
+
+Contribuições são muito bem-vindas! Se você deseja adicionar novas fontes de dados, melhorar a performance ou corrigir bugs:
+
+1.  **Fork** o projeto.
+2.  Crie uma branch para sua feature (`git checkout -b feature/nova-feature`).
+3.  Implemente suas mudanças.
+4.  Execute os testes e linters:
+    ```bash
+    poetry run pre-commit run --all-files
+    poetry run pytest
+    ```
+5.  Abra um **Pull Request**.
+
+Consulte o [Guia de Contribuição](https://jor0105.github.io/Global-Data-Finance/dev-guide/contributing/) para mais detalhes.
+
+---
+
+## 📄 Licença
+
+Este projeto é distribuído sob a licença **Apache 2.0**. Consulte o arquivo [LICENSE](LICENSE) para mais informações.
+
+---
+
+## 📞 Suporte e Contato
+
+- **Autor**: Jordan Estralioto
+- **GitHub**: [@jor0105](https://github.com/jor0105)
+- **Email**: estraliotojordan@gmail.com
+- **Issues**: [Reportar Bug](https://github.com/jor0105/Global-Data-Finance/issues)
+
+---
+
+<div align="center">
+    <sub>Copyright © 2025 Jordan Estralioto • Licensed under Apache 2.0</sub>
+</div>
+