oaubert
diff --git a/‎.github/workflows/ruff.yml‎
Lines changed: 22 additions & 0 deletions b/‎.github/workflows/ruff.yml‎
Lines changed: 22 additions & 0 deletions
diff --git a/‎.github/workflows/tests.yml‎
Lines changed: 16 additions & 0 deletions b/‎.github/workflows/tests.yml‎
Lines changed: 16 additions & 0 deletions
diff --git a/‎.gitignore‎
Lines changed: 13 additions & 0 deletions b/‎.gitignore‎
Lines changed: 13 additions & 0 deletions
diff --git a/‎.gitmodules‎
Lines changed: 4 additions & 0 deletions b/‎.gitmodules‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎.pre-commit-config.yaml‎
Lines changed: 32 additions & 0 deletions b/‎.pre-commit-config.yaml‎
Lines changed: 32 additions & 0 deletions
diff --git a/‎AUTHORS‎
Lines changed: 3 additions & 0 deletions b/‎AUTHORS‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎Makefile‎
Lines changed: 23 additions & 10 deletions b/‎Makefile‎
Lines changed: 23 additions & 10 deletions
diff --git a/‎README.md‎
Lines changed: 82 additions & 32 deletions b/‎README.md‎
Lines changed: 82 additions & 32 deletions
diff --git a/‎TODO‎
Lines changed: 0 additions & 4 deletions b/‎TODO‎
Lines changed: 0 additions & 4 deletions
diff --git a/‎dev_setup.py‎
Lines changed: 63 additions & 0 deletions b/‎dev_setup.py‎
Lines changed: 63 additions & 0 deletions
@@ -0,0 +1,22 @@
+name: Ruff
+
+on: [push, pull_request]
+
+jobs:
+  linting:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: chartboost/ruff-action@v1
+        with:
+          args: "check --config ruff.toml"
+          src: "./generator/generate.py ./tests ./dev_setup.py"
+
+  formatting:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: chartboost/ruff-action@v1
+        with:
+          args: "format --check --config ruff.toml"
+          src: "./generator/generate.py ./tests ./dev_setup.py ./generator/templates"
@@ -0,0 +1,16 @@
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: |
+          sudo apt-get install -y vlc pulseaudio libvlc-dev
+          pulseaudio --start
+          python3 dev_setup.py
+          . .venv/bin/activate
+          make test_generator
+          make test_bindings
@@ -38,3 +38,16 @@ nosetests.xml
 .mr.developer.cfg
 .project
 .pydevproject
+
+# Virtual environment
+.venv
+venv
+
+# pyenv version
+.python-version
+
+# Preprocessed libvlc header files
+*.preprocessed*
+
+# Documentation
+docs/_build/
@@ -0,0 +1,4 @@
+[submodule "vendor/tree-sitter-c"]
+    path = vendor/tree-sitter-c
+    url = https://github.com/tree-sitter/tree-sitter-c
+    ignore = dirty
@@ -0,0 +1,32 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+- repo: local
+  hooks:
+    # Abort the commit if there is one or more linting errors
+    - id: lint
+      name: Check no linting errors
+      entry: ruff check --config ruff.toml
+      language: python
+      files: |
+        (?x)^(
+          generator/generate\.py|
+          tests/.*\.py|
+          dev_setup\.py
+        )$
+      minimum_pre_commit_version: "2.9.2"
+
+    # Abort the commit if code wasn't formatted
+    - id: format
+      name: Check code is formatted
+      entry: ruff format --config ruff.toml --check
+      language: python
+      files: |
+        (?x)^(
+          generator/generate\.py|
+          tests/.*\.py|
+          dev_setup\.py|
+          generator/templates/.*\.py
+        )$
+      minimum_pre_commit_version: "2.9.2"
+
@@ -20,3 +20,6 @@ Jonas Haag <jonas@lophus.org>
 Patrick Fay <pf5151@gmail.com>
 Vaksick <vaksick@gmail.com>
 Kim Wiktorén <kim.wiktoren@gmail.com>
+Wafa Harir <harir.wafa.harir@gmail.com>
+Yann Salmon <yannsalmon.pro@gmail.com>
+Marwa Tabib <marwatabib21@gmail.com>
@@ -29,6 +29,8 @@ ifeq ($(TARGETS),)
 TARGETS=missing
 endif
 
+.PHONY: missing dev installed dist deb doc test_bindings2 test_bindings test_generator test2 test tests sdist publish format rcheck check clean
+
 all: $(TARGETS)
 
 missing:
@@ -59,25 +61,36 @@ $(VERSIONED_NAME): generator/generate.py generator/templates/header.py generator
 doc: $(VERSIONED_NAME)
 	-pydoctor --project-name=python-vlc --project-url=https://github.com/oaubert/python-vlc/ --make-html --verbose --html-output=doc $<
 
