Skip to content

Commit 767749a

Browse files
timlnxtimlnx
committed
Docs for the docs
1 parent 4655731 commit 767749a

8 files changed

Lines changed: 123 additions & 115 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,3 +53,4 @@ docsite/build/doctrees
5353
bitmathenv3
5454
bitmathenv2
5555
bitmath2
56+
.vscode

‎README.rst‎

Lines changed: 32 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,44 @@
1-
.. image:: https://readthedocs.org/projects/bitmath/badge/?version=latest
2-
:target: http://bitmath.rtfd.org/
3-
:align: right
4-
:height: 19
5-
:width: 77
6-
71
.. image:: https://github.com/timlnx/bitmath/actions/workflows/python.yml/badge.svg
82
:target: https://github.com/timlnx/bitmath/actions/workflows/python.yml
3+
.. image:: https://img.shields.io/pypi/v/bitmath.svg
4+
:target: https://pypi.org/project/bitmath/
5+
:alt: Latest Version
6+
.. image:: https://img.shields.io/pypi/dm/bitmath?style=flat-square
7+
:target: https://pypistats.org/packages/bitmath
8+
:alt: PyPI - Package Downloads
9+
.. image:: https://img.shields.io/pypi/implementation/bitmath?style=flat-square
10+
:alt: PyPI - Implementation
11+
.. image:: https://img.shields.io/pypi/pyversions/bitmath?style=flat-square
12+
:alt: PyPI - Python Version
913

14+
.. image:: https://readthedocs.org/projects/bitmath/badge/?version=latest
15+
:target: http://bitmath.rtfd.org/
1016
.. image:: https://github.com/timlnx/bitmath/actions/workflows/bandit.yml/badge.svg
1117
:target: https://github.com/timlnx/bitmath/actions/workflows/bandit.yml
1218
:alt: Bandit Security Scan
13-
1419
.. image:: https://img.shields.io/github/issues/timlnx/bitmath?style=flat-square
1520
:target: https://github.com/timlnx/bitmath/issues
1621
:alt: Open issues
17-
1822
.. image:: https://img.shields.io/github/issues-pr/timlnx/bitmath?style=flat-square
1923
:target: https://github.com/timlnx/bitmath/pulls
2024
:alt: Open pull requests
21-
22-
.. image:: https://img.shields.io/pypi/v/bitmath.svg
23-
:target: https://pypi.org/project/bitmath/
24-
:alt: Latest Version
25-
26-
.. image:: https://img.shields.io/pypi/dm/bitmath?style=flat-square
27-
:target: https://pypistats.org/packages/bitmath
28-
:alt: PyPI - Package Downloads
29-
3025
.. image:: https://img.shields.io/github/stars/timlnx/bitmath?style=flat-square
31-
:target: https://pypistats.org/packages/bitmath
26+
:target: https://github.com/timlnx/bitmath
3227
:alt: GitHub Project Popularity
33-
3428
.. image:: https://img.shields.io/badge/license-MIT-blue.svg
3529
:target: https://github.com/timlnx/bitmath/blob/master/LICENSE
3630
:alt: License
3731

38-
.. image:: https://img.shields.io/pypi/implementation/bitmath?style=flat-square
39-
:alt: PyPI - Implementation
40-
41-
.. image:: https://img.shields.io/pypi/pyversions/bitmath?style=flat-square
42-
:alt: PyPI - Python Version
43-
4432

4533
bitmath
4634
=======
4735

36+
* Free software: MIT License
37+
* Documentation: https://bitmath.readthedocs.io/en/latest/
38+
* Source: https://github.com/timlnx/bitmath
39+
* Bugs: https://github.com/timlnx/bitmath/issues
40+
* Contributing: https://bitmath.readthedocs.io/en/latest/contributing.html
41+
4842
`bitmath <http://bitmath.readthedocs.org/en/latest/>`_ simplifies many
4943
facets of interacting with file sizes in various units. Originally
5044
focusing on file size unit conversion, functionality now includes:
@@ -96,44 +90,33 @@ issues.
9690
Installation
9791
============
9892

