<!-- markdownlint-disable -->
<p align="center">
<a href="https://github.com/DevelopersToolbox/">
<img src="https://cdn.wolfsoftware.com/assets/images/github/organisations/developerstoolbox/black-and-white-circle-256.png" alt="DevelopersToolbox logo" />
</a>
<br />
<a href="https://github.com/DevelopersToolbox/convert-size-package/actions/workflows/cicd.yml">
<img src="https://img.shields.io/github/actions/workflow/status/DevelopersToolbox/convert-size-package/cicd.yml?branch=master&label=build%20status&style=for-the-badge" alt="Github Build Status" />
</a>
<a href="https://github.com/DevelopersToolbox/convert-size-package/blob/master/LICENSE.md">
<img src="https://img.shields.io/github/license/DevelopersToolbox/convert-size-package?color=blue&label=License&style=for-the-badge" alt="License">
</a>
<a href="https://github.com/DevelopersToolbox/convert-size-package">
<img src="https://img.shields.io/github/created-at/DevelopersToolbox/convert-size-package?color=blue&label=Created&style=for-the-badge" alt="Created">
</a>
<br />
<a href="https://github.com/DevelopersToolbox/convert-size-package/releases/latest">
<img src="https://img.shields.io/github/v/release/DevelopersToolbox/convert-size-package?color=blue&label=Latest%20Release&style=for-the-badge" alt="Release">
</a>
<a href="https://github.com/DevelopersToolbox/convert-size-package/releases/latest">
<img src="https://img.shields.io/github/release-date/DevelopersToolbox/convert-size-package?color=blue&label=Released&style=for-the-badge" alt="Released">
</a>
<a href="https://github.com/DevelopersToolbox/convert-size-package/releases/latest">
<img src="https://img.shields.io/github/commits-since/DevelopersToolbox/convert-size-package/latest.svg?color=blue&style=for-the-badge" alt="Commits since release">
</a>
<br />
<a href="https://github.com/DevelopersToolbox/convert-size-package/blob/master/.github/CODE_OF_CONDUCT.md">
<img src="https://img.shields.io/badge/Code%20of%20Conduct-blue?style=for-the-badge" />
</a>
<a href="https://github.com/DevelopersToolbox/convert-size-package/blob/master/.github/CONTRIBUTING.md">
<img src="https://img.shields.io/badge/Contributing-blue?style=for-the-badge" />
</a>
<a href="https://github.com/DevelopersToolbox/convert-size-package/blob/master/.github/SECURITY.md">
<img src="https://img.shields.io/badge/Report%20Security%20Concern-blue?style=for-the-badge" />
</a>
<a href="https://github.com/DevelopersToolbox/convert-size-package/issues">
<img src="https://img.shields.io/badge/Get%20Support-blue?style=for-the-badge" />
</a>
</p>
## Overview
The File Size Converter module provides functions for converting file sizes between different units in both IEC (binary)
and SI (decimal) formats. It includes functionality for getting the full name of a unit from its abbreviation and
converting sizes between units.
## Features
- Convert sizes between different IEC units (e.g., Bytes to Kibibytes).
- Convert sizes between different SI units (e.g., Bytes to Kilobytes).
- Retrieve the full name of a unit from its abbreviation.
- Support for both IEC (binary) and SI (decimal) unit systems.
## Installation
```shell
pip install wolfsoftware.convert-size
```
## Usage
### Importing the Module
```python
import wolfsoftware.convert_size as fsc
```
### Converting Sizes
To convert a size between different units, use the `convert_size` function. You can specify whether to use SI units by setting the `si_units` parameter.
```python
# IEC conversion example
size_in_gib = fsc.convert_size(1024, 'MiB', 'GiB')
print(size_in_gib) # Output: 1.0
# SI conversion example
size_in_gb = fsc.convert_size(1000, 'MB', 'GB', si_units=True)
print(size_in_gb) # Output: 1.0
```
### Getting the Full Name of a Unit
To get the full name of a unit from its abbreviation, use the `get_name_from_code` function.
```python
# IEC unit name example
unit_name = fsc.get_name_from_code('KiB')
print(unit_name) # Output: Kibibyte
# SI unit name example
unit_name = fsc.get_name_from_code('KB', si_units=True)
print(unit_name) # Output: Kilobyte
```
## Functions
##### `convert_size(size: float, start_unit: str, end_unit: str, si_units: bool = False) -> float`
Convert a size between units, either IEC or SI.
- `size` (float): The original size.
- `start_unit` (str): The starting unit abbreviation.
- `end_unit` (str): The ending unit abbreviation.
- `si_units` (bool): If True, use SI units; otherwise, use IEC units.
- Returns (float): The converted size.
- Raises `ValueError`: If the unit abbreviations are not valid.
##### `get_name_from_code(unit: str, si_units: bool = False) -> str`
Get the full name of a unit from its abbreviation.
- `unit` (str): The unit abbreviation.
- `si_units` (bool): If True, use SI units; otherwise, use IEC units.
- Returns (str): The full name of the unit.
- Raises `ValueError`: If the unit abbreviation is not valid.
##### `get_name_from_code_iec(unit: str) -> str`
Get the full name of an IEC unit from its abbreviation.
- `unit` (str): The IEC unit abbreviation.
- Returns (str): The full name of the IEC unit.
- Raises `ValueError`: If the unit abbreviation is not valid.
##### `get_name_from_code_si(unit: str) -> str`
Get the full name of an SI unit from its abbreviation.
- `unit` (str): The SI unit abbreviation.
- Returns (str): The full name of the SI unit.
- Raises `ValueError`: If the unit abbreviation is not valid.
## Error Handling
The module raises `ValueError` exceptions for invalid unit abbreviations. Ensure that you handle these exceptions in your code:
```python
try:
size_in_gib = fsc.convert_size(1024, 'MiB', 'GiB')
except ValueError as e:
print(e)
```
<br />
<p align="right"><a href="https://wolfsoftware.com/"><img src="https://img.shields.io/badge/Created%20by%20Wolf%20on%20behalf%20of%20Wolf%20Software-blue?style=for-the-badge" /></a></p>
Raw data
{
"_id": null,
"home_page": "https://github.com/DevelopersToolbox/convert-size-package",
"name": "wolfsoftware.convert-size",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "python, convert, size",
"author": "Wolf Software",
"author_email": "pypi@wolfsoftware.com",
"download_url": "https://files.pythonhosted.org/packages/3f/fa/7e9aa2c888747c5cb511d1ac84e819c7718dd0bbf3c0e3a39388df9766d6/wolfsoftware_convert_size-0.1.2.tar.gz",
"platform": null,
"description": "<!-- markdownlint-disable -->\n<p align=\"center\">\n <a href=\"https://github.com/DevelopersToolbox/\">\n <img src=\"https://cdn.wolfsoftware.com/assets/images/github/organisations/developerstoolbox/black-and-white-circle-256.png\" alt=\"DevelopersToolbox logo\" />\n </a>\n <br />\n <a href=\"https://github.com/DevelopersToolbox/convert-size-package/actions/workflows/cicd.yml\">\n <img src=\"https://img.shields.io/github/actions/workflow/status/DevelopersToolbox/convert-size-package/cicd.yml?branch=master&label=build%20status&style=for-the-badge\" alt=\"Github Build Status\" />\n </a>\n <a href=\"https://github.com/DevelopersToolbox/convert-size-package/blob/master/LICENSE.md\">\n <img src=\"https://img.shields.io/github/license/DevelopersToolbox/convert-size-package?color=blue&label=License&style=for-the-badge\" alt=\"License\">\n </a>\n <a href=\"https://github.com/DevelopersToolbox/convert-size-package\">\n <img src=\"https://img.shields.io/github/created-at/DevelopersToolbox/convert-size-package?color=blue&label=Created&style=for-the-badge\" alt=\"Created\">\n </a>\n <br />\n <a href=\"https://github.com/DevelopersToolbox/convert-size-package/releases/latest\">\n <img src=\"https://img.shields.io/github/v/release/DevelopersToolbox/convert-size-package?color=blue&label=Latest%20Release&style=for-the-badge\" alt=\"Release\">\n </a>\n <a href=\"https://github.com/DevelopersToolbox/convert-size-package/releases/latest\">\n <img src=\"https://img.shields.io/github/release-date/DevelopersToolbox/convert-size-package?color=blue&label=Released&style=for-the-badge\" alt=\"Released\">\n </a>\n <a href=\"https://github.com/DevelopersToolbox/convert-size-package/releases/latest\">\n <img src=\"https://img.shields.io/github/commits-since/DevelopersToolbox/convert-size-package/latest.svg?color=blue&style=for-the-badge\" alt=\"Commits since release\">\n </a>\n <br />\n <a href=\"https://github.com/DevelopersToolbox/convert-size-package/blob/master/.github/CODE_OF_CONDUCT.md\">\n <img src=\"https://img.shields.io/badge/Code%20of%20Conduct-blue?style=for-the-badge\" />\n </a>\n <a href=\"https://github.com/DevelopersToolbox/convert-size-package/blob/master/.github/CONTRIBUTING.md\">\n <img src=\"https://img.shields.io/badge/Contributing-blue?style=for-the-badge\" />\n </a>\n <a href=\"https://github.com/DevelopersToolbox/convert-size-package/blob/master/.github/SECURITY.md\">\n <img src=\"https://img.shields.io/badge/Report%20Security%20Concern-blue?style=for-the-badge\" />\n </a>\n <a href=\"https://github.com/DevelopersToolbox/convert-size-package/issues\">\n <img src=\"https://img.shields.io/badge/Get%20Support-blue?style=for-the-badge\" />\n </a>\n</p>\n\n## Overview\n\nThe File Size Converter module provides functions for converting file sizes between different units in both IEC (binary)\nand SI (decimal) formats. It includes functionality for getting the full name of a unit from its abbreviation and\nconverting sizes between units.\n\n## Features\n\n- Convert sizes between different IEC units (e.g., Bytes to Kibibytes).\n- Convert sizes between different SI units (e.g., Bytes to Kilobytes).\n- Retrieve the full name of a unit from its abbreviation.\n- Support for both IEC (binary) and SI (decimal) unit systems.\n\n## Installation\n\n```shell\npip install wolfsoftware.convert-size\n```\n\n## Usage\n\n### Importing the Module\n\n```python\nimport wolfsoftware.convert_size as fsc\n```\n\n### Converting Sizes\n\nTo convert a size between different units, use the `convert_size` function. You can specify whether to use SI units by setting the `si_units` parameter.\n\n```python\n# IEC conversion example\nsize_in_gib = fsc.convert_size(1024, 'MiB', 'GiB')\nprint(size_in_gib) # Output: 1.0\n\n# SI conversion example\nsize_in_gb = fsc.convert_size(1000, 'MB', 'GB', si_units=True)\nprint(size_in_gb) # Output: 1.0\n```\n\n### Getting the Full Name of a Unit\n\nTo get the full name of a unit from its abbreviation, use the `get_name_from_code` function.\n\n```python\n# IEC unit name example\nunit_name = fsc.get_name_from_code('KiB')\nprint(unit_name) # Output: Kibibyte\n\n# SI unit name example\nunit_name = fsc.get_name_from_code('KB', si_units=True)\nprint(unit_name) # Output: Kilobyte\n```\n\n## Functions\n\n##### `convert_size(size: float, start_unit: str, end_unit: str, si_units: bool = False) -> float`\n\nConvert a size between units, either IEC or SI.\n\n- `size` (float): The original size.\n- `start_unit` (str): The starting unit abbreviation.\n- `end_unit` (str): The ending unit abbreviation.\n- `si_units` (bool): If True, use SI units; otherwise, use IEC units.\n- Returns (float): The converted size.\n- Raises `ValueError`: If the unit abbreviations are not valid.\n\n##### `get_name_from_code(unit: str, si_units: bool = False) -> str`\n\nGet the full name of a unit from its abbreviation.\n\n- `unit` (str): The unit abbreviation.\n- `si_units` (bool): If True, use SI units; otherwise, use IEC units.\n- Returns (str): The full name of the unit.\n- Raises `ValueError`: If the unit abbreviation is not valid.\n\n##### `get_name_from_code_iec(unit: str) -> str`\n\nGet the full name of an IEC unit from its abbreviation.\n\n- `unit` (str): The IEC unit abbreviation.\n- Returns (str): The full name of the IEC unit.\n- Raises `ValueError`: If the unit abbreviation is not valid.\n\n##### `get_name_from_code_si(unit: str) -> str`\n\nGet the full name of an SI unit from its abbreviation.\n\n- `unit` (str): The SI unit abbreviation.\n- Returns (str): The full name of the SI unit.\n- Raises `ValueError`: If the unit abbreviation is not valid.\n\n## Error Handling\n\nThe module raises `ValueError` exceptions for invalid unit abbreviations. Ensure that you handle these exceptions in your code:\n\n```python\ntry:\n size_in_gib = fsc.convert_size(1024, 'MiB', 'GiB')\nexcept ValueError as e:\n print(e)\n```\n<br />\n<p align=\"right\"><a href=\"https://wolfsoftware.com/\"><img src=\"https://img.shields.io/badge/Created%20by%20Wolf%20on%20behalf%20of%20Wolf%20Software-blue?style=for-the-badge\" /></a></p>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Convert between various sizes.",
"version": "0.1.2",
"project_urls": {
"Documentation": "https://github.com/DevelopersToolbox/convert-size-package",
"Homepage": "https://github.com/DevelopersToolbox/convert-size-package",
"Source": "https://github.com/DevelopersToolbox/convert-size-package",
"Sponsor": "https://github.com/sponsors/WolfSoftware",
"Tracker": "https://github.com/DevelopersToolbox/convert-size-package/issues/"
},
"split_keywords": [
"python",
" convert",
" size"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6cf31283ca2e04b9cbc1781eb443d39227e880576ca34dbdf8f8d5013e888b5a",
"md5": "09e0f064bab62b152c26f75f511182c1",
"sha256": "9a8209f935f7132f0bd94502bdb43f6307f27a4dc322d447b210c22f42274c0a"
},
"downloads": -1,
"filename": "wolfsoftware.convert_size-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "09e0f064bab62b152c26f75f511182c1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 6288,
"upload_time": "2024-06-26T16:48:21",
"upload_time_iso_8601": "2024-06-26T16:48:21.642167Z",
"url": "https://files.pythonhosted.org/packages/6c/f3/1283ca2e04b9cbc1781eb443d39227e880576ca34dbdf8f8d5013e888b5a/wolfsoftware.convert_size-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3ffa7e9aa2c888747c5cb511d1ac84e819c7718dd0bbf3c0e3a39388df9766d6",
"md5": "e759e7a3d5392c9cbce1af87ba66d8e1",
"sha256": "25157ceb88610a92c5ffefad53e0d6c2507e3082eb68b5963d8df2009f746019"
},
"downloads": -1,
"filename": "wolfsoftware_convert_size-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "e759e7a3d5392c9cbce1af87ba66d8e1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 7663,
"upload_time": "2024-06-26T16:48:23",
"upload_time_iso_8601": "2024-06-26T16:48:23.422407Z",
"url": "https://files.pythonhosted.org/packages/3f/fa/7e9aa2c888747c5cb511d1ac84e819c7718dd0bbf3c0e3a39388df9766d6/wolfsoftware_convert_size-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-26 16:48:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DevelopersToolbox",
"github_project": "convert-size-package",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "wolfsoftware.convert-size"
}
JSON
