django-components 0.84__tar.gz → 0.85__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. {django_components-0.84/src/django_components.egg-info → django_components-0.85}/PKG-INFO +171 -42
  2. {django_components-0.84 → django_components-0.85}/README.md +170 -41
  3. {django_components-0.84 → django_components-0.85}/pyproject.toml +1 -1
  4. django_components-0.85/src/django_components/__init__.py +7 -0
  5. django_components-0.85/src/django_components/apps.py +17 -0
  6. django_components-0.85/src/django_components/autodiscover.py +115 -0
  7. {django_components-0.84 → django_components-0.85}/src/django_components/component_media.py +2 -2
  8. django_components-0.85/src/django_components/template_loader.py +61 -0
  9. {django_components-0.84 → django_components-0.85}/src/django_components/template_parser.py +3 -1
  10. django_components-0.85/src/django_components/utils.py +21 -0
  11. {django_components-0.84 → django_components-0.85/src/django_components.egg-info}/PKG-INFO +171 -42
  12. {django_components-0.84 → django_components-0.85}/src/django_components.egg-info/SOURCES.txt +2 -0
  13. {django_components-0.84 → django_components-0.85}/tests/test_attributes.py +2 -3
  14. django_components-0.85/tests/test_autodiscover.py +164 -0
  15. {django_components-0.84 → django_components-0.85}/tests/test_command_startcomponent.py +10 -10
  16. {django_components-0.84 → django_components-0.85}/tests/test_component.py +9 -11
  17. {django_components-0.84 → django_components-0.85}/tests/test_component_as_view.py +4 -5
  18. {django_components-0.84 → django_components-0.85}/tests/test_component_media.py +11 -13
  19. {django_components-0.84 → django_components-0.85}/tests/test_context.py +29 -35
  20. {django_components-0.84 → django_components-0.85}/tests/test_dependency_rendering.py +3 -1
  21. {django_components-0.84 → django_components-0.85}/tests/test_registry.py +3 -1
  22. django_components-0.85/tests/test_settings.py +19 -0
  23. django_components-0.85/tests/test_template_loader.py +76 -0
  24. {django_components-0.84 → django_components-0.85}/tests/test_template_parser.py +34 -6
  25. {django_components-0.84 → django_components-0.85}/tests/test_templatetags.py +11 -16
  26. {django_components-0.84 → django_components-0.85}/tests/test_templatetags_component.py +10 -15
  27. {django_components-0.84 → django_components-0.85}/tests/test_templatetags_provide.py +4 -5
  28. {django_components-0.84 → django_components-0.85}/tests/test_templatetags_slot_fill.py +17 -23
  29. {django_components-0.84 → django_components-0.85}/tests/test_templatetags_templating.py +20 -27
  30. {django_components-0.84 → django_components-0.85}/tests/testutils.py +16 -12
  31. django_components-0.84/src/django_components/__init__.py +0 -76
  32. django_components-0.84/src/django_components/apps.py +0 -8
  33. django_components-0.84/src/django_components/template_loader.py +0 -95
  34. django_components-0.84/src/django_components/utils.py +0 -58
  35. django_components-0.84/tests/test_autodiscover.py +0 -186
  36. django_components-0.84/tests/test_settings.py +0 -35
  37. {django_components-0.84 → django_components-0.85}/LICENSE +0 -0
  38. {django_components-0.84 → django_components-0.85}/setup.cfg +0 -0
  39. {django_components-0.84 → django_components-0.85}/src/django_components/app_settings.py +0 -0
  40. {django_components-0.84 → django_components-0.85}/src/django_components/attributes.py +0 -0
  41. {django_components-0.84 → django_components-0.85}/src/django_components/component.py +0 -0
  42. {django_components-0.84 → django_components-0.85}/src/django_components/component_registry.py +0 -0
  43. {django_components-0.84 → django_components-0.85}/src/django_components/context.py +0 -0
  44. {django_components-0.84 → django_components-0.85}/src/django_components/expression.py +0 -0
  45. {django_components-0.84 → django_components-0.85}/src/django_components/logger.py +0 -0
  46. {django_components-0.84 → django_components-0.85}/src/django_components/management/__init__.py +0 -0
  47. {django_components-0.84 → django_components-0.85}/src/django_components/management/commands/__init__.py +0 -0
  48. {django_components-0.84 → django_components-0.85}/src/django_components/management/commands/startcomponent.py +0 -0
  49. {django_components-0.84 → django_components-0.85}/src/django_components/management/commands/upgradecomponent.py +0 -0
  50. {django_components-0.84 → django_components-0.85}/src/django_components/middleware.py +0 -0
  51. {django_components-0.84 → django_components-0.85}/src/django_components/node.py +0 -0
  52. {django_components-0.84 → django_components-0.85}/src/django_components/provide.py +0 -0
  53. {django_components-0.84 → django_components-0.85}/src/django_components/py.typed +0 -0
  54. {django_components-0.84 → django_components-0.85}/src/django_components/safer_staticfiles/__init__.py +0 -0
  55. {django_components-0.84 → django_components-0.85}/src/django_components/safer_staticfiles/apps.py +0 -0
  56. {django_components-0.84 → django_components-0.85}/src/django_components/slots.py +0 -0
  57. {django_components-0.84 → django_components-0.85}/src/django_components/templatetags/__init__.py +0 -0
  58. {django_components-0.84 → django_components-0.85}/src/django_components/templatetags/component_tags.py +0 -0
  59. {django_components-0.84 → django_components-0.85}/src/django_components/types.py +0 -0
  60. {django_components-0.84 → django_components-0.85}/src/django_components.egg-info/dependency_links.txt +0 -0
  61. {django_components-0.84 → django_components-0.85}/src/django_components.egg-info/requires.txt +0 -0
  62. {django_components-0.84 → django_components-0.85}/src/django_components.egg-info/top_level.txt +0 -0
  63. {django_components-0.84 → django_components-0.85}/tests/test_safer_staticfiles.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: django_components