-test2: $(MODULE_NAME)
-	PYTHONPATH=$(VERSIONED_PATH):$(PROJECT_ROOT) python tests/test.py
-	PYTHONPATH=$(DEV_PATH):$(PROJECT_ROOT) python tests/test.py
+test_bindings2: $(MODULE_NAME)
+	PYTHONPATH=$(VERSIONED_PATH):$(PROJECT_ROOT) python tests/test_bindings.py
+	PYTHONPATH=$(DEV_PATH):$(PROJECT_ROOT) python tests/test_bindings.py
+
+test_bindings: $(MODULE_NAME)
+	PYTHONPATH=$(VERSIONED_PATH):$(PROJECT_ROOT) python3 tests/test_bindings.py
+	PYTHONPATH=$(DEV_PATH):$(PROJECT_ROOT) python3 tests/test_bindings.py
+
+test_generator: $(MODULE_NAME)
+	PYTHONPATH=$(VERSIONED_PATH):$(PROJECT_ROOT) python3 tests/test_generator.py
+	PYTHONPATH=$(DEV_PATH):$(PROJECT_ROOT) python3 tests/test_generator.py
+
+test2: test_bindings2
 
-test: $(MODULE_NAME)
-	PYTHONPATH=$(VERSIONED_PATH):${PROJECT_ROOT} python3 tests/test.py
-	PYTHONPATH=$(DEV_PATH):$(PROJECT_ROOT) python3 tests/test.py
+test: test_bindings test_generator
+
+tests: test test2
 
 sdist: $(VERSIONED_NAME)
 	cd $(VERSIONED_PATH); python3 setup.py bdist_wheel sdist
 
 publish: $(VERSIONED_NAME)
 	cd $(VERSIONED_PATH); python3 setup.py bdist_wheel sdist && twine upload dist/*
 
-tests: test test2
+format:
+	ruff format ./generator/generate.py ./tests dev_setup.py ./generator/templates/
+	ruff check --fix --fix-only --exit-zero ./generator/generate.py ./tests dev_setup.py ./generator/templates
 
-check: $(MODULE_NAME)
-	-pyflakes $<
-	-pylint $<
+check:
+	ruff check ./generator/generate.py ./tests dev_setup.py
 
 clean:
 	-$(RM) -r $(DEV_PATH)
 
@@ -1,26 +1,24 @@
-Python ctypes-based bindings for libvlc
-=======================================
+# Python ctypes-based bindings for libvlc
+
+![](https://img.shields.io/github/actions/workflow/status/yanns1/python-vlc/tests.yml?event=push&label=tests)
 
 This file documents the bindings generator, not the bindings
 themselves. For the bindings documentation, see the README.module
 file.
 
-
 The bindings generator generates ctypes-bindings from the include
 files defining the public API. The same generated module should be
-compatible with various versions of libvlc 2.* and 3.*. However, there
+compatible with various versions of libvlc 2.\* and 3.\*. However, there
 may be incompatible changes between major versions. Versioned bindings
 for 2.2 and 3.0 are provided in the repository.
 
-License
--------
+## License
 
 The module generator is licensed under the GNU General Public License
-version 2 or later.  The generated module is licensed, like libvlc,
+version 2 or later. The generated module is licensed, like libvlc,
 under the GNU Lesser General Public License 2.1 or later.
 
-Building from source
---------------------
+## Development
 
 You can get the latest version of the code generator from
 <https://github.com/oaubert/python-vlc/> or
@@ -31,31 +29,58 @@ vlc/bindings/python, so that it finds the development include files,
 or to find the installed include files in /usr/include (on Debian,
 install libvlc-dev).
 
+Once you have cloned the project, you can run
+
+```
+python3 dev_setup.py
+```
+
+from the root.
+This script will install everything that is needed (submodules,
+virtual environment, packages, etc.) for you to generate the bindings.
+Then, activate the virtual environment:
+
+- On Linux with Bash:
+  ```
+  . .venv/bin/activate
+  ```
+- On Windows with Powershell:
+  ```
+  .\.venv\Scripts\Activate.ps1
+  ```
+
+See https://docs.python.org/3/library/venv.html#how-venvs-work for other os-shell combinations.
+
 To generate the vlc.py module and its documentation, for both the
-development version and the installed VLC version, use
+development version and the installed VLC version, use `make`.
 
-    make
+For running tests, use `make test`.
+Note that you need vlc installed because some tests require the
+libvlc's dynamic library to be present on the system.
 
 If you want to generate the bindings from an installed version of the
 VLC includes (which are expected to be in /usr/include/vlc), use the
-'installed' target:
+'installed' target: `make installed`.
 
-    make installed
+See more recipes in the Makefile.
 
-To install it for development purposes (add a symlink to your Python
+To install python-vlc for development purposes (add a symlink to your Python
 library) simply do
 
-    python setup.py develop
+```
+python setup.py develop
+```
 
 preferably inside a virtualenv. You can uninstall it later with
 
-    python setup.py develop --uninstall
+```
+python setup.py develop --uninstall
+```
 
 Documentation building needs epydoc. An online build is available at
 <http://olivieraubert.net/vlc/python-ctypes/>
 
-Packaging
----------
+## Packaging
 
 The generated module version number is built from the VLC version
 number and the generator version number:
@@ -67,24 +92,49 @@ so that it shared it major.minor with the corresponding VLC.
 To generate the reference PyPI module (including setup.py, examples
 and metadata files), use
 
-    make dist
+```
+make dist
+```
+
+## Architecture
+
+First of all, the bindings generator is in generator/generate.py.
+
+It really is the conjunction of two things:
+
+1. A **parser** of C header files (those of libvlc): that is the class `Parser`.
+1. A **generator** of Python bindings: that is the class `PythonGenerator`.
+
+`Parser` parses libvlc's headers and produce a kind of AST where nodes are
+instances of either `Struct`, `Union`, `Func`, `Par`, `Enum` or `Val`.
+The information kept is what is necessary for `PythonGenerator` to then produce
+the bindings.
+
+Until version 2 of the bindings generator, parsing was regex-based.
+It worked pretty well thanks to the consistent coding style of libvlc.
+However, it remained rather fragile.
+
+Since version 2, parsing is done using [Tree-sitter](https://tree-sitter.github.io/tree-sitter/).
+More specifically, we use the [C Tree-sitter grammar](https://github.com/tree-sitter/tree-sitter-c)
+and [Tree-sitter's Python bindings](https://github.com/tree-sitter/py-tree-sitter).
+It offers a more complete and robust parsing of C code.
+The job of `Parser` is thus to transform the AST[^1] produced by Tree-sitter into an "AST"
+understandable by the generator.
+
+## LibVLC Discord
 
-LibVLC Discord
------------------
 [![Join the chat at https://discord.gg/3h3K3JF](https://img.shields.io/discord/716939396464508958?label=discord)](https://discord.gg/3h3K3JF)
 
 python-vlc is part of the LibVLC Discord Community server. Feel free to come say hi!
 
-How to contribute
------------------
+## How to contribute
+
+Contributions such as:
+
+- reporting and fixing bugs,
+- contributing unit tests
+- contributing examples
 
-There are short-terms contributions (reporting and fixing bugs,
-contributing unit tests, contributing examples). A number of libvlc
-functions are currently blacklisted (search for `_blacklist` in the
-generator code), mostly because of their signature complexity. They
-would benefit some work.
+are welcomed!
 
-Longer terms goals include the rewriting of the generator to use a
-proper parser for the C-syntax (for the moment, the parser relies on
-regexp-based expression, which works thanks to the coding style
-applied in the code, but remains very fragile).
+[^1]: To be exact, it produces a CST: Concrete Syntax Tree.
@@ -1,6 +1,2 @@
 * Add more test coverage
 * Provide more examples
-* Rewrite parsing code using a proper C parser, such as
-https://github.com/eliben/pycparser
-or
-https://github.com/albertz/PyCParser
@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+
+"""Script to get going after having cloned the repository."""
+
+import os
+import sys
+from pathlib import Path
+from subprocess import PIPE, STDOUT, CalledProcessError, run
+
+PROJECT_ROOT = Path(__file__).parent
+cwd = Path.cwd()
+assert (
+    cwd.resolve() == PROJECT_ROOT.resolve()
+), f"You should run that script from {PROJECT_ROOT}, but current working directory is {cwd}."
+
+# See https://stackoverflow.com/questions/1854/how-to-identify-which-os-python-is-running-on
+on_windows = os.name == "nt"
+
+
+def run_cmd(mess, cmd):
+    print(f"{mess}...", end=" ", flush=True)
+    try:
+        _proc = run(cmd, stdout=PIPE, stderr=STDOUT, check=True)
+    except CalledProcessError as e:
+        print()
+        cmd = " ".join(e.cmd)
+        print(f"Oops! Command '{cmd}' failed.")
+        print(f"Got return code {e.returncode}.")
+        print("Here is the command output:")
+        print(e.output.decode(), end="", flush=True)
+        sys.exit(e.returncode)
+    print("Done.", flush=True)
+
+
+python = "python3"
+venv_bin = ".venv/Scripts" if on_windows else ".venv/bin"
+venv_python = f"{venv_bin}/python3"
+pre_commit = f"{venv_bin}/pre-commit"
+
+# Clone Tree-sitter grammar which is a Git submodule of the project
+# See https://git-scm.com/book/en/v2/Git-Tools-Submodules
+run_cmd(
+    "Clone vendored C Tree-sitter grammar",
+    ["git", "submodule", "update", "--init", "--recursive"],
+)
+
+# Create a virtual environment if it doesn't exist
+if not (PROJECT_ROOT / ".venv").is_dir():
+    run_cmd("Create a virtual environment in .venv", [python, "-m", "venv", ".venv"])
+
+# Upgrade venv's pip
+run_cmd("Upgrade pip", [venv_python, "-m", "pip", "install", "--upgrade", "pip"])
+
+# Install dev dependencies
+run_cmd(
+    "Install dependencies",
+    [venv_python, "-m", "pip", "install", "-r", "requirements.txt"],
+)
+
+# Install pre-commit hooks
+run_cmd("Install pre-commit hooks", [pre_commit, "install"])
+
+print("Setup successfull!")