Metadata-Version: 2.4
Name: k3num
Version: 0.1.10
Summary: Human-readable number formatting and hex string utilities
Author-email: Zhang Yanpo <drdr.xp@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/pykit3/k3num
Project-URL: Documentation, https://k3num.readthedocs.io
Keywords: number,readable,format,hex,human-readable
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
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
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: k3ut; extra == "dev"
Provides-Extra: publish
Requires-Dist: build; extra == "publish"
Requires-Dist: twine; extra == "publish"
Requires-Dist: pk3; extra == "publish"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Dynamic: license-file

# k3num

[![Build Status](https://github.com/pykit3/k3num/actions/workflows/python-package.yml/badge.svg)](https://github.com/pykit3/k3num/actions/workflows/python-package.yml)
[![Documentation Status](https://readthedocs.org/projects/k3num/badge/?version=stable)](https://k3num.readthedocs.io/en/stable/?badge=stable)
[![Package](https://img.shields.io/pypi/pyversions/k3num)](https://pypi.org/project/k3num)

Convert number to human readable format in a string.

k3num is a component of [pykit3] project: a python3 toolkit set.


k3num convert numbers(or numbers in `dict` or `list`) to human readable
format in string::

    >>> readable(103425)
    '101.0K'
    >>> readable({ 'total': 10240, 'progress': [1, 1024*2.1, 1024*3.2], })
    {'total': '10K', 'progress': ['1', '2.10K', '3.20K']}
    >>> parsenum('5.2K')
    5324.8
    >>> parsenum('10%')
    0.1

Attributes:
    value_to_unit(dict): map of int to unit, e.g.: `1024 -> "K"`, `1024² -> "M"`.

        Usage::

            >>> value_to_unit[1024**2]
            'M'

            >>> unit_to_value['K']
            1024

    unit_to_value(dict): reverse map of `value_to_unit`.


k3num.Hex provides hex integer with arithmatic support.

Different ways to create a 4-byte crc32 hex str::

    >>> Hex(0x0102, 4)
    '00000102'
    >>> Hex(0x0102, 'crc32')
    '00000102'
    >>> Hex.crc32(0x0102)
    '00000102'
    >>> Hex('00000102', 'crc32')
    '00000102'
    >>> Hex.crc32('00000102')
    '00000102'


Create with a tuple of prefix and a filling byte::

    >>> Hex(('12', 1), 'crc32')
    '12010101'


Arithmetic operations::

    >>> Hex(0x0102, 'crc32') + 1
    '00000103'
    >>> Hex(0x0102, 'crc32') * 2
    '00000204'
    >>> Hex(0x0102, 'crc32') - 1000000
    '00000000'
    >>> Hex(0x0102, 'crc32') * 1000000000
    'ffffffff'


Iterate over sha1 space with a specific step::

    >>> Hex.sha1(0) + Hex.sha1(('10', 0))
    '1000000000000000000000000000000000000000'
    >>> Hex.sha1(0) + Hex.sha1(('10', 0)) * 2
    '2000000000000000000000000000000000000000'



# Install

```
pip install k3num
```

# Synopsis

```python
>>> readable(103425)
'101.0K'
>>> readable({ 'total': 10240, 'progress': [1, 1024*2.1, 1024*3.2], })
{'total': '10K', 'progress': ['1', '2.10K', '3.20K']}
>>> parsenum('5.2K')
5324.8
>>> parsenum('10%')
0.1
>>> value_to_unit[1024**2]
'M'
>>> unit_to_value['K']
1024
>>> Hex(0x0102, 4)
'00000102'
>>> Hex(0x0102, 'crc32')
'00000102'
>>> Hex.crc32(0x0102)
'00000102'
>>> Hex('00000102', 'crc32')
'00000102'
>>> Hex.crc32('00000102')
'00000102'
>>> Hex(('12', 1), 'crc32')
'12010101'
>>> Hex(0x0102, 'crc32') + 1
'00000103'
>>> Hex(0x0102, 'crc32') * 2
'00000204'
>>> Hex(0x0102, 'crc32') - 1000000
'00000000'
>>> Hex(0x0102, 'crc32') * 1000000000
'ffffffff'
>>> Hex.sha1(0) + Hex.sha1(('10', 0))
'1000000000000000000000000000000000000000'
>>> Hex.sha1(0) + Hex.sha1(('10', 0)) * 2
'2000000000000000000000000000000000000000'
```

#   Author

Zhang Yanpo (张炎泼) <drdr.xp@gmail.com>

#   Copyright and License

The MIT License (MIT)

Copyright (c) 2015 Zhang Yanpo (张炎泼) <drdr.xp@gmail.com>


[pykit3]: https://github.com/pykit3
