Contributing to natsort

If you have an idea for how to improve natsort, we highly encourage you to contribute! Whether it is a simple bug fix, a documentation update, or a more robust parsing algorithm, your help is appreciated.

Because natsort is a foundational library relied upon by thousands of projects, contributions that change the public API must ensure that the library does not become less usable. Strict backwards-compatibility is maintained unless there is an overwhelming, explicitly discussed architectural reason to break it.

Development Environment Setup

The natsort project utilizes modern Python development tooling.

pyproject.toml: Houses all project metadata, build configurations, and linter rules.
tox: Orchestrates testing across multiple Python versions and handles virtual environment isolation.
ruff: Used for lightning-fast code formatting and linting (replacing flake8 and black).
mypy: Enforces strict static type checking.

1. Fork and Clone

First, fork the repository on GitHub and clone it locally:

git clone https://github.com/YOUR-USERNAME/natsort.git
cd natsort

2. Install Tox

You only need to install tox globally or in your base environment. Tox will handle provisioning the rest of the dependencies automatically.

pip install tox

Submitting Code

When contributing code, please follow this checklist to ensure a smooth review process:

Run existing tests: Before touching the code, confirm the existing test suite passes safely on your machine.
```
tox -e py39  # Or whichever Python version you have installed
```
Write tests first: Add tests via the pytest framework (located in the tests/ directory) that cleanly demonstrate your bug or target feature. Verify that these new tests fail on the current codebase.
Make your changes: Implement your fix or feature. Keep in mind that natsort relies heavily on factory closures (in natsort/utils.py) to eliminate runtime branching logic for performance.
Verify Code Quality: Run the linter, formatter, and type checker.
```
tox -e lint
tox -e mypy
```
Run the entire test suite: Confirm that all tests pass, including the property-based tests powered by the hypothesis library.
Send a Pull Request: Submit your PR via GitHub targeting the main branch. GitHub Actions will automatically execute the CI pipeline across all supported platforms (Windows, macOS, Linux, FreeBSD).

Codebase Architecture Primer

If you are diving into the code, here is a quick map:

natsort/natsort.py: The public-facing API (natsorted, realsorted, os_sorted). Handles type-checking inputs and routing to generators.
natsort/ns_enum.py: Defines the bitwise ns Enum flags.
natsort/utils.py: The heavy lifting. This file contains factory functions (e.g., parse_string_factory) that pre-compile regexes and closures based on the ns flags passed. This avoids evaluating if alg & ns.IGNORECASE: inside tight loops.
natsort/compat/: Fallback logic ensuring the library runs smoothly even if C-extensions like fastnumbers or PyICU are missing.

Code of Conduct

In the interest of fostering an open and welcoming environment, we pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity, nationality, religion, or sexual identity.

Our Standards

Examples of behavior that contributes to creating a positive environment include:

Using welcoming and inclusive language.
Being respectful of differing viewpoints and experiences.
Gracefully accepting constructive criticism.
Focusing strictly on what is best for the overall community.
Showing empathy towards other community members.

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team. All complaints will be confidentially reviewed and investigated. Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions.

Adapted from the Contributor Covenant, version 1.4.