convunit 1.1.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

---

Table of Contents

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

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

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

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

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:

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:

python -m convunit --help
python -m 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). 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.

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

Examples

Interactive Mode:

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

CLI Mode

python -m 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)

---

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.