Metadata-Version: 2.4
Name: largest-remainder
Version: 0.1.0
Summary: Largest Remainder (Hamilton method) algorithm for rounding values while preserving the total.
Author-email: Trustfull Engineering Team <engineering@trustfull.com>
License: MIT License
        
        Copyright (c) 2025 Trustfull
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/fido-id/largest-remainder-py
Project-URL: Documentation, https://github.com/fido-id/largest-remainder-py#readme
Project-URL: Changelog, https://github.com/fido-id/largest-remainder-py/releases
Project-URL: Issues, https://github.com/fido-id/largest-remainder-py/issues
Keywords: largest remainder,hamilton method,rounding,quota
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# largest-remainder [![codecov](https://codecov.io/gh/fido-id/largest-remainder-py/graph/badge.svg?token=WHZvIR6im8)](https://codecov.io/gh/fido-id/largest-remainder-py)


Utilities for working with the **Largest Remainder (Hamilton)** apportionment
algorithm. The package exposes a single `LargestRemainder` helper that rounds
floating point allocations to integers while preserving the requested total.

## Features

- ✅ Deterministic rounding that always matches the requested total
- ✅ Supports both sequences and mappings while keeping the original order of keys
- ✅ Fully type annotated API with comprehensive unit tests

## Installation

The package is published on PyPI. Install it with your preferred Python package
manager:

```bash
pip install largest-remainder
# or
uv add largest-remainder
```

## Usage

```python
from largest_remainder import LargestRemainder

# Round a list of quotas to an integer total
LargestRemainder.round([1, 2, 3], total=10)
# -> [2, 3, 5]

# Round a mapping and keep the original keys
LargestRemainder.round({"a": 1.0, "b": 2.0}, total=10)
# -> {"a": 3, "b": 7}
```

Values can be any non-negative numbers. The algorithm scales the inputs so that
their sum matches the requested `total` and then distributes the remaining units
to the elements with the largest fractional parts.

## Development

1. Install the development dependencies using [uv](https://docs.astral.sh/uv/):
   ```bash
   uv sync --all-extras --dev
   ```
2. Run the linters and unit tests:
   ```bash
   uv run ruff check .
   uv run mypy
   uv run pytest
   ```

## Contributing and community

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for
instructions on setting up a development environment and submitting changes.
Participation in this project is governed by the
[Code of Conduct](CODE_OF_CONDUCT.md).

## Security

If you discover a security issue, please follow the process described in
[SECURITY.md](SECURITY.md).

## License

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