Release version 1.0 (#112)

⚠️ Project was rewritten from scratch for `1.x`.

Changes:
- Updated CLI interface, some options were removed, please see
`pybind11-stubgen --help` for details
- Replaced regex-based signature parsing with more robust procedure
which enables to produce partially degraded signatures
 - Added type parsing/replacing, including deeply annotated types
 - Support implicit imports required for static analysis
 - Add introspection of pure python functions
 - Improved structure of test binary pybind module

Author: sizmailov

.git-blame-ignore-revs

@@ -1,2 +1,2 @@
 ea663c34775284590aef5cf1d087fc1840edb027
-abb3085624a1e982f360086b73686b8b32e47087
+abb3085624a1e982f360086b73686b8b32e47087

.github/workflows/ci.yml

@@ -4,26 +4,35 @@ on:
   workflow_dispatch:
   pull_request:
   push:
+    branches:
+      - master
 
 jobs:
 
   format:
-    name: Format
+    name: Format code
     runs-on: ubuntu-latest
     steps:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
           python-version: '3.10.6'
       - name: Checkout
-        uses: actions/checkout@master
+        uses: actions/checkout@v3
       - name: Install requirements
         run: pip install -r requirements-dev.txt
+      - name: Run isort
+        run: isort --check --profile=black --diff ./pybind11_stubgen
+        if: ${{ failure() ||  success() }}
       - name: Run black
-        run: black --diff . --extend-exclude=tests/pybind11-project-example/external/
+        run: black --diff ./pybind11_stubgen
         if: ${{ failure() ||  success() }}
-      - name: Run isort
-        run: isort --extend-skip=tests/pybind11-project-example/external/ --check --profile=black --diff  .
+      - name: Run flake8
+        run: |
+          flake8 \
+            --max-line-length=88 \
+            --extend-ignore=E203 \
+            --extend-exclude=venv/,.pytest_cache/,.ipynb_checkpoints/,tests/,tmp/,build/
         if: ${{ failure() ||  success() }}
 
   tests:
@@ -32,40 +41,35 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        runs-on: [ubuntu-latest, windows-2022]
+        runs-on: [ ubuntu-latest ]
         python:
-            - "3.10"
-
+          - "3.11"
+          - "3.10"
+          - "3.9"
+        # - "3.8" #  `typing.Annotated` not available
+        include:
+          - runs-on: "windows-2022"
+            python: "3.10"
     steps:
-    - uses: actions/checkout@v2
-      with:
-        submodules: 'recursive'
-
-    - name: Setup Python ${{ matrix.python }}
-      uses: actions/setup-python@v2
-      with:
-        python-version: ${{ matrix.python }}
+      - uses: actions/checkout@v3
 
-    - name: Update CMake
-      uses: jwlawson/[email protected]
+      - name: Setup Python ${{ matrix.python }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python }}
 
-    - name: Setup annotations on Linux
-      if: runner.os == 'Linux'
-      run: python -m pip install pytest-github-actions-annotate-failures
+      - name: Update CMake
+        uses: jwlawson/[email protected]
 
-    - name: Install pybind11-stubgens
-      run: |
-        python -m pip install .
-        python -m pip install black isort
+      - name: Setup annotations on Linux
+        if: runner.os == 'Linux'
+        run: python -m pip install pytest-github-actions-annotate-failures
 
-    - name: Install pybind11-project-example
-      run: python -m pip install tests/pybind11-project-example
+      - name: Install requirements
+        run: pip install -r requirements-dev.txt
 
-    - name: Generate stubs
-      run: |
-        pybind11-stubgen cpp_library_bindings  '--output-dir=./tests/stubs/generated' '--root-module-suffix=' '--ignore-invalid=all' '--no-setup-py'
-        black ./tests/stubs/generated
-        isort --profile=black ./tests/stubs/generated
+      - name: Install pybind11-stubgen
+        run: pip install .
 
-    - name: Check stubs
-      run: cd tests ; python compare_walker.py
+      - name: Run tests
+        run: ./tests/run-tests.sh

