Add tests, update readme

Author: tomasr8

README.md

@@ -33,7 +33,13 @@ Get it via pip:
 pip install python-jsx
 ```
 
-## Minimal example
+## Minimal example (using the `coding` directive)
+
+> [!TIP]
+> There are more examples available in the [examples folder](examples).
+
+There are two supported ways to seamlessly integrate JSX into your codebase.
+One is by registering a custom codec shown here and the other by using a custom import hook shown [below](#minimal-example-using-an-import-hook).
 
 ```python
 # hello.py
@@ -58,9 +64,6 @@ $ python main.py
 <h1>Hello, word!</h1>
 ```
 
-> [!TIP]
-> There are more examples available in the [examples folder](examples).
-
 Each file containing JSX must contain two things:
 
 - `# coding: jsx` directive - This tells Python to let our library parse the
@@ -72,6 +75,42 @@ To run a file containing JSX, the `jsx` codec must be registered first which can
 be done with `from pyjsx import auto_setup`. This must occur before importing
 any other file containing JSX.
 
+## Minimal example (using an import hook)
+
+> [!TIP]
+> There are more examples available in the [examples folder](examples).
+
+```python
+# hello.px
+from pyjsx import jsx
+
+def hello():
+    print(<h1>Hello, world!</h1>)
+```
+
+```python
+# main.py
+from pyjsx import auto_setup
+
+from hello import hello
+
+hello()
+```
+
+```sh
+$ python main.py
+<h1>Hello, word!</h1>
+```
+
+Each file containing JSX must contain two things:
+
+- The file extension must be `.px`
+- `from pyjsx import jsx` import. PyJSX transpiles JSX into `jsx(...)` calls so
+  it must be in scope.
+
+To be able to import `.px`, the import hook must be registered first which can
+be done with `from pyjsx import auto_setup` (same as for the codec version). This must occur before importing any other file containing JSX.
+
 ## Supported grammar
 
 The full [JSX grammar](https://facebook.github.io/jsx/) is supported.

pyjsx/import_hook.py

@@ -61,4 +61,10 @@ def _spec_from_path(self, fullname: str, path: str) -> ModuleSpec | None:
 
 
 def register_import_hook() -> None:
+    """Register import hook for .px files."""
     sys.meta_path.append(PyJSXFinder())
+
+
+def unregister_import_hook() -> None:
+    """Unregister import hook for .px files."""
+    sys.meta_path = [finder for finder in sys.meta_path if not isinstance(finder, PyJSXFinder)]

tests/data/examples-custom.txt tests/data/examples-custom_components.txt

@@ -13,15 +13,18 @@ def run_example(name: str):
 
 
 @pytest.mark.parametrize(
-    "example",
+    ("example", "loader"),
     [
-        "table",
-        "props",
-        "custom",
+        ("table", "codec"),
+        ("table", "import_hook"),
+        ("props", "codec"),
+        ("props", "import_hook"),
+        ("custom_components", "codec"),
+        ("custom_components", "import_hook"),
     ],
 )
-def test_example(request, snapshot, example):
+def test_example(snapshot, example, loader):
     snapshot.snapshot_dir = Path(__file__).parent / "data"
     snapshot.assert_match(
-        run_example(example), f"examples-{request.node.callspec.id}.txt"
+        run_example(f"{example}_{loader}"), f"examples-{example}.txt"
     )

tests/test_examples.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+
+import pytest
+
+from pyjsx.import_hook import PyJSXFinder, register_import_hook, unregister_import_hook
+
+
+@pytest.fixture
+def import_hook():
+    register_import_hook()
+    yield
+    unregister_import_hook()
+
+
+def test_finder():
+    finder = PyJSXFinder()
+    path = str(Path(__file__).parent / "test_module")
+    spec = finder.find_spec("main", [path])
+    assert spec is not None
+    assert spec.name == "main"
+
+
+@pytest.mark.usefixtures("import_hook")
+def test_import():
+    from .test_module import main
+
+    assert str(main.hello()) == """\
+<h1>
+    Hello, World!
+</h1>"""

tests/test_import_hook.py

@@ -0,0 +1,4 @@
+from pyjsx import jsx
+
+def hello():
+    return <h1>Hello, World!</h1>