99-
The easiest way to install bitmath is via ``dnf`` (or ``yum``) if
100-
you're on a Fedora/RHEL based distribution. bitmath is available in
101-
the main Fedora repositories, as well as EPEL Repositories. As of 2023
102-
bitmath is only developed, tested, and supported for `currently
103-
supported <https://devguide.python.org/versions/>`_ Python releases.
104-
105-
106-
.. code-block:: bash
107-
108-
$ sudo dnf install python3-bitmath
93+
.. admonition:: Seeking a Debian Maintainer
10994

95+
bitmath is not currently packaged for Debian or Ubuntu. If you're
96+
interested in maintaining the package for those distributions, please
97+
see `issue #117 <https://github.com/timlnx/bitmath/issues/117>`_.
11098

111-
**PyPI**:
99+
Requires Python 3.9 or newer. No runtime dependencies outside the
100+
standard library.
112101

113-
You could also install bitmath from `PyPI
114-
<https://pypi.org/project/bitmath/>`_ if you like:
102+
**PyPI** (the typical path):
115103

116104
.. code-block:: bash
117105
118-
$ pip install --user bitmath
119-
120-
121-
122-
**Source**:
106+
pip install bitmath
123107
124-
To install from source, clone the repository and use pip:
108+
**Fedora and EPEL**
125109

126110
.. code-block:: bash
127111
128-
$ git clone https://github.com/timlnx/bitmath.git
129-
$ cd bitmath
130-
$ pip install .
112+
sudo dnf install python3-bitmath
131113
132-
To also install the ``bitmath`` manpage:
114+
**From source**
133115

134116
.. code-block:: bash
135117
136-
$ sudo make install
118+
git clone https://github.com/timlnx/bitmath.git
119+
pip install ./bitmath
137120
138121
139122
Documentation

‎bitmath/__init__.py‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@
4747
import numbers
4848
import os
4949
import os.path
50+
import pathlib
5051
import platform
5152
import re
5253
import shutil
@@ -114,7 +115,7 @@
114115