3
- Version: 0.84
3
+ Version: 0.85
4
4
  Summary: A way to create simple reusable template components in Django.
5
5
  Author-email: Emil Stenström <emil@emilstenstrom.se>
6
6
  License: MIT
@@ -70,6 +70,14 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
70
70
 
71
71
  ## Release notes
72
72
 
73
+ 🚨📢 **Version 0.85** Autodiscovery module resolution changed. Following undocumented behavior was removed:
74
+ - Previously, autodiscovery also imported any `[app]/components.py` files, and used `SETTINGS_MODULE` to search for component dirs.
75
+ - To migrate from:
76
+ - `[app]/components.py` - Define each module in `COMPONENTS.libraries` setting,
77
+ or import each module inside the `AppConfig.ready()` hook in respective `apps.py` files.
78
+ - `SETTINGS_MODULE` - Define component dirs using `STATICFILES_DIRS`
79
+ - Previously, autodiscovery handled relative files in `STATICFILES_DIRS`. To align with Django, `STATICFILES_DIRS` now must be full paths ([Django docs](https://docs.djangoproject.com/en/5.0/ref/settings/#std-setting-STATICFILES_DIRS)).
80
+
73
81
  🚨📢 **Version 0.81** Aligned the `render_to_response` method with the (now public) `render` method of `Component` class. Moreover, slots passed to these can now be rendered also as functions.
74
82
 
75
83
  - BREAKING CHANGE: The order of arguments to `render_to_response` has changed.
@@ -159,51 +167,62 @@ For a step-by-step guide on deploying production server with static files,
159
167
 
160
168
  ## Installation
161
169
 
162
- Install the app into your environment:
170
+ 1. Install the app into your environment:
163
171
 
164
- > `pip install django_components`
172
+ > `pip install django_components`
165
173
 
166
- Then add the app into INSTALLED_APPS in settings.py
174
+ 2. Then add the app into `INSTALLED_APPS` in settings.py
167
175
 
168
- ```python
169
- INSTALLED_APPS = [
170
- ...,
171
- 'django_components',
172
- ]
173
- ```
176
+ ```python
177
+ INSTALLED_APPS = [
178
+ ...,
179
+ 'django_components',
180
+ ]
181
+ ```
174
182
 
175
- Modify `TEMPLATES` section of settings.py as follows:
176
- - *Remove `'APP_DIRS': True,`*
177
- - add `loaders` to `OPTIONS` list and set it to following value:
183
+ 3. Ensure that `BASE_DIR` setting is defined in settings.py:
178
184
 
179
- ```python
180
- TEMPLATES = [
181
- {
182
- ...,
183
- 'OPTIONS': {
184
- 'context_processors': [
185
- ...
186
- ],
187
- 'loaders':[(
188
- 'django.template.loaders.cached.Loader', [
189
- 'django.template.loaders.filesystem.Loader',
190
- 'django.template.loaders.app_directories.Loader',
191
- 'django_components.template_loader.Loader',
192
- ]
193
- )],
194
- },
195
- },
196
- ]
197
- ```
185
+ ```py
186
+ BASE_DIR = Path(__file__).resolve().parent.parent
187
+ ```
198
188
 
199
- Modify STATICFILES_DIRS (or add it if you don't have it) so django can find your static JS and CSS files:
189
+ 4. Modify `TEMPLATES` section of settings.py as follows:
190
+ - *Remove `'APP_DIRS': True,`*
191
+ - Add `loaders` to `OPTIONS` list and set it to following value:
192
+
193
+ ```python
194
+ TEMPLATES = [
195
+ {
196
+ ...,
197
+ 'OPTIONS': {
198
+ 'context_processors': [
199
+ ...
200
+ ],
201
+ 'loaders':[(
202
+ 'django.template.loaders.cached.Loader', [
203
+ 'django.template.loaders.filesystem.Loader',
204
+ 'django.template.loaders.app_directories.Loader',
205
+ 'django_components.template_loader.Loader',
206
+ ]
207
+ )],
208
+ },
209
+ },
210
+ ]
211
+ ```
200
212
 
201
- ```python
202
- STATICFILES_DIRS = [
203
- ...,
204
- os.path.join(BASE_DIR, "components"),
205
- ]
206
- ```
213
+ 5. Modify `STATICFILES_DIRS` (or add it if you don't have it) so django can find your static JS and CSS files:
214
+
215
+ ```python
216
+ STATICFILES_DIRS = [
217
+ ...,
218
+ os.path.join(BASE_DIR, "components"),
219
+ ]
220
+ ```
221
+
222
+ If `STATICFILES_DIRS` is omitted or empty, django-components will by default look for
223
+ `{BASE_DIR}/components`
224
+
225
+ NOTE: The paths in `STATICFILES_DIRS` must be full paths. [See Django docs](https://docs.djangoproject.com/en/5.0/ref/settings/#staticfiles-dirs).
207
226
 
208
227
  ### Optional
209
228
 
@@ -359,7 +378,49 @@ class Calendar(component.Component):
359
378
 
360
379
  This makes it easy to create small components without having to create a separate template, CSS, and JS file.
361
380
 
362
- Note that the `t.django_html`, `t.css`, and `t.js` types are used to specify the type of the template, CSS, and JS files, respectively. This is not necessary, but if you're using VSCode with the [Python Inline Source Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=samwillis.python-inline-source) extension, it will give you syntax highlighting for the template, CSS, and JS.
381
+ ### Syntax highlight and code assistance
382
+
383
+ #### VSCode
384
+
385
+ Note, in the above example, that the `t.django_html`, `t.css`, and `t.js` types are used to specify the type of the template, CSS, and JS files, respectively. This is not necessary, but if you're using VSCode with the [Python Inline Source Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=samwillis.python-inline-source) extension, it will give you syntax highlighting for the template, CSS, and JS.
386
+
387
+ #### Pycharm (or other Jetbrains IDEs)
388
+
389
+ If you're a Pycharm user (or any other editor from Jetbrains), you can have coding assistance as well:
390
+
391
+ ```python
392
+ from django_components import component
393
+
394
+ @component.register("calendar")
395
+ class Calendar(component.Component):
396
+ def get_context_data(self, date):
397
+ return {
398
+ "date": date,
399
+ }
400
+
401
+ # language=HTML
402
+ template= """
403
+ <div class="calendar-component">Today's date is <span>{{ date }}</span></div>
404
+ """
405
+
406
+ # language=CSS
407
+ css = """
408
+ .calendar-component { width: 200px; background: pink; }
409
+ .calendar-component span { font-weight: bold; }
410
+ """
411
+
412
+ # language=JS
413
+ js = """
414
+ (function(){
415
+ if (document.querySelector(".calendar-component")) {
416
+ document.querySelector(".calendar-component").onclick = function(){ alert("Clicked calendar!"); };
417
+ }
418
+ })()
419
+ """
420
+ ```
421
+
422
+ You don't need to use `t.django_html`, `t.css`, `t.js` and `from django_components import types as t` since Pycharm uses [language injections](https://www.jetbrains.com/help/pycharm/using-language-injections.html).
423
+ You only need to write the comments `# language=<lang>` above the variables.
363
424
 
364
425
  ## Use components in templates
365
426
 
@@ -605,7 +666,37 @@ If you're planning on passing an HTML string, check Django's use of [`format_htm
605
666
 
606
667
  ## Autodiscovery
607
668
 
608
- By default, the Python files in the `components` app are auto-imported in order to auto-register the components (e.g. `components/button/button.py`).
669
+ Every component that you want to use in the template with the `{% component %}` tag needs to be registered with the ComponentRegistry. Normally, we use the `@component.register` decorator for that:
670
+
671
+ ```py
672
+ from django_components import component
673
+
674
+ @component.register("calendar")
675
+ class Calendar(component.Component):
676
+ ...
677
+ ```
678
+
679
+ But for the component to be registered, the code needs to be executed - the file needs to be imported as a module.
680
+
681
+ One way to do that is by importing all your components in `apps.py`:
682
+
683
+ ```py
684
+ from django.apps import AppConfig
685
+
686
+ class MyAppConfig(AppConfig):
687
+ name = "my_app"
688
+
689
+ def ready(self) -> None:
690
+ from components.card.card import Card
691
+ from components.list.list import List
692
+ from components.menu.menu import Menu
693
+ from components.button.button import Button
694
+ ...
695
+ ```
696
+
697
+ However, there's a simpler way!
698
+
699
+ By default, the Python files in the `STATICFILES_DIRS` directories are auto-imported in order to auto-register the components.
609
700
 
610
701
  Autodiscovery occurs when Django is loaded, during the `ready` hook of the `apps.py` file.
611
702
 
@@ -615,7 +706,17 @@ If you are using autodiscovery, keep a few points in mind:
615
706
  - Components inside the auto-imported files still need to be registered with `@component.register()`
616
707
  - 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).
617
708
 
618
- Autodiscovery can be disabled via in the [settings](#disable-autodiscovery).
709
+ Autodiscovery can be disabled in the [settings](#disable-autodiscovery).
710
+
711
+ ### Manually trigger autodiscovery
712
+
713
+ Autodiscovery can be also triggered manually as a function call. This is useful if you want to run autodiscovery at a custom point of the lifecycle:
714
+
715
+ ```py
716
+ from django_components import autodiscover
717
+
718
+ autodiscover()
719
+ ```
619
720
 
620
721
  ## Using slots in templates
621
722
 
@@ -1941,6 +2042,34 @@ COMPONENTS = {
1941
2042
  }
1942
2043
  ```
1943
2044
 
2045
+ Where `mysite/components/forms.py` may look like this:
2046
+
2047
+ ```py
2048
+ @component.register("form_simple")
2049
+ class FormSimple(component.Component):
2050
+ template = """
2051
+ <form>
2052
+ ...
2053
+ </form>
2054
+ """
2055
+
2056
+ @component.register("form_other")
2057
+ class FormOther(component.Component):
2058
+ template = """
2059
+ <form>
2060
+ ...
2061
+ </form>
2062
+ """
2063
+ ```
2064
+
2065
+ In the rare cases when you need to manually trigger the import of libraries, you can use the `import_libraries` function:
2066
+
2067
+ ```py
2068
+ from django_components import import_libraries
2069
+
2070
+ import_libraries()
2071
+ ```
2072
+
1944
2073
  ### Disable autodiscovery
1945
2074
 
1946
2075
  If you specify all the component locations with the setting above and have a lot of apps, you can (very) slightly speed things up by disabling autodiscovery.
@@ -46,6 +46,14 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
46
46
 
47
47
  ## Release notes
48
48
 
49
+ 🚨📢 **Version 0.85** Autodiscovery module resolution changed. Following undocumented behavior was removed:
50
+ - Previously, autodiscovery also imported any `[app]/components.py` files, and used `SETTINGS_MODULE` to search for component dirs.
51
+ - To migrate from:
52
+ - `[app]/components.py` - Define each module in `COMPONENTS.libraries` setting,
53
+ or import each module inside the `AppConfig.ready()` hook in respective `apps.py` files.
54
+ - `SETTINGS_MODULE` - Define component dirs using `STATICFILES_DIRS`
55
+ - Previously, autodiscovery handled relative files in `STATICFILES_DIRS`. To align with Django, `STATICFILES_DIRS` now must be full paths ([Django docs](https://docs.djangoproject.com/en/5.0/ref/settings/#std-setting-STATICFILES_DIRS)).
56
+
49
57
  🚨📢 **Version 0.81** Aligned the `render_to_response` method with the (now public) `render` method of `Component` class. Moreover, slots passed to these can now be rendered also as functions.
50
58
 
51
59
  - BREAKING CHANGE: The order of arguments to `render_to_response` has changed.
@@ -135,51 +143,62 @@ For a step-by-step guide on deploying production server with static files,
135
143
 
136
144
  ## Installation
137
145
 
138
- Install the app into your environment:
146
+ 1. Install the app into your environment:
139
147
 
140
- > `pip install django_components`
148
+ > `pip install django_components`
141
149
 
142
- Then add the app into INSTALLED_APPS in settings.py
150
+ 2. Then add the app into `INSTALLED_APPS` in settings.py
143
151
 
144
- ```python
145
- INSTALLED_APPS = [
146
- ...,
147
- 'django_components',
148
- ]
149
- ```
152
+ ```python
153
+ INSTALLED_APPS = [
154
+ ...,
155
+ 'django_components',
156
+ ]
157
+ ```
150
158
 
151
- Modify `TEMPLATES` section of settings.py as follows:
152
- - *Remove `'APP_DIRS': True,`*
153
- - add `loaders` to `OPTIONS` list and set it to following value:
159
+ 3. Ensure that `BASE_DIR` setting is defined in settings.py:
154
160
 
155
- ```python
156
- TEMPLATES = [
157
- {
158
- ...,
159
- 'OPTIONS': {
160
- 'context_processors': [
161
- ...
162
- ],
163
- 'loaders':[(
164
- 'django.template.loaders.cached.Loader', [
165
- 'django.template.loaders.filesystem.Loader',
166
- 'django.template.loaders.app_directories.Loader',
167
- 'django_components.template_loader.Loader',
168
- ]
169
- )],
170
- },
171
- },
172
- ]
173
- ```
161
+ ```py
162
+ BASE_DIR = Path(__file__).resolve().parent.parent
163
+ ```
174
164
 
175
- Modify STATICFILES_DIRS (or add it if you don't have it) so django can find your static JS and CSS files:
165
+ 4. Modify `TEMPLATES` section of settings.py as follows:
166
+ - *Remove `'APP_DIRS': True,`*
167
+ - Add `loaders` to `OPTIONS` list and set it to following value:
168
+
169
+ ```python
170
+ TEMPLATES = [
171
+ {
172
+ ...,
173
+ 'OPTIONS': {
174
+ 'context_processors': [
175
+ ...
176
+ ],
177
+ 'loaders':[(
178
+ 'django.template.loaders.cached.Loader', [
179
+ 'django.template.loaders.filesystem.Loader',
180
+ 'django.template.loaders.app_directories.Loader',
181
+ 'django_components.template_loader.Loader',
182
+ ]
183
+ )],
184
+ },
185
+ },
186
+ ]
187
+ ```
176
188
 
177
- ```python
178
- STATICFILES_DIRS = [
179
- ...,
180
- os.path.join(BASE_DIR, "components"),
181
- ]
182
- ```
189
+ 5. Modify `STATICFILES_DIRS` (or add it if you don't have it) so django can find your static JS and CSS files:
190
+
191
+ ```python
192
+ STATICFILES_DIRS = [
193
+ ...,
194
+ os.path.join(BASE_DIR, "components"),
195
+ ]
196
+ ```
197
+
198
+ If `STATICFILES_DIRS` is omitted or empty, django-components will by default look for
199
+ `{BASE_DIR}/components`
200
+
201
+ NOTE: The paths in `STATICFILES_DIRS` must be full paths. [See Django docs](https://docs.djangoproject.com/en/5.0/ref/settings/#staticfiles-dirs).
183
202
 
184
203
  ### Optional
185
204
 
@@ -335,7 +354,49 @@ class Calendar(component.Component):
335
354
 
336
355
  This makes it easy to create small components without having to create a separate template, CSS, and JS file.
337
356
 
338
- Note that the `t.django_html`, `t.css`, and `t.js` types are used to specify the type of the template, CSS, and JS files, respectively. This is not necessary, but if you're using VSCode with the [Python Inline Source Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=samwillis.python-inline-source) extension, it will give you syntax highlighting for the template, CSS, and JS.
357
+ ### Syntax highlight and code assistance
358
+
359
+ #### VSCode
360
+
361
+ Note, in the above example, that the `t.django_html`, `t.css`, and `t.js` types are used to specify the type of the template, CSS, and JS files, respectively. This is not necessary, but if you're using VSCode with the [Python Inline Source Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=samwillis.python-inline-source) extension, it will give you syntax highlighting for the template, CSS, and JS.
362
+
363
+ #### Pycharm (or other Jetbrains IDEs)
364
+
365
+ If you're a Pycharm user (or any other editor from Jetbrains), you can have coding assistance as well:
366
+
367
+ ```python
368
+ from django_components import component
369
+
370
+ @component.register("calendar")
371
+ class Calendar(component.Component):
372
+ def get_context_data(self, date):
373
+ return {
374
+ "date": date,
375
+ }
376
+
377
+ # language=HTML
378
+ template= """
379
+ <div class="calendar-component">Today's date is <span>{{ date }}</span></div>
380
+ """
381
+
382
+ # language=CSS
383
+ css = """
384
+ .calendar-component { width: 200px; background: pink; }
385
+ .calendar-component span { font-weight: bold; }
386
+ """
387
+
388
+ # language=JS
389
+ js = """
390
+ (function(){
391
+ if (document.querySelector(".calendar-component")) {
392
+ document.querySelector(".calendar-component").onclick = function(){ alert("Clicked calendar!"); };
393
+ }
394
+ })()
395
+ """
396
+ ```
397
+
398
+ You don't need to use `t.django_html`, `t.css`, `t.js` and `from django_components import types as t` since Pycharm uses [language injections](https://www.jetbrains.com/help/pycharm/using-language-injections.html).
399
+ You only need to write the comments `# language=<lang>` above the variables.
339
400
 
340
401
  ## Use components in templates
341
402
 
@@ -581,7 +642,37 @@ If you're planning on passing an HTML string, check Django's use of [`format_htm
581
642
 
582
643
  ## Autodiscovery
583
644
 
584
- By default, the Python files in the `components` app are auto-imported in order to auto-register the components (e.g. `components/button/button.py`).
645
+ Every component that you want to use in the template with the `{% component %}` tag needs to be registered with the ComponentRegistry. Normally, we use the `@component.register` decorator for that:
646
+
647
+ ```py
648
+ from django_components import component
649
+
650
+ @component.register("calendar")
651
+ class Calendar(component.Component):
652
+ ...
653
+ ```
654
+
655
+ But for the component to be registered, the code needs to be executed - the file needs to be imported as a module.
656
+
657
+ One way to do that is by importing all your components in `apps.py`:
658
+
659
+ ```py
660
+ from django.apps import AppConfig
661
+
662
+ class MyAppConfig(AppConfig):
663
+ name = "my_app"
664
+
665
+ def ready(self) -> None:
666
+ from components.card.card import Card
667
+ from components.list.list import List
668
+ from components.menu.menu import Menu
669
+ from components.button.button import Button
670
+ ...
671
+ ```
672
+
673
+ However, there's a simpler way!
674
+
675
+ By default, the Python files in the `STATICFILES_DIRS` directories are auto-imported in order to auto-register the components.
585
676
 
586
677
  Autodiscovery occurs when Django is loaded, during the `ready` hook of the `apps.py` file.
587
678
 
@@ -591,7 +682,17 @@ If you are using autodiscovery, keep a few points in mind:
591
682
  - Components inside the auto-imported files still need to be registered with `@component.register()`
592
683
  - 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).
593
684
 
594
- Autodiscovery can be disabled via in the [settings](#disable-autodiscovery).
685
+ Autodiscovery can be disabled in the [settings](#disable-autodiscovery).
686
+
687
+ ### Manually trigger autodiscovery
688
+
689
+ Autodiscovery can be also triggered manually as a function call. This is useful if you want to run autodiscovery at a custom point of the lifecycle:
690
+
691
+ ```py
692
+ from django_components import autodiscover
693
+
694
+ autodiscover()
695
+ ```
595
696
 
596
697
  ## Using slots in templates
597
698
 
@@ -1917,6 +2018,34 @@ COMPONENTS = {
1917
2018
  }
1918
2019
  ```
1919
2020
 
2021
+ Where `mysite/components/forms.py` may look like this:
2022
+
2023
+ ```py
2024
+ @component.register("form_simple")
2025
+ class FormSimple(component.Component):
2026
+ template = """
2027
+ <form>
2028
+ ...
2029
+ </form>
2030
+ """
2031
+
2032
+ @component.register("form_other")
2033
+ class FormOther(component.Component):
2034
+ template = """
2035
+ <form>
2036
+ ...
2037
+ </form>
2038
+ """
2039
+ ```
2040
+
2041
+ In the rare cases when you need to manually trigger the import of libraries, you can use the `import_libraries` function:
2042
+
2043
+ ```py
2044
+ from django_components import import_libraries
2045
+
2046
+ import_libraries()
2047
+ ```
2048
+
1920
2049
  ### Disable autodiscovery
1921
2050
 
1922
2051
  If you specify all the component locations with the setting above and have a lot of apps, you can (very) slightly speed things up by disabling autodiscovery.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "django_components"
7
- version = "0.84"
7
+ version = "0.85"
8
8
  requires-python = ">=3.8, <4.0"
9
9
  description = "A way to create simple reusable template components in Django."
10
10
  keywords = ["django", "components", "css", "js", "html"]
@@ -0,0 +1,7 @@
1
+ import django
2
+
3
+ from django_components.autodiscover import autodiscover as autodiscover # NOQA
4
+ from django_components.autodiscover import import_libraries as import_libraries # NOQA
5
+
6
+ if django.VERSION < (3, 2):
7
+ default_app_config = "django_components.apps.ComponentsConfig"
@@ -0,0 +1,17 @@
1
+ from django.apps import AppConfig
2
+
3
+
4
+ class ComponentsConfig(AppConfig):
5
+ name = "django_components"
6
+
7
+ # This is the code that gets run when user adds django_components
8
+ # to Django's INSTALLED_APPS
9
+ def ready(self) -> None:
10
+ from django_components.app_settings import app_settings
11
+ from django_components.autodiscover import autodiscover, import_libraries
12
+
13
+ # Import modules set in `COMPONENTS.libraries` setting
14
+ import_libraries()
15
+
16
+ if app_settings.AUTODISCOVER:
17
+ autodiscover()
@@ -0,0 +1,115 @@
1
+ import glob
2
+ import importlib
3
+ import os
4
+ from pathlib import Path
5
+ from typing import Callable, List, Optional, Union
6
+
7
+ from django.conf import settings
8
+ from django.template.engine import Engine
9
+
10
+ from django_components.logger import logger
11
+ from django_components.template_loader import Loader
12
+
13
+
14
+ def autodiscover(
15
+ map_module: Optional[Callable[[str], str]] = None,
16
+ ) -> List[str]:
17
+ """
18
+ Search for component files and import them. Returns a list of module
19
+ paths of imported files.
20
+
21
+ Autodiscover searches in the locations as defined by `Loader.get_dirs`.
22
+
23
+ You can map the module paths with `map_module` function. This serves
24
+ as an escape hatch for when you need to use this function in tests.
25
+ """
26
+ dirs = get_dirs()
27
+ component_filepaths = search_dirs(dirs, "**/*.py")
28
+ logger.debug(f"Autodiscover found {len(component_filepaths)} files in component directories.")
29
+
30
+ modules = [_filepath_to_python_module(filepath) for filepath in component_filepaths]
31
+ return _import_modules(modules, map_module)
32
+
33
+
34
+ def import_libraries(
35
+ map_module: Optional[Callable[[str], str]] = None,
36
+ ) -> List[str]:
37
+ """
38
+ Import modules set in `COMPONENTS.libraries` setting.
39
+
40
+ You can map the module paths with `map_module` function. This serves
41
+ as an escape hatch for when you need to use this function in tests.
42
+ """
43
+ from django_components.app_settings import app_settings
44
+
45
+ return _import_modules(app_settings.LIBRARIES, map_module)
46
+
47
+
48
+ def _import_modules(
49
+ modules: List[str],
50
+ map_module: Optional[Callable[[str], str]] = None,
51
+ ) -> List[str]:
52
+ imported_modules: List[str] = []
53
+ for module_name in modules:
54
+ if map_module:
55
+ module_name = map_module(module_name)
56
+
57
+ # This imports the file and runs it's code. So if the file defines any
58
+ # django components, they will be registered.
59
+ logger.debug(f'Importing module "{module_name}"')
60
+ importlib.import_module(module_name)
61
+ imported_modules.append(module_name)
62
+ return imported_modules
63
+
64
+
65
+ def _filepath_to_python_module(file_path: Union[Path, str]) -> str:
66
+ """
67
+ Derive python import path from the filesystem path.
68
+
69
+ Example:
70
+ - If project root is `/path/to/project`
71
+ - And file_path is `/path/to/project/app/components/mycomp.py`
72
+ - Then the path relative to project root is `app/components/mycomp.py`
73
+ - Which we then turn into python import path `app.components.mycomp`
74
+ """
75
+ if hasattr(settings, "BASE_DIR") and settings.BASE_DIR:
76
+ project_root = str(settings.BASE_DIR)
77
+ else:
78
+ # Fallback for getting the root dir, see https://stackoverflow.com/a/16413955/9788634
79
+ project_root = os.path.abspath(os.path.dirname(__name__))
80
+
81
+ rel_path = os.path.relpath(file_path, start=project_root)
82
+ rel_path_without_suffix = str(Path(rel_path).with_suffix(""))
83
+
84
+ # NOTE: `Path` normalizes paths to use `/` as separator, while `os.path`
85
+ # uses `os.path.sep`.
86
+ sep = os.path.sep if os.path.sep in rel_path_without_suffix else "/"
87
+ module_name = rel_path_without_suffix.replace(sep, ".")
88
+
89
+ return module_name
90
+
91
+
92
+ def get_dirs(engine: Optional[Engine] = None) -> List[Path]:
93
+ """
94
+ Helper for using django_component's FilesystemLoader class to obtain a list
95
+ of directories where component python files may be defined.
96
+ """
97
+ current_engine = engine
98
+ if current_engine is None:
99
+ current_engine = Engine.get_default()
100
+
101
+ loader = Loader(current_engine)
102
+ return loader.get_dirs()
103
+
104
+
105
+ def search_dirs(dirs: List[Path], search_glob: str) -> List[Path]:
106
+ """
107
+ Search the directories for the given glob pattern. Glob search results are returned
108
+ as a flattened list.
109
+ """
110
+ matched_files: List[Path] = []
111
+ for directory in dirs:
112
+ for path in glob.iglob(str(Path(directory) / search_glob), recursive=True):
113
+ matched_files.append(Path(path))
114
+
115
+ return matched_files