-
Notifications
You must be signed in to change notification settings - Fork 21
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add necessary stuff for deploying an mkdocs site (#25)
* Add necessary stuff for deploying an mkdocs site * Use commit hashes for security * Address feedback; do not duplicate README * Rework structure of the site - Move index.html content into different pages - Write more of an intro in index.html (moved some README content) - Add initial status tracker * remove vestigal pyenv/README.md * Expand stubs in porting guide * Tweaks to CI page * Tweaks to the "porting extension modules" page * Tweaks to "Running with the GIL disabled" page * Extend the Installing page with binary install options * Improve and extend the tracking table Organized alphabetically (more scalable), and using the lessons from the NumPy 2.0 rollout tracker for added columns. * Extend table to all currently tracked packages on issue tracker * Reorder table, nightlies at the end. Add CMake Not relevant for all packages, and importance of nightlies should fade away over time. * Rewrite the front page of the site * Add some front matter to the compatibility tracking page * Update link in README * Add joblib to tracker * Update deploy job to deploy to py-free-threading.github.io repo --------- Co-authored-by: Nathan Goldbaum <nathan.goldbaum@gmail.com> Co-authored-by: Ralf Gommers <ralf.gommers@gmail.com>
- Loading branch information
1 parent
d0dc7f9
commit 692665f
Showing
11 changed files
with
833 additions
and
391 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,52 @@ | ||
name: Deploy to GitHub Pages | ||
|
||
on: | ||
push: | ||
branches: | ||
- main | ||
paths: | ||
- '.github/worksflows/deploy.yml' | ||
- 'docs/**' | ||
- 'mkdocs.yml' | ||
- 'requirements.txt' | ||
pull_request: | ||
branches: | ||
- main | ||
paths: | ||
- '.github/worksflows/deploy.yml' | ||
- 'docs/**' | ||
- 'mkdocs.yml' | ||
- 'requirements.txt' | ||
|
||
jobs: | ||
deploy: | ||
runs-on: ubuntu-22.04 | ||
permissions: | ||
contents: write | ||
concurrency: | ||
group: ${{ github.workflow }}-${{ github.ref }} | ||
|
||
steps: | ||
- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 | ||
with: | ||
fetch-depth: 0 | ||
|
||
- uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5.1.0 | ||
with: | ||
python-version: 3.12 | ||
|
||
- name: Install MkDocs & co | ||
run: pip install -r requirements.txt | ||
|
||
- name: Build site | ||
run: mkdocs build | ||
|
||
- name: Deploy | ||
uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0 | ||
if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' | ||
with: | ||
personal_token: ${{ secrets.PYFREETHREADING_DEPLOY_KEY }} | ||
external_repository: py-free-threading/py-free-threading.github.io | ||
publish_dir: ./site | ||
user_name: 'github-actions[bot]' | ||
user_email: 'github-actions[bot]@users.noreply.github.com' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,68 @@ | ||
# Setting up CI | ||
|
||
Currently the `setup-python` GitHub Action [does not | ||
support](https://github.com/actions/setup-python/issues/771) installing a | ||
free-threaded build. For now, the easiest way to get a free-threaded Python | ||
build on a CI runner is with the `deadsnakes` Ubuntu PPA and the | ||
`deadsnakes-action` GitHub Action: | ||
|
||
```yaml | ||
jobs: | ||
free-threaded: | ||
runs-on: ubuntu-latest | ||
steps: | ||
- uses: actions/checkout@... | ||
- uses: deadsnakes/action@... | ||
with: | ||
python-version: '3.13.0b2' | ||
nogil: true | ||
``` | ||
You should replace the ellipses with versions for the actions. If there is a | ||
newer CPython 3.13 release available since this document was written or | ||
updated, use that version instead. | ||
[cibuildwheel](https://cibuildwheel.pypa.io/en/stable/) has support | ||
for building free-threaded wheels on all platforms. If your project releases | ||
nightly wheels, we suggest configuring `cibuildwheel` to build nightly | ||
free-threaded wheels. | ||
|
||
You will need to specify the following variables in the environment for the | ||
cibuildwheel action: | ||
|
||
```yaml | ||
- name: Build wheels | ||
uses: pypa/cibuildwheel@... | ||
env: | ||
CIBW_PRERELEASE_PYTHONS: True | ||
CIBW_FREE_THREADED_SUPPORT: True | ||
CIBW_BUILD: cp313t-${{ matrix.buildplat }} | ||
# TODO: remove along with installing build deps in | ||
# cibw_before_build.sh when a released cython can build numpy | ||
CIBW_BUILD_FRONTEND: "pip; args: --no-build-isolation" | ||
``` | ||
|
||
As above, replace the ellipses with a `cibuildwheel` version. | ||
|
||
If your project depends on Cython, you will need to install a Cython nightly | ||
wheel in the build, as the newest stable release of Cython cannot generate code | ||
that will compile under the free-threaded build. You likely do not need to | ||
disable `pip`'s build isolation if your project does not depend on Cython. | ||
|
||
You can install nightly wheels for Cython and NumPy using the following | ||
install command: | ||
|
||
``` | ||
pip install -i https://pypi.anaconda.org/scientific-python-nightly-wheels/simple cython numpy | ||
``` | ||
|
||
Note that nightly wheels may not be available on all platforms yet. Windows | ||
wheels, in particular, are not currently available for NumPy or projects that | ||
depend on NumPy (e.g., SciPy). | ||
|
||
You will also likely need to manually pass `-Xgil=0` or set `PYTHON_GIL=0` in | ||
your shell environment while running tests to ensure the GIL is actually | ||
disabled during tests, at least until you can register that your extension | ||
modules support disabling the GIL via `Py_mod_gil` and all of your runtime test | ||
dependencies do the same. It is not currently possible to mark that a Cython | ||
module supports running without the GIL. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,45 @@ | ||
--- | ||
description: py-free-threading is a centralized collection of documentation and trackers around compatibility with free-threaded CPython for the Python open source ecosystem | ||
--- | ||
|
||
# Introduction | ||
|
||
Free-threaded CPython is coming! :material-language-python: :thread: | ||
|
||
After the [acceptance by the Python Steering Council](https://discuss.python.org/t/a-steering-council-notice-about-pep-703-making-the-global-interpreter-lock-optional-in-cpython/30474) | ||
of, and the [gradual rollout strategy](https://discuss.python.org/t/pep-703-making-the-global-interpreter-lock-optional-in-cpython-acceptance/37075) for, | ||
[PEP 703 - Making the Global Interpreter Lock Optional in CPython](https://peps.python.org/pep-0703/), | ||
a lot of work is happening both in CPython itself and across the Python ecosystem. | ||
|
||
This website aims to serve as a centralized resource both for Python package | ||
maintainers and end users interested in supporting or experimenting with | ||
free-threaded Python. An overview of the compatibility status of various Python | ||
libraries is maintained in: | ||
|
||
- [Compatibility status tracking](tracking.md) | ||
|
||
This website also provide documentation and porting guidance - with a focus on | ||
extension modules using the Python C API, because that's where most of the work | ||
will be. The following resources should get you started: | ||
|
||
- [Installing free-threaded CPython](installing_cpython.md) | ||
- [Running Python with the GIL disabled](running-gil-disabled.md) | ||
- [Porting extension modules to support free-threading](porting.md) | ||
- [Setting up CI](ci.md) | ||
|
||
|
||
|
||
## About this site | ||
|
||
Any contributions are very much welcome - please open issues or pull requests | ||
[on this repo](https://github.com/Quansight-Labs/free-threaded-compatibility) | ||
for anything that seems in scope for this site or for tracking issues related | ||
to support for free-threaded Python across the ecosystem. | ||
|
||
This site is maintained primarily by Quansight Labs, where a team is working | ||
together with the Python runtime team at Meta and stakeholders across the | ||
ecosystem to jumpstart work on converting the libraries that make up the | ||
scientific Python and AI/ML stacks to work with the free-threaded build of | ||
CPython 3.13. Additionally, that effort will look at libraries like PyO3 that | ||
are needed to interface with CPython from other languages. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,84 @@ | ||
# Installing a free-threaded Python | ||
|
||
To install a free-threaded CPython interpreter, you can either use a pre-built | ||
binary or build CPython from source. The former is quickest to get started | ||
with. Building from source is not too difficult either though, and in case you | ||
hit a bug that may involve CPython itself then you may want to build from | ||
source. | ||
|
||
|
||
## Binary install options | ||
|
||
There are a growing number of options to install a free-threaded interpreter, | ||
from the python.org installers to Linux distro and Conda package managers. | ||
|
||
!!! note | ||
|
||
For any of these options, please check after the install succeeds that you | ||
have a `pip` version that is recent enough (`>=24.1`), and upgrade it if | ||
that isn't the case. Older `pip` versions will select wheels with the | ||
`cp313` tag (binary-incompatible) rather than the `cp313t` tag. | ||
|
||
|
||
### python.org installers | ||
|
||
The [python.org downloads page](https://www.python.org/download/pre-releases/) | ||
provides macOS and Windows installers that have experimental support. Note | ||
that you have to customize the install - e.g., for Windows there is a | ||
_Download free-threaded binaries_ checkbox under "Advanced Options". | ||
See also the [Using Python on Windows](https://docs.python.org/3.13/using/windows.html#installing-free-threaded-binaries) | ||
section of the Python 3.13 docs. | ||
|
||
|
||
### Linux distros | ||
|
||
=== "Fedora" | ||
|
||
Fedora ships a packaged version, which you can install with: | ||
``` | ||
sudo dnf install python3.13-freethreading | ||
``` | ||
This will install the interpreter at `/usr/bin/python3.13t`. | ||
|
||
=== "Ubuntu" | ||
|
||
For Ubuntu you can use the [deadsnakes PPA](https://launchpad.net/%7Edeadsnakes/+archive/ubuntu/ppa/+packages) | ||
by adding it to your repositories and then installing `python3.13-nogil`: | ||
``` | ||
sudo add-apt-repository ppa:deadsnakes | ||
sudo apt-get update | ||
sudo apt-get install python3.13-nogil | ||
``` | ||
|
||
|
||
### Conda | ||
|
||
Conda packages are currently available for macOS arm64 and Linux x86-64 under a | ||
label in the `ad-testing` (`ad` means "anaconda distribution") channel: | ||
|
||
``` | ||
conda create -n nogil -c defaults -c ad-testing/label/py313_nogil python=3.13 | ||
``` | ||
|
||
|
||
## Building from source | ||
|
||
Currently we suggest building CPython from source using the latest version of | ||
the CPython `main` branch. See | ||
[the build instructions](https://devguide.python.org/getting-started/setup-building/index.html) | ||
in the CPython developer guide. You will need to install [needed third-party | ||
dependencies](https://devguide.python.org/getting-started/setup-building/index.html#install-dependencies) | ||
before building. To build the free-threaded version of CPython, pass | ||
`--disable-gil` to the `configure` script: | ||
|
||
```bash | ||
./configure --with-pydebug --disable-gil | ||
``` | ||
|
||
If you will be switching Python versions often, it may make sense to | ||
build CPython using [pyenv](https://github.com/pyenv/pyenv). In order to | ||
do that, you can use the following: | ||
|
||
```bash | ||
pyenv install --debug 3.13t-dev | ||
``` |
Oops, something went wrong.