Metadata-Version: 2.4
Name: boring-utils
Version: 0.2.0
Summary: A Python library to handle the tedious parts of Data Science and AI—so you don't have to.
Author-email: Estevão Augusto da Fonseca Santos <estevaoaugusto2005@gmail.com>
Project-URL: Homepage, https://github.com/EstevaoAugusto/boring-utils
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=3.0.2
Requires-Dist: requests>=2.33.1
Dynamic: license-file

# boring-utils

For every project involving data, there's a lot of tedious repetitive work that goes into it, which results in the creation of reusable scripts that greatly automate the process for you. What if instead of copy and pasting these files into new projects, there was one library that simplified things, and get solutions done through one line of code? 

Introducing **boring-utils** — a Python library focused on simplifying tedious, boring tasks involving data management, such as downloading files, managing datasets, storing and retrieving data in various formats, and much more.

## 📦 Installation

### Using `pip`

To install boring-utils using pip, run the following command:

```bash
pip install boring-utils
```

### Using `uv` (Recommended)

If you're using [uv](https://docs.astral.sh/uv/), the modern Python package installer, you can install boring-utils with:

```bash
uv pip install boring-utils
```

Or if you're using uv as a project manager:

```bash
uv add boring-utils
```

### Requirements

- **Python >= 3.13**
- **Dependencies:**
  - `pandas >= 3.0.2` — Data manipulation and analysis
  - `requests >= 2.33.1` — HTTP requests for downloading files

## ✨ Main Features

### 1. **Data Collection** 🔽
Easily download and manage files from the web:
- **Download single files** with progress tracking
- **Download multiple files** in batch operations
- **Automatic filename detection** from HTTP headers or URLs
- **Unzip archives** automatically

**Example:**
```python
from boring_utils.data.data_collecting import download_file, download_several_files
from pathlib import Path

# Download a single file
download_file("https://example.com/data.csv", Path("./data"))

# Download multiple files
urls = [
    "https://example.com/file1.zip",
    "https://example.com/file2.csv"
]
download_several_files(urls)
```

### 2. **Data Storage** 💾
Save and load data in multiple formats with a unified interface:
- **JSON** — Store structured data with customizable indentation
- **Pickle** — Python object serialization
- **CSV** — Tabular data format
- **Parquet** — Efficient columnar storage
- **YAML & XML** — Structured data formats

**Example:**
```python
from boring_utils.data.data_storage import save_json, save_csv, load_json
from pathlib import Path

# Save data as JSON
data = {"name": "John", "age": 30}
save_json(data, "output.json")

# Load data from JSON
loaded = load_json("output.json")
```

### 3. **Helper Utilities** 🔧
- **Path Management** — Preconfigured directories for organized data storage
- **Constants** — Predefined file extensions and default HTTP headers
- **Directory Utilities** — Automatic directory creation and validation

**Example:**
```python
from boring_utils.helpers._paths import DATA_DIRECTORY_PATH
from boring_utils.helpers.constants import DATA_EXTENSIONS

print(f"Data directory: {DATA_DIRECTORY_PATH}")
print(f"Supported formats: {DATA_EXTENSIONS}")
```

### 4. **Network Utilities** 🌐
- **Default headers** for HTTP requests
- **User-Agent configuration** — Avoid blocking by providing proper headers
- **Extensible networking** features for data collection

## 🚀 Quick Start

```python
import pandas as pd
from boring_utils.data import data_collecting, data_storage
from pathlib import Path

# Download a CSV file
data_collecting.download_file(
    "https://example.com/dataset.csv",
    dest_path=Path("./data/my_dataset.csv")
)

# Load and process with pandas
df = pd.read_csv("./data/my_dataset.csv")

# Save processed data
data_storage.save_json(df.head().to_dict(), "sample.json")
```

## 📚 Documentation

For detailed documentation on each module, please refer to the docstrings in the source code or check the [GitHub repository](https://github.com/EstevaoAugusto/boring-utils).

## 🤝 Contributing

We welcome contributions! Please read our [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to contribute to this project.

## 📝 License

This project is licensed under the terms specified in the [LICENSE](./LICENSE) file.

## PyPi Page

This project is also available in the [PyPI](https://pypi.org/project/boring-utils/) page.
