Metadata-Version: 2.4
Name: ft_utils
Version: 0.2.0
Summary: A utility library for Free Threaded Python programming
Author-email: "Meta Platforms, Inc." <open-source@fb.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/facebookincubator/ft_utils
Project-URL: Issues, https://github.com/facebookincubator/ft_utils/issues
Project-URL: Documentation, https://github.com/facebookincubator/ft_utils/blob/main/docs/index.md
Keywords: free-threading,nogil,concurrency,threading,atomics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Free Threading :: 2 - Beta
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

![Image](https://github.com/user-attachments/assets/f4ef78b9-8cc0-4264-971f-d6ac76884f3a)
# Welcome to ft_utils!

We're excited to share this library with you, designed to help you build high-performance applications with
Free Threaded Python.

## License

ft_utils is open-source software, licensed under the permissive MIT license. You can find the full license terms in our
[LICENSE file](LICENSE).

## Contributing and Code Standards

We'd love for you to contribute to ft_utils! To ensure that our codebase remains maintainable and efficient, we follow
some simple guidelines. Please take a look at our [CONTRIBUTING.md](CONTRIBUTING.md) document for more information.

### Extra Guidelines

In addition to these guidelines, we have a few extra rules to keep in mind:

* **Language**: We use C11 and Python as our only programming languages. Build scripts can be in other languages.
* **Cross-Platform Compatibility**: Our code must compile on Windows, Linux, and Mac(arm).
* **GIL and Free Threaded Python**: All functionality should work seamlessly on both GIL and Free Threaded Python, although results may vary slightly between the two environments.
* **Unit Tests**: Every feature must have at least one unit test to ensure it works correctly.
* **Benchmarks**: It is best practice to write benchmarks for all new features to further test and to drive our aim of high performance.

## Documentation

See to [documentation](docs/index.md).

## Build And CI

ft_utils is built and tested against the following configurations:

|                                 | CPython 3.13 | CPython 3.13t | CPython 3.14 | CPython 3.14t |
| ------------------------------- | ------------ | ------------- | ------------ | ------------- |
| manylinux: glibc 2.17+ x86-64   | ✅           | ✅            | ✅           | ✅            |
| manylinux: glibc 2.17+ i686     | ✅           | ✅            | ✅           | ✅            |
| manylinux: glibc 2.17+ aarch64  | ✅           | ✅            | ✅           | ✅            |
| musllinux: musl 1.2+ x86-64     | ✅           | ✅            | ✅           | ✅            |
| musllinux: musl 1.2+ i686       | ✅           | ✅            | ✅           | ✅            |
| musllinux: musl 1.2+ aarch64    | ✅           | ✅            | ✅           | ✅            |
| Windows x86-64                  | ✅           | ✅            | ✅           | ✅            |
| macOS 11.0+ ARM64               | ✅           | ✅            | ✅           | ✅            |

These wheels are uploaded to and available on [PyPI](https://pypi.org/project/ft-utils/), along with a
source distribution for platforms not covered above.

### Build from source

You will need a source code version of CPython. To run for Free Threaded Python, at the time of writing, this means
you will require CPython 3.13+ and compile as <PYTHON_VERSION>t.

Please ensure you are in a virtual environment. If you cannot, or do not wish to do this then you will need to comment
out the call to check_env() in setup.py.

Once you have everything in place, please execute setup.py as a python script:

```
python -P setup.py bdist_wheel
```

If this does not work due to networking then you might need use a proxy; for example:

```
https_proxy=http://fwdproxy:8080 python setup.py
```

To install just install the wheel; for example on Windows:

```
python -m pip install build\dist\ft_utils-0.2.0-cp314-cp314-win_amd64.whl
```

Or:

```
python -m pip install --force-reinstall build\dist\ft_utils-0.2.0-cp314-cp314-win_amd64.whl
```

### Testing from source

Once installed you can test the code via `python -m ft_utils.tests.test_run_all`. This will run all the tests and benchmarks which are known to be good and report any failures.