115116
#: Byte values represented by each SI prefix unit
116117
SI_STEPS = {
117-
'Bit': 1 / 8.0,
118+
'Bit': 1 / 8,
118119
'Byte': 1,
119120
'k': 1000,
120121
'M': 1000000,
@@ -132,7 +133,7 @@
132133

133134
#: Byte values represented by each NIST prefix unit
134135
NIST_STEPS = {
135-
'Bit': 1 / 8.0,
136+
'Bit': 1 / 8,
136137
'Byte': 1,
137138
'Ki': 1024,
138139
'Mi': 1048576,
@@ -552,7 +553,7 @@ def to_Bit(self):
552553

553554
def to_Byte(self):
554555
"""Convert to Byte."""
555-
return Byte(self._byte_value / float(NIST_STEPS['Byte']))
556+
return Byte(self._byte_value / NIST_STEPS['Byte'])
556557

557558
# Properties
558559
Bit = property(lambda s: s.to_Bit())
@@ -1560,12 +1561,14 @@ def query_capacity(path: Union[str, os.PathLike], bestprefix: bool = True,
15601561
return Capacity(total, used, free)
15611562

15621563

1563-
def getsize(path: str, bestprefix: bool = True, system: int = NIST) -> Bitmath:
1564+
def getsize(path: str | pathlib.Path, bestprefix: bool = True, system: int = NIST) -> Bitmath:
15641565
"""Return a bitmath instance in the best human-readable representation
15651566
of the file size at `path`. Optionally, provide a preferred unit
15661567
system by setting `system` to either `bitmath.NIST` (default) or
15671568
`bitmath.SI`.
15681569
1570+
`path` may be a plain string or a :class:`pathlib.Path` object.
1571+
15691572
Optionally, set ``bestprefix`` to ``False`` to get ``bitmath.Byte``
15701573
instances back.
15711574
"""

‎docsite/source/classes.rst‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@ Available Classes
1515
There are two **fundamental** classes available, the :class:`Bit` and
1616
the :class:`Byte`.
1717

18-
There are **24** other classes available, representing all the prefix
19-
units from **k** through **e** (*kilo/kibi* through *exa/exbi*).
18+
There are **32** other classes available, representing all the prefix
19+
units from **k** through **Y** (*kilo/kibi* through *yotta/yobi*).
2020

2121
Classes with **'i'** in their names are **NIST** type classes. They
2222
were defined by the `National Institute of Standards and Technology
@@ -64,6 +64,14 @@ more apparent:
6464
+---------------+--------------+
6565
| ``TiB(Byte)`` | ``TB(Byte)`` |
6666
+---------------+--------------+
67+
| ``Zib(Bit)`` | ``Zb(Bit)`` |
68+
+---------------+--------------+
69+
| ``ZiB(Byte)`` | ``ZB(Byte)`` |
70+
+---------------+--------------+
71+
| ``Yib(Bit)`` | ``Yb(Bit)`` |
72+
+---------------+--------------+
73+
| ``YiB(Byte)`` | ``YB(Byte)`` |
74+
+---------------+--------------+
6775

6876
.. note:: As per SI definition, the ``kB`` and ``kb`` classes begins
6977
with a *lower-case* **k** character.
@@ -107,8 +115,12 @@ Initializing
107115
.. class:: Tib([value=0[, bytes=None[, bits=None]]])
108116
.. class:: YB([value=0[, bytes=None[, bits=None]]])
109117
.. class:: Yb([value=0[, bytes=None[, bits=None]]])
118+
.. class:: YiB([value=0[, bytes=None[, bits=None]]])
119+
.. class:: Yib([value=0[, bytes=None[, bits=None]]])
110120
.. class:: ZB([value=0[, bytes=None[, bits=None]]])
111121
.. class:: Zb([value=0[, bytes=None[, bits=None]]])
122+
.. class:: ZiB([value=0[, bytes=None[, bits=None]]])
123+
.. class:: Zib([value=0[, bytes=None[, bits=None]]])
112124

113125
.. class:: Bitmath([value=0[, bytes=None[, bits=None]]])
114126

‎docsite/source/index.rst‎

Lines changed: 21 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,12 @@
3131
bitmath
3232
#######
3333

34+
* Free software: MIT License
35+
* Documentation: https://bitmath.readthedocs.io/en/latest/
36+
* Source: https://github.com/timlnx/bitmath
37+
* Bugs: https://github.com/timlnx/bitmath/issues
38+
* Contributing: https://bitmath.readthedocs.io/en/latest/contributing.html
39+
3440
`bitmath <http://bitmath.readthedocs.org/en/latest/>`_ simplifies many
3541
facets of interacting with file sizes in various units. Originally
3642
focusing on file size unit conversion, functionality now includes:
@@ -77,35 +83,34 @@ yourself <https://github.com/tbielawa/bitmath/tree/master/tests>`_.
7783
Installation
7884
############
7985

80-
bitmath is available in Fedora and EPEL repositories, as well as
81-
directly available via `PyPI
82-
<https://pypi.org/project/bitmath/>`_. As of 2023 bitmath is only
83-
developed, tested, and supported for `currently supported
84-
<https://devguide.python.org/versions/>`_ Python releases.
86+
.. admonition:: Seeking a Debian Maintainer
8587

86-
**Package Managers**
88+
bitmath is not currently packaged for Debian or Ubuntu. If you're
89+
interested in maintaining the package for those distributions, please
90+
see `issue #117 <https://github.com/timlnx/bitmath/issues/117>`_.
8791

88-
.. code-block:: bash
92+
Requires Python 3.9 or newer. No runtime dependencies outside the
93+
standard library.
8994

90-
$ sudo dnf install python3-bitmath
91-
$ pip install --user bitmath
95+
**PyPI** (the typical path):
9296

97+
.. code-block:: bash
9398
94-
**Source**
99+
pip install bitmath
95100
96-
To install from source, clone the repository and use pip:
101+
**Fedora and EPEL**
97102

98103
.. code-block:: bash
99104
100-
$ git clone https://github.com/timlnx/bitmath.git
101-
$ cd bitmath
102-
$ pip install .
105+
sudo dnf install python3-bitmath
103106
104-
To also install the ``bitmath`` manpage:
107+
**From source**
105108

106109
.. code-block:: bash
107110
108-
$ sudo make install
111+
git clone https://github.com/timlnx/bitmath.git
112+
pip install ./bitmath
113+
109114
110115
111116
Contents

‎docsite/source/index.rst.in‎

Lines changed: 21 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,12 @@
3131
bitmath
3232
#######
3333

34+
* Free software: MIT License
35+
* Documentation: https://bitmath.readthedocs.io/en/latest/
36+
* Source: https://github.com/timlnx/bitmath
37+
* Bugs: https://github.com/timlnx/bitmath/issues
38+
* Contributing: https://bitmath.readthedocs.io/en/latest/contributing.html
39+
3440
`bitmath <http://bitmath.readthedocs.org/en/latest/>`_ simplifies many
3541
facets of interacting with file sizes in various units. Originally
3642
focusing on file size unit conversion, functionality now includes:
@@ -77,35 +83,34 @@ yourself <https://github.com/tbielawa/bitmath/tree/master/tests>`_.
7783
Installation
7884
############
7985

80-
bitmath is available in Fedora and EPEL repositories, as well as
81-
directly available via `PyPI
82-
<https://pypi.org/project/bitmath/>`_. As of 2023 bitmath is only
83-
developed, tested, and supported for `currently supported
84-
<https://devguide.python.org/versions/>`_ Python releases.
86+
.. admonition:: Seeking a Debian Maintainer
8587

86-
**Package Managers**
88+
bitmath is not currently packaged for Debian or Ubuntu. If you're
89+
interested in maintaining the package for those distributions, please
90+
see `issue #117 <https://github.com/timlnx/bitmath/issues/117>`_.
8791

88-
.. code-block:: bash
92+
Requires Python 3.9 or newer. No runtime dependencies outside the
93+
standard library.
8994

90-
$ sudo dnf install python3-bitmath
91-
$ pip install --user bitmath
95+
**PyPI** (the typical path):
9296

97+
.. code-block:: bash
9398

94-
**Source**
99+
pip install bitmath
95100

96-
To install from source, clone the repository and use pip:
101+
**Fedora and EPEL**
97102

98103
.. code-block:: bash
99104

100-
$ git clone https://github.com/timlnx/bitmath.git
101-
$ cd bitmath
102-
$ pip install .
105+
sudo dnf install python3-bitmath
103106

104-
To also install the ``bitmath`` manpage:
107+
**From source**
105108

106109
.. code-block:: bash
107110

108-
$ sudo make install
111+
git clone https://github.com/timlnx/bitmath.git
112+
pip install ./bitmath
113+
109114

110115

111116
Contents

‎docsite/source/instances.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -175,7 +175,7 @@ bitmath objects come with a few basic methods: :py:meth:`to_THING`,
175175
to_THING()
176176
==========
177177

178-
Like the :ref:`available classes <classes_available>`, there are 24
178+
Like the :ref:`available classes <classes_available>`, there are 32
179179
``to_THING()`` methods available. ``THING`` is any of the bitmath
180180
classes. You can even ``to_THING()`` an instance into itself again:
181181

@@ -516,7 +516,7 @@ Instance Properties
516516
THING Properties
517517
================
518518

519-
Like the :ref:`available classes <classes_available>`, there are 24
519+
Like the :ref:`available classes <classes_available>`, there are 32
520520
``THING`` properties available. ``THING`` is any of the bitmath
521521
classes. Under the covers these properties call ``to_THING``.
522522

0 commit comments

Comments
 (0)