bumbag 5.2.1
A package for Python utility functions.
License: BSD-3-Clause
Requires Python: >=3.8,<4.0
Keywords: utility functions,bumbag

<p align="center">
<img src="https://raw.githubusercontent.com/estripling/bumbag/main/docs/source/_static/logo.png" width="180" alt="The BumBag logo.">
</p>

<p align="center">
<a href="https://pypi.org/project/bumbag"><img alt="pypi" src="https://img.shields.io/pypi/v/bumbag"></a>
<a href="https://readthedocs.org/projects/bumbag/?badge=latest"><img alt="docs" src="https://readthedocs.org/projects/bumbag/badge/?version=latest"></a>
<a href="https://github.com/estripling/bumbag/actions/workflows/ci.yml"><img alt="ci status" src="https://github.com/estripling/bumbag/actions/workflows/ci.yml/badge.svg?branch=main"></a>
<a href="https://codecov.io/gh/estripling/bumbag"><img alt="coverage" src="https://codecov.io/github/estripling/bumbag/coverage.svg?branch=main"></a>
<a href="https://github.com/estripling/bumbag/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/pypi/l/bumbag"></a>
</p>

## About

BumBag is a collection of Python utility functions:

- [Documentation](https://bumbag.readthedocs.io/en/stable/index.html)
- [Example usage](https://bumbag.readthedocs.io/en/stable/example.html)
- [API Reference](https://bumbag.readthedocs.io/en/stable/autoapi/bumbag/index.html)

## Installation

`bumbag` is available on [PyPI](https://pypi.org/project/bumbag/) for Python 3.8+:

```shell
pip install bumbag
```

## Examples

Measure elapsed wall-clock time and compute total elapsed time with [`stopwatch`](https://bumbag.readthedocs.io/en/stable/autoapi/bumbag/index.html#bumbag.stopwatch):

```python
>>> import bumbag
>>> import time
>>> with bumbag.stopwatch(1) as sw1:
...     time.sleep(1)
...
2023-01-01 12:00:00 -> 2023-01-01 12:00:01 = 1.00124s - 1
>>> with bumbag.stopwatch(2) as sw2:
...     time.sleep(1)
...
2023-01-01 12:01:00 -> 2023-01-01 12:01:01 = 1.00168s - 2
>>> sw1 + sw2
2.00291s - total elapsed time
```

Easily [`flatten`](https://bumbag.readthedocs.io/en/stable/autoapi/bumbag/index.html#bumbag.flatten) an irregular list:

```python
>>> import bumbag
>>> irregular_list = [
...     ["one", 2],
...     3,
...     [(4, "five")],
...     [[["six"]]],
...     "seven",
...     [],
... ]
>>> list(bumbag.flatten(irregular_list, 8, [9, ("ten",)]))
['one', 2, 3, 4, 'five', 'six', 'seven', 8, 9, 'ten']
```

Use [`highlight_string_differences`](https://bumbag.readthedocs.io/en/stable/autoapi/bumbag/index.html#bumbag.highlight_string_differences) to see differences between two strings easily:

```python
>>> import bumbag
>>> print(bumbag.highlight_string_differences("hello", "hall"))
hello
 |  |
hall
```

Quickly compare two Python sets with [`two_set_summary`](https://bumbag.readthedocs.io/en/stable/autoapi/bumbag/index.html#bumbag.two_set_summary):

```python
>>> import bumbag
>>> x = {"a", "c", "b", "g", "h"}
>>> y = {"c", "d", "e", "f", "g"}
>>> summary = bumbag.two_set_summary(x, y)
>>> print(summary["report"])
    x (n=5): {'a', 'b', 'c', ...}
    y (n=5): {'c', 'd', 'e', ...}
x | y (n=8): {'a', 'b', 'c', ...}
x & y (n=2): {'c', 'g'}
x - y (n=3): {'a', 'b', 'h'}
y - x (n=3): {'d', 'e', 'f'}
x ^ y (n=6): {'a', 'b', 'd', ...}
jaccard = 0.25
overlap = 0.4
dice = 0.4
disjoint?: False
x == y: False
x <= y: False
x <  y: False
y <= x: False
y <  x: False
```

## Contributing to BumBag

Your contribution is greatly appreciated!
See the following links to help you get started:

- [Contributing Guide](https://bumbag.readthedocs.io/en/latest/contributing.html)
- [Developer Guide](https://bumbag.readthedocs.io/en/latest/developers.html)
- [Contributor Code of Conduct](https://bumbag.readthedocs.io/en/latest/conduct.html)

## License

`bumbag` was created by the BumBag Developers.
It is licensed under the terms of the BSD 3-Clause license.