dataquantum-yaml-reader 0.3.1__py3-none-any.whl

dataquantum_yaml_reader/__init__.py

@@ -0,0 +1,7 @@
+"""YAML reader package."""
+
+from dataquantum_yaml_reader.reader_yaml import get_reader_yaml
+
+__all__ = ["get_reader_yaml"]
+
+__version__ = "0.3.1"

dataquantum_yaml_reader/reader_yaml.py

@@ -0,0 +1,54 @@
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def get_reader_yaml(config_path: Path) -> dict[str, Any]:
+    """
+    Loads all YAML configuration files present in a
+    specified directory.
+
+    Parameters
+    ----------
+    config_path : Path
+        Path to the directory containing the configuration files.
+
+    Returns
+    -------
+    Dict[str, Any]
+        A dictionary containing all the loaded configurations.
+        The key corresponds to the name of the YAML file, and the
+        value corresponds to the file's content converted into
+        a Python structure.
+    """
+
+    # Initialize the dictionary that will store all configurations
+    # loaded from the YAML files.
+    configs: dict[str, Any] = {}
+
+    try:
+        # Checks if the configuration directory exists.
+        if not config_path.exists():
+            raise FileNotFoundError(f"Configuration directory not found: {config_path}")
+
+        # Checks if the configuration path exists.
+        if not config_path.is_dir():
+            raise NotADirectoryError(
+                f"The specified path is not a directory: {config_path}"
+            )
+
+        # Iterates through all files with the .yaml extension
+        for file in config_path.glob("*.yaml"):
+            # Opens the YAML file in read mode, using
+            # UTF-8 encoding to ensure compatibility.
+            with open(file, "r", encoding="utf-8") as f:
+                # Loads the YAML content securely using
+                # yaml.safe_load, which prevents the execution of arbitrary code.
+                configs[file.stem] = yaml.safe_load(f)
+
+        # Returns the dictionary containing all loaded settings.
+        return configs
+
+    except yaml.YAMLError as error:
+        raise ValueError(f"YAML_ERROR: error processing YAML -> {error}") from error

