convunit 1.0.0

A flexible unit conversion tool with support for custom groups, types, aliases, and date/time conversions.

ConvUnit

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)

python -m src.convunit

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

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
• Features
• How to Run ConvUnit
• Installation
• Quick Start
• Usage
  • Interactive Mode
  • Command Line (CLI)
  • API
• Date & Time Conversion
• Project Structure
• Design Choices
• Contributing
• 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:

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

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

from convunit import Converter
converter = Converter()

---

Quick Start

For Normal Users

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

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

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:

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:

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

3. API Mode (Python Library)

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.

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 for the full list of supported formats and detailed examples.

Examples

Interactive Mode:

python -m src.convunit
convert
time
5 years 10 months 10 days 8 hours seconds

CLI Mode

python -m src.convunit convert time 5 years 10 months 10 days hours

API Mode

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

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 file for details.