django-components 0.129__tar.gz → 0.131__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 (86) hide show
  1. {django_components-0.129/src/django_components.egg-info → django_components-0.131}/PKG-INFO +64 -10
  2. {django_components-0.129 → django_components-0.131}/README.md +63 -9
  3. {django_components-0.129 → django_components-0.131}/pyproject.toml +7 -2
  4. {django_components-0.129 → django_components-0.131}/src/django_components/__init__.py +46 -3
  5. {django_components-0.129 → django_components-0.131}/src/django_components/app_settings.py +146 -41
  6. {django_components-0.129 → django_components-0.131}/src/django_components/apps.py +6 -0
  7. {django_components-0.129 → django_components-0.131}/src/django_components/autodiscovery.py +12 -0
  8. {django_components-0.129 → django_components-0.131}/src/django_components/cache.py +12 -11
  9. django_components-0.131/src/django_components/commands/components.py +32 -0
  10. django_components-0.131/src/django_components/commands/create.py +220 -0
  11. django_components-0.131/src/django_components/commands/ext.py +22 -0
  12. django_components-0.131/src/django_components/commands/ext_list.py +74 -0
  13. django_components-0.131/src/django_components/commands/ext_run.py +113 -0
  14. django_components-0.131/src/django_components/commands/list.py +222 -0
  15. django_components-0.131/src/django_components/commands/startcomponent.py +11 -0
  16. django_components-0.131/src/django_components/commands/upgrade.py +79 -0
  17. django_components-0.131/src/django_components/commands/upgradecomponent.py +11 -0
  18. django_components-0.131/src/django_components/compat/django.py +164 -0
  19. {django_components-0.129 → django_components-0.131}/src/django_components/component.py +204 -53
  20. {django_components-0.129 → django_components-0.131}/src/django_components/component_media.py +14 -1
  21. {django_components-0.129 → django_components-0.131}/src/django_components/component_registry.py +127 -42
  22. {django_components-0.129 → django_components-0.131}/src/django_components/components/__init__.py +1 -1
  23. {django_components-0.129 → django_components-0.131}/src/django_components/components/dynamic.py +6 -2
  24. {django_components-0.129 → django_components-0.131}/src/django_components/expression.py +8 -1
  25. django_components-0.131/src/django_components/extension.py +720 -0
  26. django_components-0.131/src/django_components/extensions/view.py +80 -0
  27. django_components-0.131/src/django_components/management/commands/components.py +5 -0
  28. django_components-0.131/src/django_components/management/commands/startcomponent.py +5 -0
  29. django_components-0.131/src/django_components/management/commands/upgradecomponent.py +5 -0
  30. django_components-0.131/src/django_components/py.typed +0 -0
  31. {django_components-0.129 → django_components-0.131}/src/django_components/slots.py +5 -3
  32. django_components-0.131/src/django_components/templatetags/__init__.py +0 -0
  33. django_components-0.131/src/django_components/testing.py +9 -0
  34. django_components-0.131/src/django_components/urls.py +18 -0
  35. django_components-0.131/src/django_components/util/__init__.py +0 -0
  36. django_components-0.131/src/django_components/util/command.py +407 -0
  37. {django_components-0.129 → django_components-0.131}/src/django_components/util/context.py +44 -2
  38. {django_components-0.129 → django_components-0.131}/src/django_components/util/misc.py +33 -1
  39. django_components-0.131/src/django_components/util/routing.py +62 -0
  40. django_components-0.131/src/django_components/util/testing.py +543 -0
  41. django_components-0.131/src/django_components/util/weakref.py +30 -0
  42. {django_components-0.129 → django_components-0.131/src/django_components.egg-info}/PKG-INFO +64 -10
  43. {django_components-0.129 → django_components-0.131}/src/django_components.egg-info/SOURCES.txt +22 -1
  44. django_components-0.129/src/django_components/management/commands/startcomponent.py +0 -219
  45. django_components-0.129/src/django_components/management/commands/upgradecomponent.py +0 -69
  46. django_components-0.129/src/django_components/urls.py +0 -7
  47. {django_components-0.129 → django_components-0.131}/LICENSE +0 -0
  48. {django_components-0.129 → django_components-0.131}/MANIFEST.in +0 -0
  49. {django_components-0.129 → django_components-0.131}/setup.cfg +0 -0
  50. {django_components-0.129 → django_components-0.131}/src/django_components/attributes.py +0 -0
  51. {django_components-0.129/src/django_components/management → django_components-0.131/src/django_components/commands}/__init__.py +0 -0
  52. {django_components-0.129/src/django_components/management/commands → django_components-0.131/src/django_components/compat}/__init__.py +0 -0
  53. {django_components-0.129 → django_components-0.131}/src/django_components/context.py +0 -0
  54. {django_components-0.129 → django_components-0.131}/src/django_components/dependencies.py +0 -0
  55. {django_components-0.129/src/django_components/perfutil → django_components-0.131/src/django_components/extensions}/__init__.py +0 -0
  56. {django_components-0.129 → django_components-0.131}/src/django_components/finders.py +0 -0
  57. {django_components-0.129 → django_components-0.131}/src/django_components/library.py +0 -0
  58. {django_components-0.129/src/django_components/templatetags → django_components-0.131/src/django_components/management}/__init__.py +0 -0
  59. {django_components-0.129/src/django_components/util → django_components-0.131/src/django_components/management/commands}/__init__.py +0 -0
  60. {django_components-0.129 → django_components-0.131}/src/django_components/middleware.py +0 -0
  61. {django_components-0.129 → django_components-0.131}/src/django_components/node.py +0 -0
  62. /django_components-0.129/src/django_components/py.typed → /django_components-0.131/src/django_components/perfutil/__init__.py +0 -0
  63. {django_components-0.129 → django_components-0.131}/src/django_components/perfutil/component.py +0 -0
  64. {django_components-0.129 → django_components-0.131}/src/django_components/perfutil/provide.py +0 -0
  65. {django_components-0.129 → django_components-0.131}/src/django_components/provide.py +0 -0
  66. {django_components-0.129 → django_components-0.131}/src/django_components/static/django_components/django_components.min.js +0 -0
  67. {django_components-0.129 → django_components-0.131}/src/django_components/tag_formatter.py +0 -0
  68. {django_components-0.129 → django_components-0.131}/src/django_components/template.py +0 -0
  69. {django_components-0.129 → django_components-0.131}/src/django_components/template_loader.py +0 -0
  70. {django_components-0.129 → django_components-0.131}/src/django_components/templatetags/component_tags.py +0 -0
  71. {django_components-0.129 → django_components-0.131}/src/django_components/types.py +0 -0
  72. {django_components-0.129 → django_components-0.131}/src/django_components/util/cache.py +0 -0
  73. {django_components-0.129 → django_components-0.131}/src/django_components/util/component_highlight.py +0 -0
  74. {django_components-0.129 → django_components-0.131}/src/django_components/util/django_monkeypatch.py +0 -0
  75. {django_components-0.129 → django_components-0.131}/src/django_components/util/exception.py +0 -0
  76. {django_components-0.129 → django_components-0.131}/src/django_components/util/loader.py +0 -0
  77. {django_components-0.129 → django_components-0.131}/src/django_components/util/logger.py +0 -0
  78. {django_components-0.129 → django_components-0.131}/src/django_components/util/nanoid.py +0 -0
  79. {django_components-0.129 → django_components-0.131}/src/django_components/util/tag_parser.py +0 -0
  80. {django_components-0.129 → django_components-0.131}/src/django_components/util/template_parser.py +0 -0
  81. {django_components-0.129 → django_components-0.131}/src/django_components/util/template_tag.py +0 -0
  82. {django_components-0.129 → django_components-0.131}/src/django_components/util/types.py +0 -0
  83. {django_components-0.129 → django_components-0.131}/src/django_components/util/validation.py +0 -0
  84. {django_components-0.129 → django_components-0.131}/src/django_components.egg-info/dependency_links.txt +0 -0
  85. {django_components-0.129 → django_components-0.131}/src/django_components.egg-info/requires.txt +0 -0
  86. {django_components-0.129 → django_components-0.131}/src/django_components.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.2