dataquantum_yaml_reader-0.3.1.dist-info/METADATA

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: dataquantum-yaml-reader
+Version: 0.3.1
+Summary: A Python package for reading YAML configuration files.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: yaml,configuration,reader,dataquantum
+Author: jcarlossc
+Author-email: jcarlossc1977@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
+Description-Content-Type: text/markdown
+
+# DataQuantum YAML Reader
+
+[![Python](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Biblioteca Python para leitura de arquivos de configuração YAML, desenvolvida para simplificar o carregamento e a organização de configurações em projetos Python.
+
+O `DataQuantum YAML Reader` permite ler múltiplos arquivos `.yaml` de um diretório e reunir suas configurações em um dicionário Python, utilizando o nome de cada arquivo como chave.
+
+Desenvolvido pela **DataQuantum**, marca dedicada a soluções de análise de dados, ciência de dados e engenharia de dados.
+
+## Funcionalidades
+
+- Leitura de múltiplos arquivos `.yaml` de um diretório.
+- Carregamento seguro dos arquivos utilizando `yaml.safe_load`.
+- Organização das configurações em um dicionário Python.
+- Utilização do nome de cada arquivo como chave do dicionário.
+- Suporte a estruturas YAML aninhadas.
+- Integração com projetos Python e pipelines ETL.
+
+## Requisitos
+
+- Python 3.11 ou superior.
+- PyYAML 6.0.3 ou superior, dentro do intervalo de versões declarado pelo pacote.
+
+## Instalação
+
+### Com pip
+
+Instale a biblioteca diretamente do PyPI:
+
+```bash
+pip install dataquantum-yaml-reader
+```
+
+### Com Poetry
+
+Adicione a biblioteca como dependência do projeto:
+
+```bash
+poetry add dataquantum-yaml-reader
+```
+
+### Estrutura de diretórios
+
+Crie o diretório `config` na raiz do projeto para armazenar os arquivos de configuração com extensão `.yaml`.
+
+## Exemplo de utilização
+
+Considere a seguinte estrutura de diretórios:
+
+```text
+projeto/
+├── config/
+│   └── logging.yaml
+├── src/
+│   └── main.py
+└── pyproject.toml
+```
+
+O arquivo `logging.yaml` contém:
+
+```yaml
+logging_info:
+  level: "INFO"
+  format: "%(asctime)s - %(levelname)s - %(name)s - %(message)s"
+  encoding: "utf-8"
+
+logs:
+  file: "logs/app.log"
+```
+
+### Lendo os arquivos YAML
+
+Importe a função `get_reader_yaml` e informe o caminho do diretório que contém os arquivos de configuração.
+
+```python
+from pathlib import Path
+
+from dataquantum_yaml_reader import get_reader_yaml
+
+
+# Localiza a raiz do projeto, um nível acima de src/.
+project_root = Path(__file__).resolve().parent.parent
+
+# Define o caminho absoluto para o diretório de configurações.
+config_path = project_root / "config"
+
+configs = get_reader_yaml(config_path)
+
+print(configs)
+```
+### Como funciona?
+- ```__file__```: caminho do arquivo main.py.
+- ```.resolve()```: transforma o caminho em absoluto.
+- ```.parent```: retorna o diretório src/.
+- ```.parent.parent```: retorna a raiz do projeto.
+- ```/ "config"```: acrescenta o diretório config/ ao caminho.
+
+### Resultado esperado
+
+```python
+{
+    "logging": {
+        "logging_info": {
+            "level": "INFO",
+            "format": "%(asctime)s - %(levelname)s - %(name)s - %(message)s",
+            "encoding": "utf-8",
+        },
+        "logs": {"file": "logs/app.log"},
+    }
+}
+```
+
+O dicionário contém uma entrada para cada arquivo `.yaml` encontrado. A chave corresponde ao nome do arquivo sem a extensão, e o valor corresponde ao conteúdo carregado.
+
+## Utilizando as configurações
+
+Após carregar os arquivos, você pode acessar os valores por meio das chaves do dicionário.
+
+```python
+from pathlib import Path
+
+from dataquantum_yaml_reader import get_reader_yaml
+
+# Localiza a raiz do projeto, um nível acima de src/.
+project_root = Path(__file__).resolve().parent.parent
+
+# Define o caminho absoluto para o diretório de configurações.
+config_path = project_root / "config"
+
+configs = get_reader_yaml(config_path)
+
+logging_config = configs["logging"]
+
+level = logging_config["logging_info"]["level"]
+log_format = logging_config["logging_info"]["format"]
+encoding = logging_config["logging_info"]["encoding"]
+log_file = logging_config["logs"]["file"]
+
+print(level)
+print(log_format)
+print(encoding)
+print(log_file)
+```
+
+Saída:
+
+```text
+INFO
+%(asctime)s - %(levelname)s - %(name)s - %(message)s
+utf-8
+logs/app.log
+```
+
+## Quais erros podem ocorrer?
+
+| Exceção | Situação |
+|---|---|
+| `FileNotFoundError` | O caminho informado não existe. |
+| `NotADirectoryError` | O caminho existe, mas aponta para um arquivo, não para um diretório. |
+| `ValueError` | Um arquivo YAML contém sintaxe inválida. |
+| `OSError` | Ocorre um erro do sistema operacional ao acessar ou ler arquivos. |
+
+**Arquivos YAML vazios:** não geram erro com `yaml.safe_load()`.
+O valor correspondente no dicionário será `None`.
+
+## Aplicações
+
+A biblioteca pode ser utilizada em diferentes contextos:
+
+- **Análise de dados:** centralização de configurações de projetos analíticos.
+- **Ciência de dados:** carregamento de parâmetros e configurações de experimentos.
+- **Engenharia de dados:** gerenciamento de configurações de pipelines ETL.
+- **Automação:** leitura de configurações utilizadas em scripts Python.
+- **Integração de sistemas:** organização de parâmetros de conexão e configurações de aplicações.
+
+## Desenvolvimento
+
+Este projeto utiliza Poetry para gerenciamento de dependências e do ambiente de desenvolvimento.
+
+Clone o repositório:
+
+```bash
+git clone https://github.com/jcarlossc/dataquantum-yaml-reader.git
+
+cd dataquantum-yaml-reader
+```
+
+Instale as dependências:
+
+```bash
+poetry install
+```
+
+Execute os testes:
+
+```bash
+poetry run task pytest
+```
+
+Execute os testes com relatório de cobertura:
+
+```bash
+poetry run task covcmd
+```
+
+Execute as verificações de qualidade:
+
+```bash
+poetry run task check
+poetry run task lint
+poetry run task mypy
+```
+
+Execute a validação completa para o release:
+
+```bash
+poetry run task release-check
+```
+
+## Testes e qualidade
+
+O projeto utiliza ferramentas para garantir a qualidade, a manutenção e a confiabilidade do código:
+
+- **pytest:** execução dos testes automatizados.
+- **pytest-cov:** medição da cobertura dos testes.
+- **Ruff:** análise estática e formatação do código.
+- **mypy:** verificação estática de tipos.
+- **pre-commit:** execução de verificações automatizadas antes dos commits.
+- **GitHub Actions:** integração contínua e automação de tarefas.
+- **Release Please:** gerenciamento automatizado de releases e changelog.
+
+## Versionamento
+
+O projeto segue o Versionamento Semântico (*Semantic Versioning*), utilizando o formato:
+
+`MAJOR.MINOR.PATCH`
+
+- **MAJOR:** alterações incompatíveis com versões anteriores.
+- **MINOR:** novas funcionalidades compatíveis com versões anteriores.
+- **PATCH:** correções compatíveis com a versão existente.
+
+Consulte o arquivo `CHANGELOG.md` para acompanhar o histórico de alterações.
+
+## Licença
+
+Este projeto está licenciado sob a licença MIT. Consulte o arquivo `LICENSE` para obter mais informações.
+
+## Autor e contato
+
+**DataQuantum**
+
+- GitHub: [jcarlossc](https://github.com/jcarlossc)
+- Repositório: [dataquantum-yaml-reader](https://github.com/jcarlossc/dataquantum-yaml-reader)
+- E-mail: jcarlossc1977@gmail.com
+

dataquantum_yaml_reader-0.3.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+dataquantum_yaml_reader/__init__.py,sha256=JmFy7XcE9yTHMzaUxMgWSmiK85MnMwIWbXOnJJcYRZs,146
+dataquantum_yaml_reader/reader_yaml.py,sha256=g_RkfIbyNKTRVfMbQAMHW6WLwaV_QlD-mRCPjZKmkyo,1818
+dataquantum_yaml_reader-0.3.1.dist-info/METADATA,sha256=Gpzg0o3M2uYl1J1BjbuZ4PsqgvxP78FDz9zfE-GUPsQ,7633
+dataquantum_yaml_reader-0.3.1.dist-info/WHEEL,sha256=L-WvLdSBvJWHXv5zrQxDvNRnIgoBzLUpcbuiw19KCuQ,88
+dataquantum_yaml_reader-0.3.1.dist-info/licenses/LICENSE,sha256=XtVXtSY11uUnSjQnuVdYp3dHuCr3v1EWzvR9iBNp0qo,1072
+dataquantum_yaml_reader-0.3.1.dist-info/RECORD,,

dataquantum_yaml_reader-0.3.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.5.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dataquantum_yaml_reader-0.3.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos da Costa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.