Metadata-Version: 2.4
Name: convunit
Version: 1.1.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

---


## Table of Contents
- [Description](#description)
- [Features](#features)
- [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 has one runtime dependency: `platformdirs>=4.0` (used to locate the user configuration directory in a cross-platform way). All other code uses only Python's standard library.

### Normal Installation (recommended)

```bash
pip install convunit
```

After installation, all modes work out of the box:

- **Interactive mode:** `python -m convunit`
- **CLI mode:** `convunit convert length meters feet 10`
- **Python API:** `from convunit import Converter`

> **Note for developers:** If you cloned the repository but prefer not to install the package with `pip install -e .`, you can still run it with `python -m src.convunit`.

---


## Quick Start

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

# Interactive mode
python -m convunit

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

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

# API mode
from convunit import Converter
converter = Converter()
```
> **Note:** To launch interactive mode after installation, use `python -m convunit`. Running just `convunit` (without any subcommand) will show the help message instead of starting interactive mode.

### For Developers
If you want to **modify the source code**, add new features, fix bugs, or contribute to the project, you need to clone the repository and install it in **editable mode** (recommended):

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

# Install in editable mode (recommended)
pip install -e .
```

Then you can use the project normally as shown above.

---


## Usage
ConvUnit supports three ways of use:

### 1. **Interactive Mode**
Run the following command:
```bash
python -m 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 convunit groups
python -m convunit convert length meters feet 10
python -m convunit history --limit 20
python -m convunit types length --all
```

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

```bash
python -m convunit --help
python -m 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). Use `python -m src.convunit` or install the package instead.
> **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.

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

### Examples

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

**CLI Mode**
  ```bash
  python -m 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)
  ```

---


## 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.
