refactor: exclude underscored files from autodiscovery (#888)

docs/concepts/fundamentals/autodiscovery.md

@@ -15,7 +15,7 @@ class Calendar(Component):
     ...
 ```
 
-But for the component to be registered, the code needs to be executed - the file needs to be imported as a module.
+But for the component to be registered, the code needs to be executed - and for that, the file needs to be imported as a module.
 
 One way to do that is by importing all your components in `apps.py`:
 
@@ -43,8 +43,9 @@ hook of the `apps.py` file.
 If you are using autodiscovery, keep a few points in mind:
 
 - Avoid defining any logic on the module-level inside the `components` dir, that you would not want to run anyway.
-- Components inside the auto-imported files still need to be registered with [`@register`](django_components.component_registry.register)p
+- Components inside the auto-imported files still need to be registered with [`@register`](django_components.component_registry.register)
 - Auto-imported component files must be valid Python modules, they must use suffix `.py`, and module name should follow [PEP-8](https://peps.python.org/pep-0008/#package-and-module-names).
+- Subdirectories and files starting with an underscore `_` (except `__init__.py`) are ignored.
 
 Autodiscovery can be disabled in the [settings](django_components.app_settings.ComponentsSettings.autodiscovery).
 

src/django_components/autodiscovery.py

@@ -17,6 +17,8 @@ def autodiscover(
 
     See [Autodiscovery](../../concepts/fundamentals/autodiscovery).
 
+    NOTE: Subdirectories and files starting with an underscore `_` (except for `__init__.py` are ignored.
+
     Args:
         map_module (Callable[[str], str], optional): Map the module paths with `map_module` function.\
         This serves as an escape hatch for when you need to use this function in tests.

src/django_components/util/loader.py

@@ -126,6 +126,8 @@ def get_component_files(suffix: Optional[str] = None) -> List[ComponentFileEntry
 
     Requires `BASE_DIR` setting to be set.
 
+    Subdirectories and files starting with an underscore `_` (except `__init__.py`) are ignored.
+
     Args:
         suffix (Optional[str], optional): The suffix to search for. E.g. `.py`, `.js`, `.css`.\
             Defaults to `None`, which will search for all files.
@@ -232,8 +234,17 @@ def _search_dirs(dirs: List[Path], search_glob: str) -> List[Path]:
     """
     matched_files: List[Path] = []
     for directory in dirs:
-        for path in glob.iglob(str(Path(directory) / search_glob), recursive=True):
-            matched_files.append(Path(path))
+        for path_str in glob.iglob(str(Path(directory) / search_glob), recursive=True):
+            path = Path(path_str)
+            # Skip any subdirectory or file (under the top-level directory) that starts with an underscore
+            rel_dir_parts = list(path.relative_to(directory).parts)
+            name_part = rel_dir_parts.pop()
+            if any(part.startswith("_") for part in rel_dir_parts):
+                continue
+            if name_part.startswith("_") and name_part != "__init__.py":
+                continue
+
+            matched_files.append(path)
 
     return matched_files
 

tests/components/_ignored_dir/ignored_file.py

@@ -0,0 +1,2 @@
+# This file checks that the autodiscovery does not load files from
+# subdirs that start with an underscore.

tests/components/_ignored_file.py

@@ -0,0 +1 @@
+# This file checks that the autodiscovery does not load files that start with an underscore.