Metadata-Version: 2.1
Name: filesize-cli
Version: 1.0.2
Summary: A command-line tool to display the size of a file in various units (B, KB, MB, GB, TB).
Home-page: https://gitlab.com/thaikolja/filesize-cli
Download-URL: https://gitlab.com/thaikolja/filesize-cli/-/archive/main/filesize-cli-main.zip
Author: Kolja Nolte
Author-email: kolja.nolte@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: exceptiongroup==1.2.2
Requires-Dist: iniconfig==2.0.0
Requires-Dist: packaging==24.1
Requires-Dist: pluggy==1.5.0
Requires-Dist: pytest==8.3.3
Requires-Dist: setuptools==75.2.0
Requires-Dist: tomli==2.0.2

# filesize CLI

![PyPI - Version](https://img.shields.io/pypi/v/filesize-cli) ![GitLab Release](https://img.shields.io/gitlab/v/release/thaikolja%2Ffilesize-cli) ![PyPI - Downloads](https://img.shields.io/pypi/dm/filesize-clo) ![PyPI - License](https://img.shields.io/pypi/l/filesize-cli) ![GitLab Last Commit](https://img.shields.io/gitlab/last-commit/thaikolja%2Ffilesize-cli) ![GitLab Stars](https://img.shields.io/gitlab/stars/thaikolja%2Ffilesize-cli?style=flat&color=yellow)

**filesize CLI** is a simple yet useful command-line tool written in Python. By using the `filesize` command, you can see the size of a file right in your CLI (e.g., `12.4 MB`). Use the `--unit` flag to show file size in various units (KB, MB, GB, etc.). **filesize CLI** is a cross-platform CLI tool: whether you're managing files on Windows, macOS, or Linux, `filesize` provides a straightforward way to check file sizes directly from your terminal—nothing more, nothing less. Please read this `README.md` to learn how to install, use, and adjust this handy CLI tool.

## 📖 Table of Contents

- [✨ Features](#-features)
- [🛠️ Installation](#️-installation)
  - [Using `pip` (Recommended)](#using-pip-recommended)
  - [From Source](#from-source)
- [🚀 Usage](#-usage)
  - [Options](#options)
  - [Examples](#examples)
- [🧪 Testing](#-testing)
- [🤝 Contributing](#-contributing)
- [📜 License](#license)
- [📅 Changelog](#changelog)
- [📞 Support](#support)

## ✨ Features

- **Multi-Unit Support:** Display file sizes in Bytes (B), Kilobytes (KB), Megabytes (MB), Gigabytes (GB), or Terabytes (TB).
- **Customizable Conversion Rate:** Specify a custom conversion rate (default is 1000).
- **Pretty Print Option:** Toggle between plain output and formatted output with unit labels.
- **Cross-Platform Compatibility:** Works seamlessly on Windows, macOS, and Linux.
- **Easy Installation:** Install globally using `pip` for universal access.

## 🛠️ Installation

### Using `pip` (Recommended)

Installing **filesize-cli** via `pip`, [Python's official package manager](https://www.w3schools.com/python/python_pip.asp), is the simplest method to get `filesize-cli` up and running.

1. #### Ensure Python 3 and pip are Installed

   In your command line, run `python --version` and `pip --version`. If you see a version number, you're good to go! Otherwise, you must install it manually:

   - **Windows:**
     
     - Download and install Python from the [official website](https://www.python.org/downloads/windows/).
     - Ensure that Python is [added](https://learn.microsoft.com/en-us/previous-versions/office/developer/sharepoint-2010/ee537574(v=office.14)) to your system's `PATH` during installation.
   - **macOS:**
     - Python 3 is pre-installed on newer versions. If not, install it via [Homebrew](https://brew.sh/):
       ```bash
       brew install python

   - **Linux:**
     - Python 3 can be installed via your [distribution's package manager](https://www.geekboots.com/story/list-of-linux-package-manager-and-their-utility), but should be pre-installed for most distributions. For example, on Ubuntu:
       ```bash
       sudo apt update
       sudo apt install python3 python3-pip
       ```

2. **Install `filesize-cli` Globally**

   To run `filesize` anywhere in your CLI on your system (recommended), open your terminal or command prompt and run:

   ```bash
   pip install filesize-cli
   ```

   This command installs the package and makes the `filesize` command available globally.

3. **Verify Installation**

   ```bash
   filesize --help
   ```

   You should see the help message detailing the usage and options.

### From Source

If you prefer to install from the source repository:

1. **Clone the Repository**

   ```bash
   git clone https://gitlab.com/thaikolja/filesize-cli.git
   cd filesize-cli
   ```

2. **Install the Package**

   ```bash
   pip install .
   ```

3. **Verify Installation**

   ```bash
   filesize --help
   ```

## 🚀 Usage

The `filesize` command allows you to view the size of a specified file in your desired unit. Below are the options and examples to help you get started.

### Options

- `-u`, `--unit`: *string* (Optional) Unit to display the file size in. **Default:** `mb`
   1. `b`: Bytes
   2. `kb`: Kilobytes
   3. `mb`: Megabytes
   4. `gb`: Gigabytes
   5. `tb`: Terabytes
- `-r`, `--rate`: *int* (Optional) Conversion rate of the file size. **Default:** `1000`
  1. e.g., `1024`
- `-p`, `--pretty`: *string* **Description:** Pretty print the output by including unit labels. **Default:** *deactivated*
   - `on`: Reduces the output value to two decimals after the comma and adds the size unit, e.g., `365.20 MB`
   - `off`: Displays the output only as float `e.g., 17.428439`


### Examples

#### 1. Display Size in Megabytes (Default)

```bash
filesize examples/image.jpg
```

**Output:**

```
1.00
```

#### 2. Display Size in Kilobytes with Pretty Print

```bash
filesize -u kb -p examples/image.jpg
```

**Output:**
```
1000.00 KB
```

#### 3. Display Size in Bytes without Pretty Print

```bash
filesize -u b examples/base64.txt
```

**Output:**
```
500.00
```

#### 4. Use a Custom Conversion Rate

```bash
filesize -u mb -r 1024 examples/video.mp4
```

**Output:**
```
0.98 MB
```

## 🧪 Testing

Ensuring the reliability and correctness of `filesize-cli` is paramount. The project includes a comprehensive test suite using `pytest`.

### Running Tests

1. **Clone the Repository (if not already done)**

   ```bash
   git clone https://gitlab.com/thaikolja/filesize-cli.git
   cd filesize-cli
   ```

2. **Create and Activate a Virtual Environment**

   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install Dependencies**

   ```bash
   pip install -r requirements.txt
   pip install .
   ```

4. **Run Tests**

   ```bash
   pytest
   ```

### Test Structure

Tests are located in the `tests/` directory and cover various scenarios, including:

- Displaying file sizes in different units.
- Handling non-existent files.
- Custom conversion rates.
- Pretty and non-pretty outputs.
- Integration tests using real example files.

## 🤝 Contributing

Contributions are welcome! Whether it's reporting a bug, suggesting a feature, or submitting a pull request, your input helps improve `filesize CLI`.

### Steps to Contribute

1. **Fork the Repository**

   Click the "Fork" button on the [GitLab repository](https://gitlab.com/thaikolja/filesize-cli) to create your own copy.

2. **Clone Your Fork**

   ```bash
   git clone https://gitlab.com/yourusername/filesize-cli.git
   cd filesize-cli
   ```

3. **Create a New Branch**

   ```bash
   git checkout -b feature/YourFeatureName
   ```

4. **Make Your Changes**

   Implement your feature or fix bugs.

5. **Commit Your Changes**

   ```bash
   git commit -m "Add feature: YourFeatureName"
   ```

6. **Push to Your Fork**

   ```bash
   git push origin feature/YourFeatureName
   ```

7. **Submit a Merge Request**

   Go to the original repository and create a merge request from your fork.

## 📜 License

This project is licensed under the [MIT License](LICENSE).

## 📅 Changelog

See [CHANGELOG.md](CHANGELOG.md) for detailed information about changes.

## 📞 Support

If you encounter any issues or have questions, feel free to open an issue in the [GitLab repository](https://gitlab.com/thaikolja/filesize-cli/issues) or reach out to the maintainer at [kolja.nolte@gmail.com](mailto:kolja.nolte@gmail.com).