.github/workflows/deploy.yml

@@ -32,7 +32,7 @@ jobs:
         with:
           path: |
             dist/*.tar.gz
-            dist/*.whl  
+            dist/*.whl
 
   upload_pypi:
     needs: [build_dist]
@@ -47,4 +47,4 @@ jobs:
       - uses: pypa/[email protected]
         with:
           user: __token__
-          password: ${{ secrets.PYPI_API_TOKEN }}
+          password: ${{ secrets.PYPI_API_TOKEN }}

.gitignore

@@ -206,3 +206,6 @@ cython_debug/
 #.idea/
 
 # End of https://www.toptal.com/developers/gitignore/api/c++,cmake,python
+
+
+tmp

.gitmodules

@@ -0,0 +1,37 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: "v4.3.0"
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: no-commit-to-branch
+
+  - repo: local
+    hooks:
+      - id: black
+        name: black
+        entry: black
+        language: python
+        minimum_pre_commit_version: 2.9.2
+        require_serial: true
+        types_or: [ python, pyi ]
+      - id: isort
+        name: isort
+        entry: isort
+        args:
+          - --profile=black
+        language: system
+        types: [ python ]
+        stages: [ commit ]
+      - id: flake8
+        name: flake8
+        exclude: ^(tests)/
+        language: system
+        entry: flake8
+        args:
+          # The line length in black
+          - --max-line-length=88
+          - --extend-ignore=E203
+        types: [ python ]
+        stages: [ commit ]

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+Changelog
+=========
+
+Version 1.0-dev (Aug 29, 2023)
+--------------------------
+⚠️ Project was rewritten from scratch for `1.x`. This allowed me to address some long-standing issues, but I might accidentally brake behaviour you relied on.
+
+Changes:
+ - Updated CLI interface, some options were removed, please see `pybind11-stubgen --help` for details
+ - Replaced regex-based signature parsing with more robust procedure which enables to produce partially degraded signatures
+ - Added type parsing/replacing, including deeply annotated types
+ - Support implicit imports required for static analysis
+ - Add introspection of pure python functions
+ - Support python 3.10+ only (temporarily)
+ - Improved structure of test binary pybind module

CHANGELOG.md

@@ -34,4 +34,4 @@ imposing a separate written license agreement for such Enhancements, then you
 hereby grant the following license: a non-exclusive, royalty-free perpetual
 license to install, use, modify, prepare derivative works, incorporate into
 other computer software, distribute, and sublicense such enhancements or
-derivative works thereof, in binary and source code form.
+derivative works thereof, in binary and source code form.

LICENSE

@@ -0,0 +1,35 @@
+[![pypi](https://img.shields.io/pypi/v/pybind11-stubgen.svg?logo=PyPI&logoColor=white)](https://pypi.org/project/pybind11-stubgen/)
+
+About
+----
+
+Static analysis tools and IDE usually struggle to understand python binary extensions.
+`pybind11-stubgen` generates [stubs](https://peps.python.org/pep-0561/) for python extensions to make them less opaque.
+
+While the CLI tool includes tweaks to target modules compiled specifically
+with [pybind11](https://github.com/pybind/pybind11) but it should work well with modules built with other libraries.
+
+```bash
+# Install
+pip install pybind11-stubgen
+
+# Generate stubs for numpy
+pybind11-stubgen numpy
+```
+
+Usage
+-----
+
+```
+pybind11-stubgen [-h]
+                 [-o OUTPUT_DIR]
+                 [--root-suffix ROOT_SUFFIX]
+                 [--ignore-invalid-expressions REGEX]
+                 [--ignore-invalid-identifiers REGEX]
+                 [--ignore-unresolved-names REGEX]
+                 [--ignore-all-errors]
+                 [--numpy-array-wrap-with-annotated-fixed-size| --numpy-array-remove-parameters]
+                 [--print-invalid-expressions-as-is]
+                 [--exit-code]
+                 MODULE_NAME
+```