2
2
  Name: django_components
3
- Version: 0.129
3
+ Version: 0.131
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
@@ -31,18 +31,13 @@ Requires-Dist: djc-core-html-parser>=1.0
31
31
 
32
32
  # <img src="https://raw.githubusercontent.com/django-components/django-components/master/logo/logo-black-on-white.svg" alt="django-components" style="max-width: 100%; background: white; color: black;">
33
33
 
34
- [![PyPI - Version](https://img.shields.io/pypi/v/django-components)](https://pypi.org/project/django-components/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-components)](https://pypi.org/project/django-components/) [![PyPI - License](https://img.shields.io/pypi/l/django-components)](https://github.com/django-components/django-components/blob/master/LICENSE/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/django-components)](https://pypistats.org/packages/django-components) [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/django-components/django-components/tests.yml)](https://github.com/django-components/django-components/actions/workflows/tests.yml)
34
+ [![PyPI - Version](https://img.shields.io/pypi/v/django-components)](https://pypi.org/project/django-components/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-components)](https://pypi.org/project/django-components/) [![PyPI - License](https://img.shields.io/pypi/l/django-components)](https://github.com/django-components/django-components/blob/master/LICENSE/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/django-components)](https://pypistats.org/packages/django-components) [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/django-components/django-components/tests.yml)](https://github.com/django-components/django-components/actions/workflows/tests.yml) [![asv](https://img.shields.io/badge/benchmarked%20by-asv-blue.svg?style=flat)](https://django-components.github.io/django-components/latest/benchmarks/)
35
35
 
36
36
  ### <table><td>[Read the full documentation](https://django-components.github.io/django-components/latest/)</td></table>
37
37
 
38
- <!-- TODO - Remove this banner after a month(?), so March 2025 -->
39
- > ⚠️ Attention ⚠️ - We migrated from `EmilStenstrom/django-components` to `django-components/django-components`.
40
- >
41
- > **Repo name and documentation URL changed. Package name remains the same.**
42
- >
43
- > Report any broken links links in [#922](https://github.com/django-components/django-components/issues/922).
38
+ `django-components` is a modular and extensible UI framework for Django.
44
39
 
45
- `django-components` combines Django's templating system with the modularity seen
40
+ It combines Django's templating system with the modularity seen
46
41
  in modern frontend frameworks like Vue or React.
47
42
 
48
43
  With `django-components` you can support Django projects small and large without leaving the Django ecosystem.
@@ -117,6 +112,10 @@ And this is what gets rendered:
117
112
  </div>
118
113
  ```
119
114
 
115
+ Read on to learn about all the exciting details and configuration possibilities!
116
+
117
+ (If you instead prefer to jump right into the code, [check out the example project](https://github.com/django-components/django-components/tree/master/sampleproject))
118
+
120
119
  ## Features
121
120
 
122
121
  ### Modern and modular UI
@@ -309,6 +308,48 @@ Button.render(
309
308
  )
310
309
  ```
311
310
 
311
+ ### Extensions
312
+
313
+ Django-components functionality can be extended with "extensions". Extensions allow for powerful customization and integrations. They can:
314
+
315
+ - Tap into lifecycle events, such as when a component is created, deleted, or registered.
316
+ - Add new attributes and methods to the components under an extension-specific nested class.
317
+
318
+ Some of the planned extensions include:
319
+
320
+ - Caching
321
+ - AlpineJS integration
322
+ - Storybook integration
323
+ - Pydantic validation
324
+ - Component-level benchmarking with asv
325
+
326
+ ### Simple testing
327
+
328
+ - Write tests for components with `@djc_test` decorator.
329
+ - The decorator manages global state, ensuring that tests don't leak.
330
+ - If using `pytest`, the decorator allows you to parametrize Django or Components settings.
331
+ - The decorator also serves as a stand-in for Django's `@override_settings`.
332
+
333
+ ```python
334
+ from djc_test import djc_test
335
+
336
+ from components.my_component import MyTable
337
+
338
+ @djc_test
339
+ def test_my_table():
340
+ rendered = MyTable.render(
341
+ kwargs={
342
+ "title": "My table",
343
+ },
344
+ )
345
+ assert rendered == "<table>My table</table>"
346
+ ```
347
+
348
+ ### Handle large projects with ease
349
+
350
+ - Components can be infinitely nested.
351
+ - (Soon) Optimize performance with component-level caching
352
+
312
353
  ### Debugging features
313
354
 
314
355
  - **Visual component inspection**: Highlight components and slots directly in your browser.
@@ -322,7 +363,7 @@ Button.render(
322
363
 
323
364
  - Install and use third-party components from PyPI
324
365
  - Or publish your own "component registry"
325
- - Highly customizable - Choose how the components are called in the template, and more:
366
+ - Highly customizable - Choose how the components are called in the template (and more):
326
367
 
327
368
  ```django
328
369
  {% component "calendar" date="2024-11-06" %}
@@ -343,6 +384,19 @@ Button.render(
343
384
 
344
385
  ... or jump right into the code, [check out the example project](https://github.com/django-components/django-components/tree/master/sampleproject).
345
386
 
387
+ ## Performance
388
+
389
+ Our aim is to be at least as fast as Django templates.
390
+
391
+ As of `0.130`, `django-components` is ~4x slower than Django templates.
392
+
393
+ | | Render time|
394
+ |----------|----------------------|
395
+ | django | 68.9±0.6ms |
396
+ | django-components | 259±4ms |
397
+
398
+ See the [full performance breakdown](https://django-components.github.io/django-components/latest/benchmarks/) for more information.
399
+
346
400
  ## Release notes
347
401
 
348
402
  Read the [Release Notes](https://github.com/django-components/django-components/tree/master/CHANGELOG.md)
@@ -1,17 +1,12 @@
1
1
  # <img src="https://raw.githubusercontent.com/django-components/django-components/master/logo/logo-black-on-white.svg" alt="django-components" style="max-width: 100%; background: white; color: black;">
2
2
 
3
- [![PyPI - Version](https://img.shields.io/pypi/v/django-components)](https://pypi.org/project/django-components/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-components)](https://pypi.org/project/django-components/) [![PyPI - License](https://img.shields.io/pypi/l/django-components)](https://github.com/django-components/django-components/blob/master/LICENSE/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/django-components)](https://pypistats.org/packages/django-components) [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/django-components/django-components/tests.yml)](https://github.com/django-components/django-components/actions/workflows/tests.yml)
3
+ [![PyPI - Version](https://img.shields.io/pypi/v/django-components)](https://pypi.org/project/django-components/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-components)](https://pypi.org/project/django-components/) [![PyPI - License](https://img.shields.io/pypi/l/django-components)](https://github.com/django-components/django-components/blob/master/LICENSE/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/django-components)](https://pypistats.org/packages/django-components) [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/django-components/django-components/tests.yml)](https://github.com/django-components/django-components/actions/workflows/tests.yml) [![asv](https://img.shields.io/badge/benchmarked%20by-asv-blue.svg?style=flat)](https://django-components.github.io/django-components/latest/benchmarks/)
4
4
 
5
5
  ### <table><td>[Read the full documentation](https://django-components.github.io/django-components/latest/)</td></table>
6
6
 
7
- <!-- TODO - Remove this banner after a month(?), so March 2025 -->
8
- > ⚠️ Attention ⚠️ - We migrated from `EmilStenstrom/django-components` to `django-components/django-components`.
9
- >
10
- > **Repo name and documentation URL changed. Package name remains the same.**
11
- >
12
- > Report any broken links links in [#922](https://github.com/django-components/django-components/issues/922).
7
+ `django-components` is a modular and extensible UI framework for Django.
13
8
 
14
- `django-components` combines Django's templating system with the modularity seen
9
+ It combines Django's templating system with the modularity seen
15
10
  in modern frontend frameworks like Vue or React.
16
11
 
17
12
  With `django-components` you can support Django projects small and large without leaving the Django ecosystem.
@@ -86,6 +81,10 @@ And this is what gets rendered:
86
81
  </div>
87
82
  ```
88
83
 
84
+ Read on to learn about all the exciting details and configuration possibilities!
85
+
86
+ (If you instead prefer to jump right into the code, [check out the example project](https://github.com/django-components/django-components/tree/master/sampleproject))
87
+
89
88
  ## Features
90
89
 
91
90
  ### Modern and modular UI
@@ -278,6 +277,48 @@ Button.render(
278
277
  )
279
278
  ```
280
279
 
280
+ ### Extensions
281
+
282
+ Django-components functionality can be extended with "extensions". Extensions allow for powerful customization and integrations. They can:
283
+
284
+ - Tap into lifecycle events, such as when a component is created, deleted, or registered.
285
+ - Add new attributes and methods to the components under an extension-specific nested class.
286
+
287
+ Some of the planned extensions include:
288
+
289
+ - Caching
290
+ - AlpineJS integration
291
+ - Storybook integration
292
+ - Pydantic validation
293
+ - Component-level benchmarking with asv
294
+
295
+ ### Simple testing
296
+
297
+ - Write tests for components with `@djc_test` decorator.
298
+ - The decorator manages global state, ensuring that tests don't leak.
299
+ - If using `pytest`, the decorator allows you to parametrize Django or Components settings.
300
+ - The decorator also serves as a stand-in for Django's `@override_settings`.
301
+
302
+ ```python
303
+ from djc_test import djc_test
304
+
305
+ from components.my_component import MyTable
306
+
307
+ @djc_test
308
+ def test_my_table():
309
+ rendered = MyTable.render(
310
+ kwargs={
311
+ "title": "My table",
312
+ },
313
+ )
314
+ assert rendered == "<table>My table</table>"
315
+ ```
316
+
317
+ ### Handle large projects with ease
318
+
319
+ - Components can be infinitely nested.
320
+ - (Soon) Optimize performance with component-level caching
321
+
281
322
  ### Debugging features
282
323
 
283
324
  - **Visual component inspection**: Highlight components and slots directly in your browser.
@@ -291,7 +332,7 @@ Button.render(
291
332
 
292
333
  - Install and use third-party components from PyPI
293
334
  - Or publish your own "component registry"
294
- - Highly customizable - Choose how the components are called in the template, and more:
335
+ - Highly customizable - Choose how the components are called in the template (and more):
295
336
 
296
337
  ```django
297
338
  {% component "calendar" date="2024-11-06" %}
@@ -312,6 +353,19 @@ Button.render(
312
353
 
313
354
  ... or jump right into the code, [check out the example project](https://github.com/django-components/django-components/tree/master/sampleproject).
314
355
 
356
+ ## Performance
357
+
358
+ Our aim is to be at least as fast as Django templates.
359
+
360
+ As of `0.130`, `django-components` is ~4x slower than Django templates.
361
+
362
+ | | Render time|
363
+ |----------|----------------------|
364
+ | django | 68.9±0.6ms |
365
+ | django-components | 259±4ms |
366
+
367
+ See the [full performance breakdown](https://django-components.github.io/django-components/latest/benchmarks/) for more information.
368
+
315
369
  ## Release notes
316
370
 
317
371
  Read the [Release Notes](https://github.com/django-components/django-components/tree/master/CHANGELOG.md)
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "django_components"
7
- version = "0.129"
7
+ version = "0.131"
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"]
@@ -88,6 +88,7 @@ exclude = [
88
88
  'build',
89
89
  ]
90
90
  per-file-ignores = [
91
+ 'tests/test_command_list.py:E501',
91
92
  'tests/test_component_media.py:E501',
92
93
  'tests/test_dependency_rendering.py:E501',
93
94
  ]
@@ -109,6 +110,7 @@ disallow_untyped_defs = true
109
110
  testpaths = [
110
111
  "tests"
111
112
  ]
113
+ asyncio_mode = "auto"
112
114
 
113
115
  [tool.hatch.env]
114
116
  requires = [
@@ -128,7 +130,7 @@ dependencies = [
128
130
  "pre-commit",
129
131
  "black",
130
132
  "mypy",
131
- ]
133
+ ]
132
134
  type = "pip-compile"
133
135
  lock-filename = "requirements-dev.txt"
134
136
 
@@ -140,6 +142,9 @@ detached = false
140
142
  # We only add black for formatting code in the docs
141
143
  dependencies = [
142
144
  "black",
145
+ "pygments",
146
+ "pygments-djc",
147
+ "mkdocs-awesome-nav",
143
148
  ]
144
149
 
145
150
  [tool.hatch.env.collectors.mkdocs.docs]
@@ -6,7 +6,16 @@
6
6
  # isort: off
7
7
  from django_components.app_settings import ContextBehavior, ComponentsSettings
8
8
  from django_components.autodiscovery import autodiscover, import_libraries
9
- from django_components.component import Component, ComponentVars, ComponentView
9
+ from django_components.util.command import (
10
+ CommandArg,
11
+ CommandArgGroup,
12
+ CommandHandler,
13
+ CommandLiteralAction,
14
+ CommandParserInput,
15
+ CommandSubcommand,
16
+ ComponentCommand,
17
+ )
18
+ from django_components.component import Component, ComponentVars, all_components
10
19
  from django_components.component_media import ComponentMediaInput, ComponentMediaInputPath
11
20
  from django_components.component_registry import (
12
21
  AlreadyRegistered,
@@ -15,9 +24,22 @@ from django_components.component_registry import (
15
24
  RegistrySettings,
16
25
  register,
17
26
  registry,
27
+ all_registries,
18
28
  )
19
29
  from django_components.components import DynamicComponent
20
30
  from django_components.dependencies import render_dependencies
31
+ from django_components.extension import (
32
+ ComponentExtension,
33
+ OnComponentRegisteredContext,
34
+ OnComponentUnregisteredContext,
35
+ OnRegistryCreatedContext,
36
+ OnRegistryDeletedContext,
37
+ OnComponentClassCreatedContext,
38
+ OnComponentClassDeletedContext,
39
+ OnComponentInputContext,
40
+ OnComponentDataContext,
41
+ )
42
+ from django_components.extensions.view import ComponentView
21
43
  from django_components.library import TagProtectedError
22
44
  from django_components.node import BaseNode, template_tag
23
45
  from django_components.slots import SlotContent, Slot, SlotFunc, SlotRef, SlotResult
@@ -32,19 +54,29 @@ from django_components.tag_formatter import (
32
54
  from django_components.template import cached_template
33
55
  import django_components.types as types
34
56
  from django_components.util.loader import ComponentFileEntry, get_component_dirs, get_component_files
57
+ from django_components.util.routing import URLRoute, URLRouteHandler
35
58
  from django_components.util.types import EmptyTuple, EmptyDict
36
59
 
37
60
  # isort: on
38
61
 
39
62
 
40
63
  __all__ = [
64
+ "all_components",
65
+ "all_registries",
41
66
  "AlreadyRegistered",
42
67
  "autodiscover",
43
- "cached_template",
44
68
  "BaseNode",
45
- "ContextBehavior",
69
+ "cached_template",
70
+ "CommandArg",
71
+ "CommandArgGroup",
72
+ "CommandHandler",
73
+ "CommandLiteralAction",
74
+ "CommandParserInput",
75
+ "CommandSubcommand",
76
+ "ComponentCommand",
46
77
  "ComponentsSettings",
47
78
  "Component",
79
+ "ComponentExtension",
48
80
  "ComponentFileEntry",
49
81
  "ComponentFormatter",
50
82
  "ComponentMediaInput",
@@ -54,6 +86,7 @@ __all__ = [
54
86
  "ComponentView",
55
87
  "component_formatter",
56
88
  "component_shorthand_formatter",
89
+ "ContextBehavior",
57
90
  "DynamicComponent",
58
91
  "EmptyTuple",
59
92
  "EmptyDict",
@@ -61,6 +94,14 @@ __all__ = [
61
94
  "get_component_files",
62
95
  "import_libraries",
63
96
  "NotRegistered",
97
+ "OnComponentClassCreatedContext",
98
+ "OnComponentClassDeletedContext",
99
+ "OnComponentDataContext",
100
+ "OnComponentInputContext",
101
+ "OnComponentRegisteredContext",
102
+ "OnComponentUnregisteredContext",
103
+ "OnRegistryCreatedContext",
104
+ "OnRegistryDeletedContext",
64
105
  "register",
65
106
  "registry",
66
107
  "RegistrySettings",
@@ -76,4 +117,6 @@ __all__ = [
76
117
  "TagResult",
77
118
  "template_tag",
78
119
  "types",
120
+ "URLRoute",
121
+ "URLRouteHandler",
79
122
  ]
@@ -1,11 +1,14 @@
1
1
  import re
2
2
  from dataclasses import dataclass
3
3
  from enum import Enum
4
+ from importlib import import_module
4
5
  from os import PathLike
5
6
  from pathlib import Path
6
7
  from typing import (
7
8
  TYPE_CHECKING,
9
+ Any,
8
10
  Callable,
11
+ Dict,
9
12
  Generic,
10
13
  List,
11
14
  Literal,
@@ -13,6 +16,7 @@ from typing import (
13
16
  Optional,
14
17
  Sequence,
15
18
  Tuple,
19
+ Type,
16
20
  TypeVar,
17
21
  Union,
18
22
  cast,
@@ -23,6 +27,7 @@ from django.conf import settings
23
27
  from django_components.util.misc import default
24
28
 
25
29
  if TYPE_CHECKING:
30
+ from django_components.extension import ComponentExtension
26
31
  from django_components.tag_formatter import TagFormatterABC
27
32
 
28
33
 
@@ -144,6 +149,25 @@ class ComponentsSettings(NamedTuple):
144
149
  ```
145
150
  """
146
151
 
152
+ extensions: Optional[Sequence[Union[Type["ComponentExtension"], str]]] = None
153
+ """
154
+ List of [extensions](../../concepts/advanced/extensions) to be loaded.
155
+
156
+ The extensions can be specified as:
157
+
158
+ - Python import path, e.g. `"path.to.my_extension.MyExtension"`.
159
+ - Extension class, e.g. `my_extension.MyExtension`.
160
+
161
+ ```python
162
+ COMPONENTS = ComponentsSettings(
163
+ extensions=[
164
+ "path.to.my_extension.MyExtension",
165
+ StorybookExtension,
166
+ ],
167
+ )
168
+ ```
169
+ """
170
+
147
171
  autodiscover: Optional[bool] = None
148
172
  """
149
173
  Toggle whether to run [autodiscovery](../../concepts/fundamentals/autodiscovery) at the Django server startup.
@@ -645,6 +669,7 @@ defaults = ComponentsSettings(
645
669
  debug_highlight_components=False,
646
670
  debug_highlight_slots=False,
647
671
  dynamic_component_name="dynamic",
672
+ extensions=[],
648
673
  libraries=[], # E.g. ["mysite.components.forms", ...]
649
674
  multiline_tags=True,
650
675
  reload_on_file_change=False,
@@ -671,94 +696,174 @@ defaults = ComponentsSettings(
671
696
  # fmt: on
672
697
 
673
698
 
699
+ # Interface through which we access the settings.
700
+ #
701
+ # This is the only place where we actually access the settings.
702
+ # The settings are merged with defaults, and then validated.
703
+ #
704
+ # The settings are then available through the `app_settings` object.
705
+ #
706
+ # Settings are loaded from Django settings only once, at `apps.py` in `ready()`.
674
707
  class InternalSettings:
675
- @property
676
- def _settings(self) -> ComponentsSettings:
708
+ def __init__(self, settings: Optional[Dict[str, Any]] = None):
709
+ self._settings = ComponentsSettings(**settings) if settings else defaults
710
+
711
+ def _load_settings(self) -> None:
677
712
  data = getattr(settings, "COMPONENTS", {})
678
- return ComponentsSettings(**data) if not isinstance(data, ComponentsSettings) else data
713
+ components_settings = ComponentsSettings(**data) if not isinstance(data, ComponentsSettings) else data
714
+
715
+ # Merge we defaults and otherwise initialize if necessary
716
+
717
+ # For DIRS setting, we use a getter for the default value, because the default value
718
+ # uses Django settings, which may not yet be initialized at the time these settings are generated.
719
+ dirs_default_fn = cast(Dynamic[Sequence[Union[str, Tuple[str, str]]]], defaults.dirs)
720
+ dirs_default = dirs_default_fn.getter()
721
+
722
+ self._settings = ComponentsSettings(
723
+ autodiscover=default(components_settings.autodiscover, defaults.autodiscover),
724
+ cache=default(components_settings.cache, defaults.cache),
725
+ dirs=default(components_settings.dirs, dirs_default),
726
+ app_dirs=default(components_settings.app_dirs, defaults.app_dirs),
727
+ debug_highlight_components=default(
728
+ components_settings.debug_highlight_components, defaults.debug_highlight_components
729
+ ),
730
+ debug_highlight_slots=default(components_settings.debug_highlight_slots, defaults.debug_highlight_slots),
731
+ dynamic_component_name=default(
732
+ components_settings.dynamic_component_name, defaults.dynamic_component_name
733
+ ),
734
+ libraries=default(components_settings.libraries, defaults.libraries),
735
+ # NOTE: Internally we store the extensions as a list of instances, but the user
736
+ # can pass in either a list of classes or a list of import strings.
737
+ extensions=self._prepare_extensions(components_settings), # type: ignore[arg-type]
738
+ multiline_tags=default(components_settings.multiline_tags, defaults.multiline_tags),
739
+ reload_on_file_change=self._prepare_reload_on_file_change(components_settings),
740
+ template_cache_size=default(components_settings.template_cache_size, defaults.template_cache_size),
741
+ static_files_allowed=default(components_settings.static_files_allowed, defaults.static_files_allowed),
742
+ static_files_forbidden=self._prepare_static_files_forbidden(components_settings),
743
+ context_behavior=self._prepare_context_behavior(components_settings),
744
+ tag_formatter=default(components_settings.tag_formatter, defaults.tag_formatter), # type: ignore[arg-type]
745
+ )
746
+
747
+ def _prepare_extensions(self, new_settings: ComponentsSettings) -> List["ComponentExtension"]:
748
+ extensions: Sequence[Union[Type["ComponentExtension"], str]] = default(
749
+ new_settings.extensions, cast(List[str], defaults.extensions)
750
+ )
751
+
752
+ # Prepend built-in extensions
753
+ from django_components.extensions.view import ViewExtension
754
+
755
+ extensions = [ViewExtension] + list(extensions)
756
+
757
+ # Extensions may be passed in either as classes or import strings.
758
+ extension_instances: List["ComponentExtension"] = []
759
+ for extension in extensions:
760
+ if isinstance(extension, str):
761
+ import_path, class_name = extension.rsplit(".", 1)
762
+ extension_module = import_module(import_path)
763
+ extension = cast(Type["ComponentExtension"], getattr(extension_module, class_name))
764
+
765
+ if isinstance(extension, type):
766
+ extension_instance = extension()
767
+ else:
768
+ extension_instances.append(extension)
769
+
770
+ extension_instances.append(extension_instance)
771
+
772
+ return extension_instances
773
+
774
+ def _prepare_reload_on_file_change(self, new_settings: ComponentsSettings) -> bool:
775
+ val = new_settings.reload_on_file_change
776
+ # TODO_REMOVE_IN_V1
777
+ if val is None:
778
+ val = new_settings.reload_on_template_change
679
779
 
780
+ return default(val, cast(bool, defaults.reload_on_file_change))
781
+
782
+ def _prepare_static_files_forbidden(self, new_settings: ComponentsSettings) -> List[Union[str, re.Pattern]]:
783
+ val = new_settings.static_files_forbidden
784
+ # TODO_REMOVE_IN_V1
785
+ if val is None:
786
+ val = new_settings.forbidden_static_files
787
+
788
+ return default(val, cast(List[Union[str, re.Pattern]], defaults.static_files_forbidden))
789
+
790
+ def _prepare_context_behavior(self, new_settings: ComponentsSettings) -> Literal["django", "isolated"]:
791
+ raw_value = cast(
792
+ Literal["django", "isolated"],
793
+ default(new_settings.context_behavior, defaults.context_behavior),
794
+ )
795
+ try:
796
+ ContextBehavior(raw_value)
797
+ except ValueError:
798
+ valid_values = [behavior.value for behavior in ContextBehavior]
799
+ raise ValueError(f"Invalid context behavior: {raw_value}. Valid options are {valid_values}")
800
+
801
+ return raw_value
802
+
803
+ # TODO REMOVE THE PROPERTIES BELOW? THEY NO LONGER SERVE ANY PURPOSE
680
804
  @property
681
805
  def AUTODISCOVER(self) -> bool:
682
- return default(self._settings.autodiscover, cast(bool, defaults.autodiscover))
806
+ return self._settings.autodiscover # type: ignore[return-value]
683
807
 
684
808
  @property
685
809
  def CACHE(self) -> Optional[str]:
686
- return default(self._settings.cache, defaults.cache)
810
+ return self._settings.cache
687
811
 
688
812
  @property
689
813
  def DIRS(self) -> Sequence[Union[str, PathLike, Tuple[str, str], Tuple[str, PathLike]]]:
690
- # For DIRS we use a getter, because default values uses Django settings,
691
- # which may not yet be initialized at the time these settings are generated.
692
- default_fn = cast(Dynamic[Sequence[Union[str, Tuple[str, str]]]], defaults.dirs)
693
- default_dirs = default_fn.getter()
694
- return default(self._settings.dirs, default_dirs)
814
+ return self._settings.dirs # type: ignore[return-value]
695
815
 
696
816
  @property
697
817
  def APP_DIRS(self) -> Sequence[str]:
698
- return default(self._settings.app_dirs, cast(List[str], defaults.app_dirs))
818
+ return self._settings.app_dirs # type: ignore[return-value]
699
819
 
700
820
  @property
701
821
  def DEBUG_HIGHLIGHT_COMPONENTS(self) -> bool:
702
- return default(self._settings.debug_highlight_components, cast(bool, defaults.debug_highlight_components))
822
+ return self._settings.debug_highlight_components # type: ignore[return-value]
703
823
 
704
824
  @property
705
825
  def DEBUG_HIGHLIGHT_SLOTS(self) -> bool:
706
- return default(self._settings.debug_highlight_slots, cast(bool, defaults.debug_highlight_slots))
826
+ return self._settings.debug_highlight_slots # type: ignore[return-value]
707
827
 
708
828
  @property
709
829
  def DYNAMIC_COMPONENT_NAME(self) -> str:
710
- return default(self._settings.dynamic_component_name, cast(str, defaults.dynamic_component_name))
830
+ return self._settings.dynamic_component_name # type: ignore[return-value]
711
831
 
712
832
  @property
713
833
  def LIBRARIES(self) -> List[str]:
714
- return default(self._settings.libraries, cast(List[str], defaults.libraries))
834
+ return self._settings.libraries # type: ignore[return-value]
835
+
836
+ @property
837
+ def EXTENSIONS(self) -> List["ComponentExtension"]:
838
+ return self._settings.extensions # type: ignore[return-value]
715
839
 
716
840
  @property
717
841
  def MULTILINE_TAGS(self) -> bool:
718
- return default(self._settings.multiline_tags, cast(bool, defaults.multiline_tags))
842
+ return self._settings.multiline_tags # type: ignore[return-value]
719
843
 
720
844
  @property
721
845
  def RELOAD_ON_FILE_CHANGE(self) -> bool:
722
- val = self._settings.reload_on_file_change
723
- # TODO_REMOVE_IN_V1
724
- if val is None:
725
- val = self._settings.reload_on_template_change
726
-
727
- return default(val, cast(bool, defaults.reload_on_file_change))
846
+ return self._settings.reload_on_file_change # type: ignore[return-value]
728
847
 
729
848
  @property
730
849
  def TEMPLATE_CACHE_SIZE(self) -> int:
731
- return default(self._settings.template_cache_size, cast(int, defaults.template_cache_size))
850
+ return self._settings.template_cache_size # type: ignore[return-value]
732
851
 
733
852
  @property
734
853
  def STATIC_FILES_ALLOWED(self) -> Sequence[Union[str, re.Pattern]]:
735
- return default(self._settings.static_files_allowed, cast(List[str], defaults.static_files_allowed))
854
+ return self._settings.static_files_allowed # type: ignore[return-value]
736
855
 
737
856
  @property
738
857
  def STATIC_FILES_FORBIDDEN(self) -> Sequence[Union[str, re.Pattern]]:
739
- val = self._settings.static_files_forbidden
740
- # TODO_REMOVE_IN_V1
741
- if val is None:
742
- val = self._settings.forbidden_static_files
743
-
744
- return default(val, cast(List[str], defaults.static_files_forbidden))
858
+ return self._settings.static_files_forbidden # type: ignore[return-value]
745
859
 
746
860
  @property
747
861
  def CONTEXT_BEHAVIOR(self) -> ContextBehavior:
748
- raw_value = cast(str, default(self._settings.context_behavior, defaults.context_behavior))
749
- return self._validate_context_behavior(raw_value)
750
-
751
- def _validate_context_behavior(self, raw_value: Union[ContextBehavior, str]) -> ContextBehavior:
752
- try:
753
- return ContextBehavior(raw_value)
754
- except ValueError:
755
- valid_values = [behavior.value for behavior in ContextBehavior]
756
- raise ValueError(f"Invalid context behavior: {raw_value}. Valid options are {valid_values}")
862
+ return ContextBehavior(self._settings.context_behavior)
757
863
 
758
864
  @property
759
865
  def TAG_FORMATTER(self) -> Union["TagFormatterABC", str]:
760
- tag_formatter = default(self._settings.tag_formatter, cast(str, defaults.tag_formatter))
761
- return cast(Union["TagFormatterABC", str], tag_formatter)
866
+ return self._settings.tag_formatter # type: ignore[return-value]
762
867
 
763
868
 
764
869
  app_settings = InternalSettings()
@@ -17,8 +17,11 @@ class ComponentsConfig(AppConfig):
17
17
  from django_components.autodiscovery import autodiscover, import_libraries
18
18
  from django_components.component_registry import registry
19
19
  from django_components.components.dynamic import DynamicComponent
20
+ from django_components.extension import extensions
20
21
  from django_components.util.django_monkeypatch import monkeypatch_template_cls
21
22
 
23
+ app_settings._load_settings()
24
+
22
25
  # NOTE: This monkeypatch is applied here, before Django processes any requests.
23
26
  # To make django-components work with django-debug-toolbar-template-profiler
24
27
  # See https://github.com/django-components/django-components/discussions/819
@@ -55,6 +58,9 @@ class ComponentsConfig(AppConfig):
55
58
  # Register the dynamic component under the name as given in settings
56
59
  registry.register(app_settings.DYNAMIC_COMPONENT_NAME, DynamicComponent)
57
60
 
61
+ # Let extensions process any components which may have been created before the app was ready
62
+ extensions._init_app()
63
+
58
64
 
59
65
  # See https://github.com/django-components/django-components/issues/586#issue-2472678136
60
66
  def _watch_component_files_for_autoreload() -> None: