Metadata-Version: 2.4
Name: convunit
Version: 1.0.0
Summary: A flexible unit conversion tool with support for custom groups, types, aliases, and date/time conversions.
Author-email: "Alexandre D. Ferrari" <element_trading_47@icloud.com>
License: MIT
Project-URL: Homepage, https://github.com/XanD0K/ConvUnit
Project-URL: Repository, https://github.com/XanD0K/ConvUnit
Project-URL: Issues, https://github.com/XanD0K/ConvUnit/issues
Keywords: unit-conversion,converter,convunit,cli,api,date-time
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: platformdirs>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# ConvUnit
[![Python](https://img.shields.io/badge/Python-3.9%2B-blue?logo=python)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

## Description
A flexible unit conversion tool written in Python that supports multiple categories (length, mass, temperature, time, volume, area, and speed), with support for custom units, aliases, base unit changes, and conversion history.

Three ways to use it:
- **Interactive mode** (guided menu)
- **Command Line (CLI)**
- **Python API**

---


## Features
- **Convert** — Convert units between different categories, including complex date and time conversions with multiple input formats
- **History** — View conversion history from the last 3 days
- **Groups** — List all available unit groups
- **Types** — View all unit types (and their aliases) of a specific group (or all groups)
- **Base** — View the base unit of a group (or all groups)
- **Manage Groups** — Add or remove custom unit groups
- **Manage Types** — Add or remove unit types within a group
- **Aliases** — Create or remove aliases for unit types
- **Change Base** — Change the base unit of any group
- **Reset Data** — Reset all custom data (groups, types, aliases, etc.) back to original state

---


## How to Run ConvUnit
ConvUnit can be executed in different ways depending on whether you have installed the package or not.

### Without installing (development)

```bash
python -m src.convunit
```

### After installing the package (recommended)
```bash
# Install in editable mode
pip install -e .

# Interactive mode
python -m convunit

# CLI mode
python -m convunit convert length meters feet 10

# Alternative: use the command directly
convunit convert length meters feet 10
```
> **Note:** All examples in this document use `python -m src.convunit` (development mode). If you have installed the package, replace it with `python -m convunit` or just `convunit`.

---


## Table of Contents
- [Description](#description)
- [Features](#features)
- [How to Run ConvUnit](#how-to-run-convunit)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage](#usage)
  - [Interactive Mode](#1-interactive-mode)
  - [Command Line (CLI)](#2-cli-mode)
  - [API](#3-api-mode-python-library)
- [Date & Time Conversion](#date--time-conversion)
- [Project Structure](#project-structure)
- [Design Choices](#design-choices)
- [Contributing](#contributing)
- [License](#license)

---


## Installation
ConvUnit is built using only Python's standard libraries, so it has **no external dependencies**.

Interactive and CLI approaches require you to clone the repository:

```bash
git clone https://github.com/XanD0K/ConvUnit.git
cd convunit
```

For API approach, you can import and use it directly in your Python scripts:

```bash
from convunit import Converter
converter = Converter()
```

---


## Quick Start

### For Normal Users
```bash
pip install convunit

# Interactive mode
python -m convunit

# CLI mode
python -m convunit convert length meters feet 10

# Alternative: use the command directly
convunit convert length meters feet 10
```

### For Developers
```bash
# Clone the repository
git clone https://github.com/XanD0K/ConvUnit.git
cd convunit

# --- Without installing the package ---
# Interactive mode
python -m src.convunit

# CLI mode
python -m src.convunit convert length meters feet 10

# --- After installing the package (recommended) ---
# Install in editable mode
pip install -e .

# Interactive mode
python -m convunit

# CLI mode
python -m convunit convert length meters feet 10

# Alternative: use the command directly
convunit convert length meters feet 10
```

---


## Usage
ConvUnit supports three ways of use:

### 1. **Interactive Mode**
Run the following command:
```bash
python -m src.convunit
```

Just enter the program with the command above and follow the on-screen instructions.  
Type `quit` (`q`) or `exit` (`e`) to exit.

### 2. **CLI Mode**
You can run commands directly from the terminal:

```bash
python -m src.convunit groups
python -m src.convunit convert length meters feet 10
python -m src.convunit history --limit 20
python -m src.convunit types length --all
```

Most commands support the `--help` flag to see available options and flags:

```bash
python -m src.convunit --help
python -m src.convunit history --help
```

### 3. **API Mode (Python Library)**
```bash
from convunit import Converter

converter = Converter()

# Examples
print(converter.groups())
print(converter.convert("length", "meters", "feet", 10))
print(converter.history(limit=10))
```

> **Note:** Do not run `python src/convunit/main.py` directly. It will cause import errors due to relative imports. Always use the `-m` flag as shown above.  
> **Note:** For complete usage instructions, detailed command references and all Date & Time formats, see **[USAGE.md](USAGE.md)**.


## Date & Time Conversion
ConvUnit has powerful support for date and time conversions with flexible input formats, including differences between dates, months, and times, plus summing multiple units. The time parser also accepts non-standard values (e.g. `50h:350m:780s`).

See **[USAGE.md](USAGE.md)** for the full list of supported formats and detailed examples.

### Examples

**Interactive Mode:**
  ```bash
  python -m src.convunit
  convert
  time
  5 years 10 months 10 days 8 hours seconds
  ```

**CLI Mode**
  ```bash
  python -m src.convunit convert time 5 years 10 months 10 days hours
  ```

**API Mode**
  ```bash
  result = converter.convert("time", time_input="5 years 10 months 10 days 8 hours seconds")
  print(result)
  ```

> **Note:** Date difference calculations use Python's `datetime` module for accuracy (including leap years). Single date conversions use approximate year (365.2425 days) and month (30.436875 days) values for simplicity.

---


## Project Structure

```plaintext
convunit/
├── src/
│   └── convunit/            # Main package
│       ├── data/                  # JSON data files
│       │   ├── base_units.json
│       │   ├── conversion_log.json
│       │   ├── month_aliases.json
│       │   ├── month_days.json
│       │   ├── original_units.json
│       │   ├── units.json
│       │   └── unit_aliases.json
|       |
│       ├── __init__.py
│       ├── __main__.py
│       ├── main.py
│       ├── api.py                 # Public API interface (Converter class)
│       ├── cli.py                 # Command-line interface
│       ├── interactive.py         # Interactive mode
│       ├── aliases.py
│       ├── change_base.py
│       ├── convert.py
│       ├── convert_time.py
│       ├── data_manager.py        # JSON load/save logic
│       ├── data_models.py         # Data classes and validation
│       ├── display.py
│       ├── groups.py
│       ├── manage_types.py
│       ├── time_utils.py
│       ├── utils.py
│       └── errors.py              # Custom exceptions
│
├── tests/                         # Unit tests
├── CHANGELOG.md
├── DEVLOG.md
├── README.md
├── TODO.md
├── USAGE.md
└── requirements.txt
```

---


## Design Choices

- **Modular Architecture**: The project is divided into multiple focused modules instead of a single large file. This greatly improves readability, maintainability, and separation of concerns.

- **Data-Driven Approach**: All unit definitions, aliases, and base units are stored in JSON files. This allows easy extension and modification without changing the source code.

- **Custom Exception Hierarchy**: A well-defined exception system (`AppError` and its subclasses) was implemented to provide clear and meaningful error messages.

- **Three Access Modes**: The program supports Interactive, CLI, and API modes simultaneously, giving users flexibility depending on their needs.

- **Specialized Time Handling**: Dedicated modules (`time_utils.py` and `convert_time.py`) were created to properly manage the complexity of dates, months, leap years, and multiple input formats, keeping the main conversion logic clean.

- **API-First Mindset**: Even though the project started as a simple tool, the code was designed from the beginning to also work as a reusable Python library.

---


## Contributing
Contributions are welcome! If you want to contribute to ConvUnit, please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Test your changes thoroughly
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

Feel free to open an Issue for bug reports, feature requests, or questions.

---


## License

This project is licensed under the MIT License.  
See the [LICENSE](LICENSE) file for details.
