python bindings: add type information and minor fixups

.github/workflows/bindings-c.yml

@@ -0,0 +1,48 @@
+# libpathrs: safe path resolution on Linux
+# Copyright (C) 2019-2024 Aleksa Sarai <cyphar@cyphar.com>
+# Copyright (C) 2019-2024 SUSE LLC
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option) any
+# later version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License along
+# with this program. If not, see <https://www.gnu.org/licenses/>.
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  release:
+    types: [ published ]
+  schedule:
+    - cron: '0 0 * * *'
+
+name: bindings-c
+
+jobs:
+  smoke-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Build and install libpathrs.so.
+      - uses: dtolnay/rust-toolchain@stable
+      - name: build libpathrs
+        run: make release
+      - name: install libpathrs
+        run: sudo ./install.sh --libdir=/usr/lib
+      # Run smoke-tests.
+      - run: make -C examples/c smoke-test
+
+  complete:
+    needs:
+      - smoke-test
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "C CI jobs completed successfully."

.github/workflows/bindings-go.yml

@@ -0,0 +1,58 @@
+# libpathrs: safe path resolution on Linux
+# Copyright (C) 2019-2024 Aleksa Sarai <cyphar@cyphar.com>
+# Copyright (C) 2019-2024 SUSE LLC
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option) any
+# later version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License along
+# with this program. If not, see <https://www.gnu.org/licenses/>.
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  release:
+    types: [ published ]
+  schedule:
+    - cron: '0 0 * * *'
+
+name: bindings-go
+
+jobs:
+  smoke-test:
+    strategy:
+      fail-fast: false
+      matrix:
+        go-version: ["1.18.x", "1.21.x", "1.22.x"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Build and install libpathrs.so.
+      - uses: dtolnay/rust-toolchain@stable
+      - name: build libpathrs
+        run: make release
+      - name: install libpathrs
+        run: sudo ./install.sh --libdir=/usr/lib
+      # Setup go.
+      - name: install go ${{ matrix.go-version }}
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go-version }}
+          check-latest: true
+      # Run smoke-tests.
+      - run: make -C examples/go smoke-test
+
+  complete:
+    needs:
+      - smoke-test
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Go CI jobs completed successfully."

.github/workflows/bindings.yml → .github/workflows/bindings-python.yml

@@ -24,46 +24,32 @@ on:
   schedule:
     - cron: '0 0 * * *'
 
-name: bindings-ci
+name: bindings-python
 
 jobs:
-  c:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      # Build and install libpathrs.so.
-      - uses: dtolnay/rust-toolchain@stable
-      - name: build libpathrs
-        run: make release
-      - name: install libpathrs
-        run: sudo ./install.sh --libdir=/usr/lib
-      # Run smoke-tests.
-      - run: make -C examples/c smoke-test
+  # TODO: Do some kind of lints?
 
-  go:
-    strategy:
-      fail-fast: false
-      matrix:
-        go-version: ["1.18.x", "1.21.x", "1.22.x"]
+  mypy:
+    permissions:
+      contents: read
+      pull-requests: read
+      checks: write # allow the action to annotate code
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      # Build and install libpathrs.so.
-      - uses: dtolnay/rust-toolchain@stable
-      - name: build libpathrs
-        run: make release
-      - name: install libpathrs
-        run: sudo ./install.sh --libdir=/usr/lib
-      # Setup go.
-      - name: install go ${{ matrix.go-version }}
-        uses: actions/setup-go@v5
+      # Set up python venv.
+      - uses: actions/setup-python@v5
+      - name: install mypy
+        run: >-
+          python3 -m pip install --user mypy
+      - uses: tsuyoshicho/action-mypy@v4
         with:
-          go-version: ${{ matrix.go-version }}
-          check-latest: true
-      # Run smoke-tests.
-      - run: make -C examples/go smoke-test
+          github_token: ${{ secrets.github_token }}
+          reporter: github-check
+          workdir: contrib/bindings/python/pathrs
+          fail_on_error: true
 
-  python:
+  smoke-test:
     strategy:
       fail-fast: false
       matrix:
@@ -108,3 +94,11 @@ jobs:
           path: contrib/bindings/python/dist/
       # Run smoke-tests.
       - run: make -C examples/python smoke-test
+
+  complete:
+    needs:
+      - mypy
+      - smoke-test
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Python CI jobs completed successfully."

.github/workflows/rust.yml

@@ -117,3 +117,16 @@ jobs:
         with:
           components: clippy
       - run: cargo clippy --all-features --all-targets
+
+  complete:
+    needs:
+      - check
+      - check-msrv
+      - rustdoc
+      - test
+      - examples
+      - fmt
+      - clippy
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Rust CI jobs completed successfully."

CHANGELOG.md

@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ### Fixes ###
 - python bindings: add a minimal README for PyPI.
 - python bindings: actually export `PROC_ROOT`.
+- python bindings: add type annotations and `py.typed` to allow for downstream
+  users to get proper type annotations for the API.
 
 ## [0.1.1] - 2024-10-01 ##
 

contrib/bindings/python/Makefile

