pysextant 1.1.0__tar.gz

pysextant-1.1.0/.github/workflows/teardown_bisect.yml

@@ -0,0 +1,113 @@
+# Diagnostic, run by hand: which teardown pattern makes a window's render
+# thread hang while the main thread joins it. Seen on GPU-less runner VMs:
+# macOS (Apple's software GL; fixed in sextant b1edbb7) and Linux (llvmpipe
+# under xvfb, Python 3.14). Each scenario of tools/teardown_bisect.py runs as
+# its own job, against the wheel of an earlier `wheels` run, so the binary is
+# the one that hung. Results: the run's summary page (one table row per
+# scenario) and, for each hang, its Python and native stacks (macOS `sample`,
+# Linux gdb) as an artifact.
+#
+#   gh workflow run teardown_bisect.yml -f wheels_run_id=<id> [-f platform=Linux] [-f python=3.14] [-f runs=40]
+name: teardown bisect
+
+on:
+  workflow_dispatch:
+    inputs:
+      wheels_run_id:
+        description: Run id of a `wheels` run whose wheels-<platform> artifact to test
+        required: true
+        type: string
+      platform:
+        description: Which wheel, on which runner
+        type: choice
+        options: [macOS, Linux]
+        default: macOS
+      python:
+        description: Python version (the abi3 wheel is used)
+        default: "3.12"
+        type: string
+      runs:
+        description: Fresh-Python runs per scenario
+        default: "40"
+        type: string
+      runner:
+        description: Runner image; empty = macos-15 for macOS, ubuntu-24.04 for Linux
+        default: ""
+        type: string
+
+permissions:
+  contents: read
+  actions: read   # the other run's artifact
+
+jobs:
+  bisect:
+    name: ${{ matrix.scenario }}
+    runs-on: ${{ inputs.runner || (inputs.platform == 'Linux' && 'ubuntu-24.04' || 'macos-15') }}
+    timeout-minutes: 60
+    env:
+      GALLIUM_DRIVER: llvmpipe   # Linux: as the wheels workflow's display job
+    strategy:
+      fail-fast: false
+      matrix:
+        scenario:
+          - exit3
+          - exit1
+          - exit3_framed
+          - exit3_staggered
+          - close3
+          - close_other_first
+          - close_self_first
+    steps:
+      - uses: actions/checkout@v7   # tools/ only; the wheel is not rebuilt
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: wheels-${{ inputs.platform }}
+          path: wheelhouse
+          run-id: ${{ inputs.wheels_run_id }}
+          github-token: ${{ github.token }}
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ inputs.python }}
+
+      - name: Install runtime dependencies (Linux)
+        if: inputs.platform == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libgl1 libgl1-mesa-dri libegl1 libegl-mesa0 xvfb xauth fonts-dejavu-core gdb
+
+      - name: Install the wheel
+        run: |
+          python -m venv "$RUNNER_TEMP/venv"
+          if [ "${{ inputs.platform }}" = Linux ]; then
+            wheel=$(ls wheelhouse/*-abi3-manylinux*.whl)
+          else
+            wheel=$(ls wheelhouse/*-cp312-abi3-macosx_*_arm64.whl)
+          fi
+          "$RUNNER_TEMP/venv/bin/python" -m pip install -q "$wheel"
+          "$RUNNER_TEMP/venv/bin/python" -c "import sys, sextant; print(sys.version, sextant.__file__)"
+          if [ "${{ inputs.platform }}" = Linux ]; then uname -a; else sw_vers; fi
+
+      - name: Run ${{ matrix.scenario }}
+        run: |
+          {
+            echo "| scenario | hangs | other failures | runs done | first hang | slowest |"
+            echo "|---|---|---|---|---|---|"
+          } >> "$GITHUB_STEP_SUMMARY"
+          cd "$RUNNER_TEMP"
+          run=("$RUNNER_TEMP/venv/bin/python" "$GITHUB_WORKSPACE/tools/teardown_bisect.py"
+               "${{ matrix.scenario }}" "${{ inputs.runs }}" --report-dir "$RUNNER_TEMP/reports")
+          if [ "${{ inputs.platform }}" = Linux ]; then
+            xvfb-run -a -s "-screen 0 1920x1080x24" "${run[@]}"
+          else
+            "${run[@]}"
+          fi
+
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: reports-${{ matrix.scenario }}
+          path: ${{ runner.temp }}/reports
+          if-no-files-found: ignore

pysextant-1.1.0/.github/workflows/tests.yml

@@ -0,0 +1,74 @@
+# The dev path: an editable build from the checkout (uv sync) and the whole
+# suite, on each OS. Release wheels are built and tested in wheels.yml.
+name: tests
+
+on:
+  push:
+    branches: [dev]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 40
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { name: Windows, os: windows-2025 }
+          - { name: Linux, os: ubuntu-24.04 }
+          - { name: macOS, os: macos-15 }
+    env:
+      # The runners have no GPU: Mesa's software rasterizer on Windows and Linux.
+      GALLIUM_DRIVER: llvmpipe
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: recursive
+
+      # GLFW's X11 backend and GL headers to build; EGL + llvmpipe for the
+      # display-less export, xvfb for the window tests, a font.
+      - name: Install dependencies (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libgl-dev libgl1-mesa-dri libegl1 libegl-mesa0 libopengl0 \
+            libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libxext-dev \
+            xvfb xauth fonts-dejavu-core
+
+      # Windows' own opengl32 stops at GL 1.1; sextant needs 3.3.
+      - name: Install Mesa llvmpipe (Windows)
+        if: runner.os == 'Windows'
+        uses: ssciwr/setup-mesa-dist-win@v3
+
+      - uses: astral-sh/setup-uv@v10.2.0  # no floating major tag
+        with:
+          enable-cache: true
+
+      # Builds sextant and the extension from source (~2 min).
+      - name: Build (uv sync)
+        run: uv sync
+
+      - name: Tests
+        if: runner.os != 'Linux'
+        run: uv run pytest
+
+      # Twice on Linux: with no display (the EGL export path, window tests
+      # skipped) and under xvfb (everything).
+      - name: Tests, no display (Linux)
+        if: runner.os == 'Linux'
+        run: uv run pytest
+
+      - name: Tests, xvfb (Linux)
+        if: runner.os == 'Linux'
+        run: xvfb-run -a -s "-screen 0 1920x1080x24" uv run pytest

pysextant-1.1.0/.github/workflows/wheels.yml

@@ -0,0 +1,220 @@
+# Release wheels and the sdist, tested, and published on a version tag.
+#
+# The build settings are [tool.cibuildwheel] in pyproject.toml, so a local
+# `cibuildwheel` run builds the same wheels.
+#
+# Publishing uses PyPI trusted publishing (no token): register this repository,
+# this workflow and the environment name ("pypi" / "testpypi") as a trusted
+# publisher on the project's PyPI / TestPyPI page first.
+name: wheels
+
+on:
+  push:
+    tags: ["v*"]
+    branches: [dev]
+    paths:
+      - pyproject.toml
+      - CMakeLists.txt
+      - extern/sextant
+      - .github/workflows/wheels.yml
+  pull_request:
+    paths:
+      - pyproject.toml
+      - CMakeLists.txt
+      - extern/sextant
+      - .github/workflows/wheels.yml
+  workflow_dispatch:
+    inputs:
+      target:
+        description: Where to upload the built distributions
+        type: choice
+        options: [none, testpypi, pypi]
+        default: none
+
+permissions:
+  contents: read
+
+jobs:
+  build_wheels:
+    name: Wheels, ${{ matrix.name }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 90
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { name: Windows, os: windows-2025 }
+          - { name: Linux, os: ubuntu-24.04 }
+          # arm64 runner: builds arm64 and x86_64, and tests x86_64 under Rosetta.
+          - { name: macOS, os: macos-15 }
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: recursive
+
+      # The wheel tests render: Windows' own opengl32 stops at GL 1.1.
+      - name: Install Mesa llvmpipe (Windows)
+        if: runner.os == 'Windows'
+        uses: ssciwr/setup-mesa-dist-win@v3
+
+      - uses: pypa/cibuildwheel@v4.2
+        env:
+          GALLIUM_DRIVER: llvmpipe
+        with:
+          output-dir: wheelhouse
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.name }}
+          path: wheelhouse/*.whl
+
+      # A rare exit hang (a window's first GL draw vs. the main thread joining
+      # its render thread) was seen only on these VMs, in about one wheel test
+      # run in twenty: one pytest run cannot show it is gone. Tear windows down
+      # early, many times, with the abi3 arm64 wheel built above.
+      - uses: actions/setup-python@v7
+        if: runner.os == 'macOS'
+        with:
+          python-version: "3.12"
+      - name: Stress window teardown (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          python -m venv "$RUNNER_TEMP/stress"
+          "$RUNNER_TEMP/stress/bin/python" -m pip install -q wheelhouse/*-cp312-abi3-macosx_*_arm64.whl
+          cd "$RUNNER_TEMP"
+          "$RUNNER_TEMP/stress/bin/python" "$GITHUB_WORKSPACE/tools/stress_exit.py" 100
+
+  build_sdist:
+    name: sdist
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: recursive
+      - uses: astral-sh/setup-uv@v10.2.0  # no floating major tag
+      # pypa/build, not `uv build`: [tool.uv]'s no-build-isolation-package
+      # (for the dev venv) makes uv build without isolation, and there is no
+      # venv with scikit-build-core here.
+      - run: uvx --from build pyproject-build --sdist --installer uv --outdir dist .
+      - uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  # The manylinux container has no X server, so cibuildwheel's tests skip the
+  # window tests there. Here the abi3 wheel runs the whole suite on the host,
+  # under xvfb, and once more with no display.
+  test_linux_display:
+    name: Linux wheel with a display, Python ${{ matrix.python }}
+    needs: build_wheels
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.14"]
+    env:
+      GALLIUM_DRIVER: llvmpipe
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: recursive
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: actions/download-artifact@v8
+        with:
+          name: wheels-Linux
+          path: wheelhouse
+      - name: Install runtime dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libgl1 libgl1-mesa-dri libegl1 libegl-mesa0 xvfb xauth fonts-dejavu-core
+      - name: Install the wheel
+        run: python -m pip install wheelhouse/*-abi3-manylinux*.whl pytest pytest-timeout
+      # As cibuildwheel runs them: away from the source tree, so the installed
+      # package is what gets imported.
+      - name: Copy the tests
+        run: |
+          mkdir -p "$RUNNER_TEMP/t/extern/sextant"
+          cp -R pyproject.toml tests "$RUNNER_TEMP/t/"
+          cp -R extern/sextant/include "$RUNNER_TEMP/t/extern/sextant/"
+      - name: Tests, xvfb
+        working-directory: ${{ runner.temp }}/t
+        run: xvfb-run -a -s "-screen 0 1920x1080x24" python -m pytest -q
+      - name: Tests, no display
+        working-directory: ${{ runner.temp }}/t
+        run: python -m pytest -q
+
+  # A user without a matching wheel gets the sdist: it must build with pip
+  # alone (sextant's dependencies are fetched at configure time).
+  test_sdist:
+    name: sdist builds and passes
+    needs: build_sdist
+    runs-on: ubuntu-24.04
+    env:
+      GALLIUM_DRIVER: llvmpipe
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: recursive
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - uses: actions/download-artifact@v8
+        with:
+          name: sdist
+          path: dist
+      - name: Install build dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libgl-dev libgl1-mesa-dri libegl1 libegl-mesa0 \
+            libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libxext-dev \
+            fonts-dejavu-core
+      - name: Install the sdist
+        run: python -m pip install dist/*.tar.gz pytest pytest-timeout
+      - name: Copy the tests
+        run: |
+          mkdir -p "$RUNNER_TEMP/t/extern/sextant"
+          cp -R pyproject.toml tests "$RUNNER_TEMP/t/"
+          cp -R extern/sextant/include "$RUNNER_TEMP/t/extern/sextant/"
+      - name: Tests, no display
+        working-directory: ${{ runner.temp }}/t
+        run: python -m pytest -q
+
+  publish:
+    name: Publish to ${{ github.event_name == 'workflow_dispatch' && inputs.target || 'pypi' }}
+    needs: [build_wheels, build_sdist, test_linux_display, test_sdist]
+    if: >-
+      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')) ||
+      (github.event_name == 'workflow_dispatch' && inputs.target != 'none')
+    runs-on: ubuntu-24.04
+    environment:
+      name: ${{ github.event_name == 'workflow_dispatch' && inputs.target || 'pypi' }}
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+      # A tag must name the version being uploaded: v1.1.0 <-> version = "1.1.0".
+      - name: Tag matches the project version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          version=$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match pyproject.toml version $version"
+            exit 1
+          fi
+      - uses: actions/download-artifact@v8
+        with:
+          path: dist
+          merge-multiple: true
+      - run: ls -l dist
+      - name: Upload to TestPyPI
+        if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+      - name: Upload to PyPI
+        if: github.event_name != 'workflow_dispatch' || inputs.target == 'pypi'
+        uses: pypa/gh-action-pypi-publish@release/v1

pysextant-1.1.0/.gitignore

@@ -0,0 +1,9 @@
+/build/
+/dist/
+/.venv/
+__pycache__/
+*.py[cod]
+*.pyd
+*.so
+.pytest_cache/
+*.egg-info/

pysextant-1.1.0/.gitmodules

@@ -0,0 +1,4 @@
+[submodule "extern/sextant"]
+	path = extern/sextant
+	url = https://github.com/BackslashStudio/sextant.git
+	branch = dev

pysextant-1.1.0/.python-version

@@ -0,0 +1 @@
+3.12

pysextant-1.1.0/CMakeLists.txt

@@ -0,0 +1,72 @@
+cmake_minimum_required(VERSION 3.21...4.3)
+project(sextant_py LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+# sextant is compiled in this build and linked statically into the extension:
+# one module cannot disagree with itself about the C++ ABI (the API passes
+# std::string/std::vector across), and the wheel carries no second binary.
+set(SEXTANT_SOURCE_DIR "" CACHE PATH "sextant source tree; empty = the extern/sextant submodule")
+if(NOT SEXTANT_SOURCE_DIR)
+    set(SEXTANT_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/extern/sextant")
+endif()
+if(NOT EXISTS "${SEXTANT_SOURCE_DIR}/CMakeLists.txt")
+    message(FATAL_ERROR "No sextant sources at ${SEXTANT_SOURCE_DIR}: "
+                        "run `git submodule update --init`, or set SEXTANT_SOURCE_DIR")
+endif()
+message(STATUS "sextant sources: ${SEXTANT_SOURCE_DIR}")
+
+# Link libGL.so.1, not GLVND's libOpenGL.so.0 + libGLX.so.0: manylinux allows
+# only the former, and auditwheel would bundle the latter into the wheel.
+set(OpenGL_GL_PREFERENCE LEGACY)
+
+# Static C++ runtime for everything in the build (sextant, its bundled deps,
+# nanobind): python.org's Python ships no msvcp140.dll, and a process that
+# loaded an older one first would break std::mutex in a /MD module.
+set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
+
+set(SEXTANT_BUILD_SHARED OFF CACHE BOOL "" FORCE)
+set(SEXTANT_BUNDLE_DEPS  ON  CACHE BOOL "" FORCE)
+set(SEXTANT_BUILD_TESTS  OFF CACHE BOOL "" FORCE)
+# sextant pins GLFW to X11 on Linux, so its Wayland backend is dead code, and
+# building it needs wayland-scanner/protocols and xkbcommon headers.
+set(GLFW_BUILD_WAYLAND   OFF CACHE BOOL "" FORCE)
+add_subdirectory("${SEXTANT_SOURCE_DIR}" sextant EXCLUDE_FROM_ALL)
+
+find_package(Python 3.10 REQUIRED
+    COMPONENTS Interpreter Development.Module
+    OPTIONAL_COMPONENTS Development.SABIModule)
+find_package(nanobind CONFIG REQUIRED)
+
+nanobind_add_module(_sextant STABLE_ABI NB_STATIC
+    src/ext/module.cpp
+    src/ext/axes.cpp
+    src/ext/axes3d.cpp
+    src/ext/casters.cpp
+    src/ext/data.cpp
+    src/ext/events.cpp
+    src/ext/figure.cpp
+    src/ext/lifecycle.cpp
+    src/ext/messages.cpp)
+target_link_libraries(_sextant PRIVATE sextant::sextant_static)
+
+# Export PyInit__sextant alone (see the map file). Not on macOS: arm64 already
+# exports that symbol only, and x86_64's extra exports are weak typeinfo that
+# libc++ there compares by address, so hiding them could break a catch across
+# images.
+if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
+    # Static libstdc++: a module built with a newer GCC than the host Python
+    # env's libstdc++ (conda's lags the system's) would fail to import on a
+    # missing GLIBCXX_* version. The version script below keeps it all local.
+    # libgcc stays dynamic: with a second, static unwinder an exception thrown
+    # through glibc frames (std::call_once -> pthread_once) reaches libgcc_s's
+    # personality routine with the wrong unwinder's context and aborts.
+    target_link_options(_sextant PRIVATE -static-libstdc++)
+    set(_sextant_map "${CMAKE_CURRENT_SOURCE_DIR}/src/ext/_sextant.map")
+    target_link_options(_sextant PRIVATE "LINKER:--version-script=${_sextant_map}")
+    set_property(TARGET _sextant APPEND PROPERTY LINK_DEPENDS "${_sextant_map}")
+endif()
+
+install(TARGETS _sextant LIBRARY DESTINATION sextant COMPONENT python)

pysextant-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The sextant authors
+
+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.

pysextant-1.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: pysextant
+Version: 1.1.0
+Summary: Scientific plotting from a C++20 core: matplotlib-like figures, 2D and 3D, PNG/SVG export
+License-Expression: MIT
+License-File: LICENSE
+License-File: extern/sextant/LICENSE
+License-File: extern/sextant/THIRD_PARTY_NOTICES.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://github.com/BackslashStudio/sextant
+Project-URL: Source, https://github.com/BackslashStudio/sextant_py
+Project-URL: Issues, https://github.com/BackslashStudio/sextant_py/issues
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.23
+Description-Content-Type: text/markdown
+
+# sextant for Python
+
+Python bindings for [sextant](https://github.com/BackslashStudio/sextant), a C++20 library for scientific
+plotting: 2D and 3D figures in an interactive OpenGL window, and PNG/SVG export with or without a display.
+Two ways in: the core API, which maps sextant's C++ API name for name, and `sextant.pyplot`, which runs
+matplotlib-style code.
+
+## Install
+
+```sh
+python -m pip install pysextant
+```
+
+On PyPI it is **`pysextant`** (`sextant` there is an unrelated project); it imports as `sextant`. The current
+release is 1.1.0. Wheels cover Python 3.10 or later on Windows (x86-64), Linux (x86-64, glibc 2.27+) and macOS 11+ (Apple Silicon and Intel);
+the only dependency is numpy. **[doc/install.md](https://github.com/BackslashStudio/sextant_py/blob/v1.1.0/doc/install.md)** has everything else: building
+[from source](https://github.com/BackslashStudio/sextant_py/blob/v1.1.0/doc/install.md#from-source), [conda](https://github.com/BackslashStudio/sextant_py/blob/v1.1.0/doc/install.md#in-a-conda-environment),
+[what each platform needs at run time](https://github.com/BackslashStudio/sextant_py/blob/v1.1.0/doc/install.md#running-it) (X11/EGL on Linux, the main thread on macOS,
+OpenGL 3.3 on Windows) and [troubleshooting](https://github.com/BackslashStudio/sextant_py/blob/v1.1.0/doc/install.md#troubleshooting).
+
+## Documentation
+
+[doc/README.md](https://github.com/BackslashStudio/sextant_py/blob/v1.1.0/doc/README.md) indexes it: the [core API guide](https://github.com/BackslashStudio/sextant_py/blob/v1.1.0/doc/api.md), [3D plots](https://github.com/BackslashStudio/sextant_py/blob/v1.1.0/doc/3d.md),
+[`sextant.pyplot`](https://github.com/BackslashStudio/sextant_py/blob/v1.1.0/doc/pyplot.md) and the [option reference](https://github.com/BackslashStudio/sextant_py/blob/v1.1.0/doc/reference.md).
+
+## Examples
+
+The core API: keyword arguments are the C++ option structs' fields, enums are strings, and plotting calls
+chain.
+
+```python
+import numpy as np
+import sextant
+
+x = np.linspace(0, 2 * np.pi, 200)
+fig = sextant.Figure(width=800, height=500, title="waves")
+ax = fig.axes()
+ax.line(x, np.sin(x), color="blue", name="sin").line(x, np.cos(x), color="red", linestyle="--", name="cos")
+ax.set_title("sin and cos").legend()
+fig.savefig("waves.png")   # needs no window
+fig.show()                 # in a script, blocks until the window is closed
+```
+
+matplotlib-style code through `sextant.pyplot`:
+
+```python
+import numpy as np
+import sextant.pyplot as plt
+
+x = np.linspace(0, 10, 100)
+fig, ax = plt.subplots(figsize=(7, 4))
+ax.plot(x, np.sin(x), "r-", label="sin")
+ax.scatter(x[::10], np.cos(x[::10]), label="cos, sampled")
+ax.set_xlabel("x")
+ax.legend()
+plt.savefig("mpl.png")
+plt.show()
+```
+
+`pyplot` covers the common calls (`plot`, `scatter`, `bar`, `hist`, `errorbar`, `imshow`, `pcolormesh`, 3D
+`plot_surface`/`scatter`/`bar3d`, `text`/`annotate`, `$...$` math in labels, colorbars, `mpl_connect` events,
+`pause`/`ion`); what sextant cannot draw
+raises an error rather than being ignored. In Jupyter a figure displays inline as PNG.
+
+Windows are interactive (pan, zoom, a panel to edit titles, ticks and data). In a script `show()` blocks until
+the window closes; in a REPL or IPython it returns and the window stays live.
+
+The package is typed (`py.typed`): keyword options and enum names are checked by a type checker (tested with mypy).
+
+## Development
+
+Building needs the toolchain in [doc/install.md](https://github.com/BackslashStudio/sextant_py/blob/v1.1.0/doc/install.md#1-the-c-toolchain).
+
+```sh
+git clone --recursive https://github.com/BackslashStudio/sextant_py.git
+cd sextant_py
+uv sync
+uv run pytest
+```
+
+The install is editable: after a change to the C++ sources, the next `import sextant` rebuilds the extension.
+On Windows any shell works (Visual Studio with the C++ workload is found by itself).
+
+- sextant comes from the `extern/sextant` submodule, pinned to a commit. After a `git pull` that moves the
+  pin, run `git submodule update` (or pull with `--recurse-submodules`).
+- To build against another sextant checkout, set `SEXTANT_SOURCE_DIR` to its absolute path and run
+  `uv sync --reinstall-package pysextant`.
+- After changing a signature, an option field or an enum name, regenerate the type stub with
+  `uv run python tools/gen_stubs.py`; `tests/test_stubs.py` fails until it matches.
+- Release wheels are built by `cibuildwheel` with the settings in `pyproject.toml`, locally the same as in CI
+  (`.github/workflows/wheels.yml`).
+
+## License
+
+MIT. The extension links sextant and the code it bundles (FreeType, libpng, zlib, GLFW, Dear ImGui, NanoVG,
+stb, glad); their notices are in `extern/sextant/THIRD_PARTY_NOTICES.md`, which every wheel and sdist carries
+(`*.dist-info/licenses/`). Portions of this software are copyright © 2026 The FreeType Project
+(www.freetype.org). All rights reserved.