Metadata-Version: 2.4
Name: getenmagen
Version: 0.2.4
Summary: A library to quickly get or download images from the internet.
Author-email: Pedro Antonio Rodrigues <pedro.a.rodrigues7@gmail.com>
Keywords: bing,bing-image,bing-image-downloader,crawler,downloader,icrawler,image,pillow
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: icrawler>=0.6.0
Requires-Dist: pillow>=10.0.0
Description-Content-Type: text/markdown

# GETENMAGEN — Advanced Image Downloader & Viewer

An efficient, flexible, and robust open-source library designed to automate image downloading using Bing scraping capabilities with full configuration control.

## 📌 Introduction

Hello! Thank you for using **getenmagen**. This library was developed to provide an intuitive and powerful way to build image datasets or feed visual interfaces directly from the terminal.

> ⚠️ **Author Responsibility:** This library was created for automation and educational purposes. The author is not responsible for any malicious use or scraping violations.

---

## 🛠️ Documentation & Architecture

The library is built around an Object-Oriented design, featuring two main classes: `Downloader` (which handles execution) and `Defaults` (which handles global configuration states).

### 1. Initialization & Custom Directory
By default, the library saves downloaded assets in your module's local directory. You can instantiate the downloader and define a custom root storage folder:

```python
from getenmagen.core import Downloader

# Instantiates the downloader with a custom storage path
downloader = Downloader(default_save_dir="my_custom_folder")
```
### 2. Executing Downloads (The download Method)
The core execution method is **.download().** It accepts four parameters:

- query (str): The search term or keyword for the images (Required).
- save_dir (str, optional): Overrides the instance default storage folder for this specific execution.
- qt (int, optional): Number of images to fetch. Bound between 1 and 16.
- cooldown (float, optional): Seconds to pause between image display popups.

Example Usage:

```python
downloader.download(query="cyberpunk triangle", qt=5, cooldown=1.5)
```

### 3. Runtime Mutability & Global Configurations
The Defaults class allows you to dynamically mutate configuration states globally without modifying your core execution scripts.

Example Usage:

```python
from getenmagen.defaults import Defaults
from getenmagen.core import Downloader

# Initialize global configuration
config = Defaults()
config.set_default("min_qt", 8) # Mutates the state dynamically

# Pass the mutability object to the downloader
downloader = Downloader(defaults_obj=config)
```

## 🚨 Error Handling
getenmagen comes equipped with explicit, strictly typed custom exceptions to help you build safer scripts:

DownloadImageError: Raised when network connections fail or the search query yields 0 results.

ShowImageError: Raised when the Operating System image viewer cannot be initialized or fails to open.

InvalidImageError: Raised if corrupted or broken file formats are intercepted during execution.

📄 License & Contribution
Distributed under the MIT License. Feel free to open Issues or submit Pull Requests on our official page!

Official Project Page: https://pypi.org/project/getenmagen/

__Thank you for using getenmagen! Happy coding ;)__