@@ -19,7 +19,7 @@ PIP ?= pip3
 
 SRC_FILES := $(wildcard *.py pathrs/*.py)
 
-dist: $(SRC_FILES)
+dist: $(SRC_FILES) pyproject.toml
 	$(PYTHON) -m build
 
 .PHONY: clean

contrib/bindings/python/pathrs/.gitignore

@@ -1,2 +1,2 @@
 /__pycache__/
-/_libpathrs_cffi*
+/_libpathrs_cffi.*

contrib/bindings/python/pathrs/__init__.py

@@ -15,7 +15,23 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import importlib
+import importlib.metadata
+
+from . import _pathrs
 from ._pathrs import *
 
-# TODO: Figure out a way to keep this version up-to-date with Cargo.toml.
-__version__ = "0.0.2"
+# In order get pydoc to include the documentation for the re-exported code from
+# _pathrs, we need to include all of the members in __all__. Rather than
+# duplicating the member list here explicitly, just re-export __all__.
+__all__ = []
+__all__ += _pathrs.__all__  # pyright doesn't support "=" here.
+
+try:
+    # In order to avoid drift between this version and the dist-info/ version
+    # information, just fill __version__ with the dist-info/ information.
+    __version__ = importlib.metadata.version("pathrs")
+except importlib.metadata.PackageNotFoundError:
+    # We're being run from a local directory without an installed version of
+    # pathrs, so just fill in a dummy version.
+    __version__ = "<unknown>"

contrib/bindings/python/pathrs/_libpathrs_cffi/__init__.pyi

@@ -0,0 +1,19 @@
+# libpathrs: safe path resolution on Linux
+# Copyright (C) 2019-2024 Aleksa Sarai <cyphar@cyphar.com>
+# Copyright (C) 2019-2024 SUSE LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import cffi
+
+ffi: cffi.FFI

contrib/bindings/python/pathrs/_libpathrs_cffi/lib.pyi

@@ -0,0 +1,82 @@
+# libpathrs: safe path resolution on Linux
+# Copyright (C) 2019-2024 Aleksa Sarai <cyphar@cyphar.com>
+# Copyright (C) 2019-2024 SUSE LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import cffi
+
+from typing import Optional, overload, type_check_only, Union
+
+# TODO: Remove this once we only support Python >= 3.10.
+from typing_extensions import TypeAlias, Literal
+
+from .._pathrs import CBuffer, CString
+
+# pathrs_errorinfo_t *
+@type_check_only
+class CError:
+    saved_errno: int
+    description: CString
+
+ErrorId: TypeAlias = int
+RawFd: TypeAlias = int
+
+# TODO: We actually return Union[CError, cffi.FFI.NULL] but we can't express
+#       this using the typing stubs for CFFI...
+def pathrs_errorinfo(err_id: Union[ErrorId, int]) -> CError: ...
+def pathrs_errorinfo_free(err: CError) -> None: ...
+
+ProcfsBase: TypeAlias = int
+
+PATHRS_PROC_ROOT: ProcfsBase
+PATHRS_PROC_SELF: ProcfsBase
+PATHRS_PROC_THREAD_SELF: ProcfsBase
+
+def pathrs_proc_open(
+    base: ProcfsBase, path: CString, flags: int
+) -> Union[RawFd, ErrorId]: ...
+def pathrs_proc_readlink(
+    base: ProcfsBase, path: CString, linkbuf: CBuffer, linkbuf_size: int
+) -> Union[int, ErrorId]: ...
+def pathrs_root_open(path: CString) -> Union[RawFd, ErrorId]: ...
+def pathrs_reopen(fd: RawFd, flags: int) -> Union[RawFd, ErrorId]: ...
+def pathrs_resolve(rootfd: RawFd, path: CString) -> Union[RawFd, ErrorId]: ...
+def pathrs_resolve_nofollow(rootfd: RawFd, path: CString) -> Union[RawFd, ErrorId]: ...
+def pathrs_creat(
+    rootfd: RawFd, path: CString, flags: int, filemode: int
+) -> Union[RawFd, ErrorId]: ...
+def pathrs_rename(
+    rootfd: RawFd, src: CString, dst: CString, flags: int
+) -> Union[Literal[0], ErrorId]: ...
+def pathrs_rmdir(rootfd: RawFd, path: CString) -> Union[Literal[0], ErrorId]: ...
+def pathrs_unlink(rootfd: RawFd, path: CString) -> Union[Literal[0], ErrorId]: ...
+def pathrs_remove_all(rootfd: RawFd, path: CString) -> Union[RawFd, ErrorId]: ...
+def pathrs_mkdir(
+    rootfd: RawFd, path: CString, mode: int
+) -> Union[Literal[0], ErrorId]: ...
+def pathrs_mkdir_all(
+    rootfd: RawFd, path: CString, mode: int
+) -> Union[Literal[0], ErrorId]: ...
+def pathrs_mknod(
+    rootfd: RawFd, path: CString, mode: int, dev: int
+) -> Union[Literal[0], ErrorId]: ...
+def pathrs_hardlink(
+    rootfd: RawFd, path: CString, target: CString
+) -> Union[Literal[0], ErrorId]: ...
+def pathrs_symlink(
+    rootfd: RawFd, path: CString, target: CString
+) -> Union[Literal[0], ErrorId]: ...
+def pathrs_readlink(
+    rootfd: RawFd, path: CString, linkbuf: CBuffer, linkbuf_size: int
+) -> Union[int, ErrorId]: ...