django-components 0.86__tar.gz → 0.88__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 (60) hide show
  1. {django_components-0.86/src/django_components.egg-info → django_components-0.88}/PKG-INFO +253 -130
  2. {django_components-0.86 → django_components-0.88}/README.md +252 -129
  3. {django_components-0.86 → django_components-0.88}/pyproject.toml +1 -1
  4. django_components-0.88/src/django_components/__init__.py +19 -0
  5. {django_components-0.86 → django_components-0.88}/src/django_components/component.py +15 -12
  6. {django_components-0.86 → django_components-0.88}/src/django_components/component_media.py +7 -7
  7. django_components-0.88/src/django_components/component_registry.py +338 -0
  8. {django_components-0.86 → django_components-0.88}/src/django_components/management/commands/startcomponent.py +3 -3
  9. {django_components-0.86 → django_components-0.88/src/django_components.egg-info}/PKG-INFO +253 -130
  10. {django_components-0.86 → django_components-0.88}/tests/test_attributes.py +28 -31
  11. {django_components-0.86 → django_components-0.88}/tests/test_autodiscover.py +13 -13
  12. {django_components-0.86 → django_components-0.88}/tests/test_component.py +21 -21
  13. {django_components-0.86 → django_components-0.88}/tests/test_component_as_view.py +9 -9
  14. {django_components-0.86 → django_components-0.88}/tests/test_component_media.py +35 -35
  15. {django_components-0.86 → django_components-0.88}/tests/test_context.py +25 -29
  16. {django_components-0.86 → django_components-0.88}/tests/test_dependency_rendering.py +35 -39
  17. django_components-0.88/tests/test_registry.py +126 -0
  18. {django_components-0.86 → django_components-0.88}/tests/test_template_parser.py +3 -3
  19. {django_components-0.86 → django_components-0.88}/tests/test_templatetags.py +37 -44
  20. {django_components-0.86 → django_components-0.88}/tests/test_templatetags_component.py +32 -42
  21. {django_components-0.86 → django_components-0.88}/tests/test_templatetags_provide.py +45 -45
  22. {django_components-0.86 → django_components-0.88}/tests/test_templatetags_slot_fill.py +62 -79
  23. {django_components-0.86 → django_components-0.88}/tests/test_templatetags_templating.py +34 -46
  24. django_components-0.86/src/django_components/__init__.py +0 -7
  25. django_components-0.86/src/django_components/component_registry.py +0 -63
  26. django_components-0.86/tests/test_registry.py +0 -68
  27. {django_components-0.86 → django_components-0.88}/LICENSE +0 -0
  28. {django_components-0.86 → django_components-0.88}/setup.cfg +0 -0
  29. {django_components-0.86 → django_components-0.88}/src/django_components/app_settings.py +0 -0
  30. {django_components-0.86 → django_components-0.88}/src/django_components/apps.py +0 -0
  31. {django_components-0.86 → django_components-0.88}/src/django_components/attributes.py +0 -0
  32. {django_components-0.86 → django_components-0.88}/src/django_components/autodiscover.py +0 -0
  33. {django_components-0.86 → django_components-0.88}/src/django_components/context.py +0 -0
  34. {django_components-0.86 → django_components-0.88}/src/django_components/expression.py +0 -0
  35. {django_components-0.86 → django_components-0.88}/src/django_components/logger.py +0 -0
  36. {django_components-0.86 → django_components-0.88}/src/django_components/management/__init__.py +0 -0
  37. {django_components-0.86 → django_components-0.88}/src/django_components/management/commands/__init__.py +0 -0
  38. {django_components-0.86 → django_components-0.88}/src/django_components/management/commands/upgradecomponent.py +0 -0
  39. {django_components-0.86 → django_components-0.88}/src/django_components/middleware.py +0 -0
  40. {django_components-0.86 → django_components-0.88}/src/django_components/node.py +0 -0
  41. {django_components-0.86 → django_components-0.88}/src/django_components/provide.py +0 -0
  42. {django_components-0.86 → django_components-0.88}/src/django_components/py.typed +0 -0
  43. {django_components-0.86 → django_components-0.88}/src/django_components/safer_staticfiles/__init__.py +0 -0
  44. {django_components-0.86 → django_components-0.88}/src/django_components/safer_staticfiles/apps.py +0 -0
  45. {django_components-0.86 → django_components-0.88}/src/django_components/slots.py +0 -0
  46. {django_components-0.86 → django_components-0.88}/src/django_components/template_loader.py +0 -0
  47. {django_components-0.86 → django_components-0.88}/src/django_components/template_parser.py +0 -0
  48. {django_components-0.86 → django_components-0.88}/src/django_components/templatetags/__init__.py +0 -0
  49. {django_components-0.86 → django_components-0.88}/src/django_components/templatetags/component_tags.py +0 -0
  50. {django_components-0.86 → django_components-0.88}/src/django_components/types.py +0 -0
  51. {django_components-0.86 → django_components-0.88}/src/django_components/utils.py +0 -0
  52. {django_components-0.86 → django_components-0.88}/src/django_components.egg-info/SOURCES.txt +0 -0
  53. {django_components-0.86 → django_components-0.88}/src/django_components.egg-info/dependency_links.txt +0 -0
  54. {django_components-0.86 → django_components-0.88}/src/django_components.egg-info/requires.txt +0 -0
  55. {django_components-0.86 → django_components-0.88}/src/django_components.egg-info/top_level.txt +0 -0
  56. {django_components-0.86 → django_components-0.88}/tests/test_command_startcomponent.py +0 -0
  57. {django_components-0.86 → django_components-0.88}/tests/test_safer_staticfiles.py +0 -0
  58. {django_components-0.86 → django_components-0.88}/tests/test_settings.py +0 -0
  59. {django_components-0.86 → django_components-0.88}/tests/test_template_loader.py +0 -0
  60. {django_components-0.86 → django_components-0.88}/tests/testutils.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: django_components
3
- Version: 0.86
3
+ Version: 0.88
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
@@ -23,6 +23,7 @@ License-File: LICENSE
23
23
  Requires-Dist: Django>=4.2
24
24
 
25
25
  # <img src="logo/logo-black-on-white.svg" alt="django-components" style="max-width: 100%; background: white; color: black;">
26
+
26
27
  <a href="https://github.com/EmilStenstrom/django-components/actions?query=workflow%3A%22Run+tests%22"><img align="right" src="https://github.com/EmilStenstrom/django-components/workflows/Run%20tests/badge.svg" alt="Show test status"></a>
27
28
  <a href="https://pepy.tech/project/django-components"><img align="right" src="https://pepy.tech/badge/django-components" alt="Show download stats"></a>
28
29
 
@@ -52,6 +53,7 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
52
53
  - [Using single-file components](#using-single-file-components)
53
54
  - [Use components in templates](#use-components-in-templates)
54
55
  - [Use components outside of templates](#use-components-outside-of-templates)
56
+ - [Registering components](#registering-components)
55
57
  - [Use components as views](#use-components-as-views)
56
58
  - [Autodiscovery](#autodiscovery)
57
59
  - [Using slots in templates](#using-slots-in-templates)
@@ -71,11 +73,12 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
71
73
  ## Release notes
72
74
 
73
75
  🚨📢 **Version 0.85** Autodiscovery module resolution changed. Following undocumented behavior was removed:
76
+
74
77
  - 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`
78
+ - To migrate from:
79
+ - `[app]/components.py` - Define each module in `COMPONENTS.libraries` setting,
80
+ or import each module inside the `AppConfig.ready()` hook in respective `apps.py` files.
81
+ - `SETTINGS_MODULE` - Define component dirs using `STATICFILES_DIRS`
79
82
  - 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
83
 
81
84
  🚨📢 **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.
@@ -88,12 +91,12 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
88
91
 
89
92
  - BREAKING CHANGE: Default value for the `COMPONENTS.context_behavior` setting was changes from `"isolated"` to `"django"`. If you did not set this value explicitly before, this may be a breaking change. See the rationale for change [here](https://github.com/EmilStenstrom/django-components/issues/498).
90
93
 
91
-
92
94
  🚨📢 **Version 0.77** CHANGED the syntax for accessing default slot content.
95
+
93
96
  - Previously, the syntax was
94
- `{% fill "my_slot" as "alias" %}` and `{{ alias.default }}`.
97
+ `{% fill "my_slot" as "alias" %}` and `{{ alias.default }}`.
95
98
  - Now, the syntax is
96
- `{% fill "my_slot" default="alias" %}` and `{{ alias }}`.
99
+ `{% fill "my_slot" default="alias" %}` and `{{ alias }}`.
97
100
 
98
101
  **Version 0.74** introduces `html_attrs` tag and `prefix:key=val` construct for passing dicts to components.
99
102
 
@@ -112,7 +115,7 @@ This change is done to simplify the API in anticipation of a 1.0 release of djan
112
115
 
113
116
  **Version 0.28** introduces 'implicit' slot filling and the `default` option for `slot` tags.
114
117
 
115
- **Version 0.27** adds a second installable app: *django_components.safer_staticfiles*. It provides the same behavior as *django.contrib.staticfiles* but with extra security guarantees (more info below in Security Notes).
118
+ **Version 0.27** adds a second installable app: _django_components.safer_staticfiles_. It provides the same behavior as _django.contrib.staticfiles_ but with extra security guarantees (more info below in Security Notes).
116
119
 
117
120
  **Version 0.26** changes the syntax for `{% slot %}` tags. From now on, we separate defining a slot (`{% slot %}`) from filling a slot with content (`{% fill %}`). This means you will likely need to change a lot of slot tags to fill. We understand this is annoying, but it's the only way we can get support for nested slots that fill in other slots, which is a very nice featuPpre to have access to. Hoping that this will feel worth it!
118
121
 
@@ -122,7 +125,7 @@ This change is done to simplify the API in anticipation of a 1.0 release of djan
122
125
 
123
126
  ## Security notes 🚨
124
127
 
125
- *You are advised to read this section before using django-components in production.*
128
+ _You are advised to read this section before using django-components in production._
126
129
 
127
130
  ### Static files
128
131
 
@@ -132,12 +135,12 @@ This means that files containing backend logic, such as Python modules and HTML
132
135
 
133
136
  If your are using _django.contrib.staticfiles_ to collect static files, no distinction is made between the different kinds of files.
134
137
  As a result, your Python code and templates may inadvertently become available on your static file server.
135
- You probably don't want this, as parts of your backend logic will be exposed, posing a __potential security vulnerability__.
138
+ You probably don't want this, as parts of your backend logic will be exposed, posing a **potential security vulnerability**.
136
139
 
137
- As of *v0.27*, django-components ships with an additional installable app *django_components.__safer_staticfiles__*.
138
- It is a drop-in replacement for *django.contrib.staticfiles*.
140
+ As of _v0.27_, django-components ships with an additional installable app _django_components.**safer_staticfiles**_.
141
+ It is a drop-in replacement for _django.contrib.staticfiles_.
139
142
  Its behavior is 100% identical except it ignores .py and .html files, meaning these will not end up on your static files server.
140
- To use it, add it to INSTALLED_APPS and remove _django.contrib.staticfiles_.
143
+ To use it, add it to INSTALLED*APPS and remove \_django.contrib.staticfiles*.
141
144
 
142
145
  ```python
143
146
  INSTALLED_APPS = [
@@ -187,7 +190,8 @@ For a step-by-step guide on deploying production server with static files,
187
190
  ```
188
191
 
189
192
  4. Modify `TEMPLATES` section of settings.py as follows:
190
- - *Remove `'APP_DIRS': True,`*
193
+
194
+ - _Remove `'APP_DIRS': True,`_
191
195
  - Add `loaders` to `OPTIONS` list and set it to following value:
192
196
 
193
197
  ```python
@@ -250,13 +254,13 @@ Read on to find out how to build your first component!
250
254
 
251
255
  Django-components supports all supported combinations versions of [Django](https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django) and [Python](https://devguide.python.org/versions/#versions).
252
256
 
253
- | Python version | Django version |
254
- |----------------|--------------------------|
255
- | 3.8 | 4.2 |
256
- | 3.9 | 4.2 |
257
- | 3.10 | 4.2, 5.0 |
258
- | 3.11 | 4.2, 5.0 |
259
- | 3.12 | 4.2, 5.0 |
257
+ | Python version | Django version |
258
+ | -------------- | -------------- |
259
+ | 3.8 | 4.2 |
260
+ | 3.9 | 4.2 |
261
+ | 3.10 | 4.2, 5.0 |
262
+ | 3.11 | 4.2, 5.0 |
263
+ | 3.12 | 4.2, 5.0 |
260
264
 
261
265
  ## Create your first component
262
266
 
@@ -317,10 +321,10 @@ Inside this file we create a Component by inheriting from the Component class an
317
321
 
318
322
  ```python
319
323
  # In a file called [project root]/components/calendar/calendar.py
320
- from django_components import component
324
+ from django_components import Component, register
321
325
 
322
- @component.register("calendar")
323
- class Calendar(component.Component):
326
+ @register("calendar")
327
+ class Calendar(Component):
324
328
  # Templates inside `[your apps]/components` dir and `[project root]/components` dir
325
329
  # will be automatically found. To customize which template to use based on context
326
330
  # you can override method `get_template_name` instead of specifying `template_name`.
@@ -348,26 +352,25 @@ Components can also be defined in a single file, which is useful for small compo
348
352
 
349
353
  ```python
350
354
  # In a file called [project root]/components/calendar.py
351
- from django_components import component
352
- from django_components import types as t
355
+ from django_components import Component, register, types
353
356
 
354
- @component.register("calendar")
355
- class Calendar(component.Component):
357
+ @register("calendar")
358
+ class Calendar(Component):
356
359
  def get_context_data(self, date):
357
360
  return {
358
361
  "date": date,
359
362
  }
360
363
 
361
- template: t.django_html = """
364
+ template: types.django_html = """
362
365
  <div class="calendar-component">Today's date is <span>{{ date }}</span></div>
363
366
  """
364
367
 
365
- css: t.css = """
368
+ css: types.css = """
366
369
  .calendar-component { width: 200px; background: pink; }
367
370
  .calendar-component span { font-weight: bold; }
368
371
  """
369
372
 
370
- js: t.js = """
373
+ js: types.js = """
371
374
  (function(){
372
375
  if (document.querySelector(".calendar-component")) {
373
376
  document.querySelector(".calendar-component").onclick = function(){ alert("Clicked calendar!"); };
@@ -389,10 +392,10 @@ Note, in the above example, that the `t.django_html`, `t.css`, and `t.js` types
389
392
  If you're a Pycharm user (or any other editor from Jetbrains), you can have coding assistance as well:
390
393
 
391
394
  ```python
392
- from django_components import component
395
+ from django_components import Component, register
393
396
 
394
- @component.register("calendar")
395
- class Calendar(component.Component):
397
+ @register("calendar")
398
+ class Calendar(Component):
396
399
  def get_context_data(self, date):
397
400
  return {
398
401
  "date": date,
@@ -419,8 +422,8 @@ class Calendar(component.Component):
419
422
  """
420
423
  ```
421
424
 
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.
425
+ You don't need to use `types.django_html`, `types.css`, `types.js` since Pycharm uses [language injections](https://www.jetbrains.com/help/pycharm/using-language-injections.html).
426
+ You only need to write the comments `# language=<lang>` above the variables.
424
427
 
425
428
  ## Use components in templates
426
429
 
@@ -476,7 +479,7 @@ Components can be rendered outside of Django templates, calling them as regular
476
479
  The component class defines `render` and `render_to_response` class methods. These methods accept positional args, kwargs, and slots, offering the same flexibility as the `{% component %}` tag:
477
480
 
478
481
  ```py
479
- class SimpleComponent(component.Component):
482
+ class SimpleComponent(Component):
480
483
  template = """
481
484
  {% load component_tags %}
482
485
  hello: {{ hello }}
@@ -524,21 +527,21 @@ Component.render(
524
527
  ```
525
528
 
526
529
  - _`args`_ - Positional args for the component. This is the same as calling the component
527
- as `{% component "my_comp" arg1 arg2 ... %}`
530
+ as `{% component "my_comp" arg1 arg2 ... %}`
528
531
 
529
532
  - _`kwargs`_ - Keyword args for the component. This is the same as calling the component
530
- as `{% component "my_comp" key1=val1 key2=val2 ... %}`
533
+ as `{% component "my_comp" key1=val1 key2=val2 ... %}`
531
534
 
532
535
  - _`slots`_ - Component slot fills. This is the same as pasing `{% fill %}` tags to the component.
533
- Accepts a dictionary of `{ slot_name: slot_content }` where `slot_content` can be a string
534
- or [`SlotRenderFunc`](#slotrenderfunc).
536
+ Accepts a dictionary of `{ slot_name: slot_content }` where `slot_content` can be a string
537
+ or [`SlotRenderFunc`](#slotrenderfunc).
535
538
 
536
539
  - _`escape_slots_content`_ - Whether the content from `slots` should be escaped. `True` by default to prevent XSS attacks. If you disable escaping, you should make sure that any content you pass to the slots is safe, especially if it comes from user input.
537
540
 
538
541
  - _`context`_ - A context (dictionary or Django's Context) within which the component
539
- is rendered. The keys on the context can be accessed from within the template.
540
- - NOTE: In "isolated" mode, context is NOT accessible, and data MUST be passed via
541
- component's args and kwargs.
542
+ is rendered. The keys on the context can be accessed from within the template.
543
+ - NOTE: In "isolated" mode, context is NOT accessible, and data MUST be passed via
544
+ component's args and kwargs.
542
545
 
543
546
  #### `SlotRenderFunc`
544
547
 
@@ -558,9 +561,10 @@ def render_func(
558
561
  - _`context`_ - Django's Context available to the Slot Node.
559
562
  - _`data`_ - Data passed to the `{% slot %}` tag. See [Scoped Slots](#scoped-slots).
560
563
  - _`slot_ref`_ - The default slot content. See [Accessing original content of slots](#accessing-original-content-of-slots).
561
- - NOTE: The slot is lazily evaluated. To render the slot, convert it to string with `str(slot_ref)`.
564
+ - NOTE: The slot is lazily evaluated. To render the slot, convert it to string with `str(slot_ref)`.
562
565
 
563
566
  Example:
567
+
564
568
  ```py
565
569
  def footer_slot(ctx, data, slot_ref):
566
570
  return f"""
@@ -589,7 +593,7 @@ class MyResponse(HttpResponse):
589
593
  self.headers = ...
590
594
  self.status = ...
591
595
 
592
- class SimpleComponent(component.Component):
596
+ class SimpleComponent(Component):
593
597
  response_class = MyResponse
594
598
  template: types.django_html = "HELLO"
595
599
 
@@ -609,10 +613,10 @@ Here's an example of a calendar component defined as a view:
609
613
 
610
614
  ```python
611
615
  # In a file called [project root]/components/calendar.py
612
- from django_components import component
616
+ from django_components import Component, register
613
617
 
614
- @component.register("calendar")
615
- class Calendar(component.Component):
618
+ @register("calendar")
619
+ class Calendar(Component):
616
620
 
617
621
  template = """
618
622
  <div class="calendar-component">
@@ -664,15 +668,136 @@ Note: slots content are automatically escaped by default to prevent XSS attacks.
664
668
 
665
669
  If you're planning on passing an HTML string, check Django's use of [`format_html`](https://docs.djangoproject.com/en/5.0/ref/utils/#django.utils.html.format_html) and [`mark_safe`](https://docs.djangoproject.com/en/5.0/ref/utils/#django.utils.safestring.mark_safe).
666
670
 
671
+ ## Registering components
672
+
673
+ In previous examples you could repeatedly see us using `@register()` to "register"
674
+ the components. In this section we dive deeper into what it actually means and how you can
675
+ manage (add or remove) components.
676
+
677
+ As a reminder, we may have a component like this:
678
+
679
+ ```python
680
+ from django_components import Component, register
681
+
682
+ @register("calendar")
683
+ class Calendar(Component):
684
+ template_name = "template.html"
685
+
686
+ # This component takes one parameter, a date string to show in the template
687
+ def get_context_data(self, date):
688
+ return {
689
+ "date": date,
690
+ }
691
+ ```
692
+
693
+ which we then render in the template as:
694
+
695
+ ```django
696
+ {% component "calendar" date="1970-01-01" %}
697
+ {% endcomponent %}
698
+ ```
699
+
700
+ As you can see, `@register` links up the component class
701
+ with the `{% component %}` template tag. So when the template tag comes across
702
+ a component called `"calendar"`, it can look up it's class and instantiate it.
703
+
704
+ ### What is ComponentRegistry
705
+
706
+ The `@register` decorator is a shortcut for working with the `ComponentRegistry`.
707
+
708
+ `ComponentRegistry` manages which components can be used in the template tags.
709
+
710
+ Each `ComponentRegistry` instance is associated with an instance
711
+ of Django's `Library`. And Libraries are inserted into Django template
712
+ using the `{% load %}` tags.
713
+
714
+ The `@register` decorator accepts an optional kwarg `registry`, which specifies, the `ComponentRegistry` to register components into.
715
+ If omitted, the default `ComponentRegistry` instance defined in django_components is used.
716
+
717
+ ```py
718
+ my_registry = ComponentRegistry()
719
+
720
+ @register(registry=my_registry)
721
+ class MyComponent(Component):
722
+ ...
723
+ ```
724
+
725
+ The default `ComponentRegistry` is associated with the `Library` that
726
+ you load when you call `{% load component_tags %}` inside your template, or when you
727
+ add `django_components.templatetags.component_tags` to the template builtins.
728
+
729
+ So when you register or unregister a component to/from a component registry,
730
+ then behind the scenes the registry automatically adds/removes the component's
731
+ template tags to/from the Library, so you can call the component from within the templates
732
+ such as `{% component "my_comp" %}`.
733
+
734
+ ### Working with ComponentRegistry
735
+
736
+ The default `ComponentRegistry` instance can be imported as:
737
+
738
+ ```py
739
+ from django_components import registry
740
+ ```
741
+
742
+ You can use the registry to manually add/remove/get components:
743
+
744
+ ```py
745
+ from django_components import registry
746
+
747
+ # Register components
748
+ registry.register("button", ButtonComponent)
749
+ registry.register("card", CardComponent)
750
+
751
+ # Get all or single
752
+ registry.all() # {"button": ButtonComponent, "card": CardComponent}
753
+ registry.get("card") # CardComponent
754
+
755
+ # Unregister single component
756
+ registry.unregister("card")
757
+
758
+ # Unregister all components
759
+ registry.clear()
760
+ ```
761
+
762
+ ### Registering components to custom ComponentRegistry
763
+
764
+ In rare cases, you may want to manage your own instance of `ComponentRegistry`,
765
+ or register components onto a different `Library` instance than the default one.
766
+
767
+ The `Library` instance can be set at instantiation of `ComponentRegistry`. If omitted,
768
+ then the default Library instance from django_components is used.
769
+
770
+ ```py
771
+ from django.template import Library
772
+ from django_components import ComponentRegistry
773
+
774
+ my_library = Library(...)
775
+ my_registry = ComponentRegistry(library=my_library)
776
+ ```
777
+
778
+ When you have defined your own `ComponentRegistry`, you can either register the components
779
+ with `my_registry.register()`, or pass the registry to the `@component.register()` decorator
780
+ via the `registry` kwarg:
781
+
782
+ ```py
783
+ from path.to.my.registry import my_registry
784
+
785
+ @register("my_component", registry=my_registry)
786
+ class MyComponent(Component):
787
+ ...
788
+ ```
789
+
790
+ NOTE: The Library instance can be accessed under `library` attribute of `ComponentRegistry`.
791
+
667
792
  ## Autodiscovery
668
793
 
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:
794
+ 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 `@register` decorator for that:
670
795
 
671
796
  ```py
672
- from django_components import component
797
+ from django_components import Component, register
673
798
 
674
- @component.register("calendar")
675
- class Calendar(component.Component):
799
+ @register("calendar")
800
+ class Calendar(Component):
676
801
  ...
677
802
  ```
678
803
 
@@ -703,7 +828,7 @@ Autodiscovery occurs when Django is loaded, during the `ready` hook of the `apps
703
828
  If you are using autodiscovery, keep a few points in mind:
704
829
 
705
830
  - Avoid defining any logic on the module-level inside the `components` dir, that you would not want to run anyway.
706
- - Components inside the auto-imported files still need to be registered with `@component.register()`
831
+ - Components inside the auto-imported files still need to be registered with `@register()`
707
832
  - 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).
708
833
 
709
834
  Autodiscovery can be disabled in the [settings](#disable-autodiscovery).
@@ -808,12 +933,8 @@ The rendered result (exactly the same as before):
808
933
 
809
934
  ```html
810
935
  <div class="calendar-component">
811
- <div class="header">
812
- Calendar header
813
- </div>
814
- <div class="body">
815
- Can you believe it's already <span>2020-06-06</span>??
816
- </div>
936
+ <div class="header">Calendar header</div>
937
+ <div class="body">Can you believe it's already <span>2020-06-06</span>??</div>
817
938
  </div>
818
939
  ```
819
940
 
@@ -921,17 +1042,20 @@ Which you can then use are regular default slot:
921
1042
  _Added in version 0.26_
922
1043
 
923
1044
  > NOTE: In version 0.77, the syntax was changed from
1045
+ >
924
1046
  > ```django
925
1047
  > {% fill "my_slot" as "alias" %} {{ alias.default }}
926
1048
  > ```
1049
+ >
927
1050
  > to
1051
+ >
928
1052
  > ```django
929
1053
  > {% fill "my_slot" default="slot_default" %} {{ slot_default }}
930
1054
  > ```
931
1055
 
932
1056
  Sometimes you may want to keep the original slot, but only wrap or prepend/append content to it. To do so, you can access the default slot via the `default` kwarg.
933
1057
 
934
- Similarly to the `data` attribute, you specify the variable name through which the default slot will be made available.
1058
+ Similarly to the `data` attribute, you specify the variable name through which the default slot will be made available.
935
1059
 
936
1060
  For instance, let's say you're filling a slot called 'body'. To render the original slot, assign it to a variable using the `'default'` keyword. You then render this variable to insert the default content:
937
1061
 
@@ -983,11 +1107,8 @@ explicit fills, the div containing the slot is still rendered, as shown below:
983
1107
 
984
1108
  ```html
985
1109
  <div class="frontmatter-component">
986
- <div class="title">
987
- Title
988
- </div>
989
- <div class="subtitle">
990
- </div>
1110
+ <div class="title">Title</div>
1111
+ <div class="subtitle"></div>
991
1112
  </div>
992
1113
  ```
993
1114
 
@@ -1057,8 +1178,8 @@ _Added in version 0.76_:
1057
1178
  Consider a component with slot(s). This component may do some processing on the inputs, and then use the processed variable in the slot's default template:
1058
1179
 
1059
1180
  ```py
1060
- @component.register("my_comp")
1061
- class MyComp(component.Component):
1181
+ @register("my_comp")
1182
+ class MyComp(Component):
1062
1183
  template = """
1063
1184
  <div>
1064
1185
  {% slot "content" default %}
@@ -1086,8 +1207,8 @@ Using scoped slots consists of two steps:
1086
1207
  To pass the data to the `slot` tag, simply pass them as keyword attributes (`key=value`):
1087
1208
 
1088
1209
  ```py
1089
- @component.register("my_comp")
1090
- class MyComp(component.Component):
1210
+ @register("my_comp")
1211
+ class MyComp(Component):
1091
1212
  template = """
1092
1213
  <div>
1093
1214
  {% slot "content" default input=input %}
@@ -1177,8 +1298,8 @@ so are still valid:
1177
1298
  These can then be accessed inside `get_context_data` so:
1178
1299
 
1179
1300
  ```py
1180
- @component.register("calendar")
1181
- class Calendar(component.Component):
1301
+ @register("calendar")
1302
+ class Calendar(Component):
1182
1303
  # Since # . @ - are not valid identifiers, we have to
1183
1304
  # use `**kwargs` so the method can accept these args.
1184
1305
  def get_context_data(self, **kwargs):
@@ -1202,8 +1323,8 @@ In such cases, we may want to define some HTML attributes statically, and other
1202
1323
  But for that, we need to define this dictionary on Python side:
1203
1324
 
1204
1325
  ```py
1205
- @component.register("my_comp")
1206
- class MyComp(component.Component):
1326
+ @register("my_comp")
1327
+ class MyComp(Component):
1207
1328
  template = """
1208
1329
  {% component "other" attrs=attrs %}
1209
1330
  {% endcomponent %}
@@ -1230,8 +1351,8 @@ we prefix the key with the name of the dict and `:`. So key `class` of input `at
1230
1351
  `attrs:class`. And our example becomes:
1231
1352
 
1232
1353
  ```py
1233
- @component.register("my_comp")
1234
- class MyComp(component.Component):
1354
+ @register("my_comp")
1355
+ class MyComp(Component):
1235
1356
  template = """
1236
1357
  {% component "other"
1237
1358
  attrs:class="pa-4 flex"
@@ -1320,8 +1441,7 @@ And template:
1320
1441
  Then this renders:
1321
1442
 
1322
1443
  ```html
1323
- <div class="text-green">
1324
- </div>
1444
+ <div class="text-green"></div>
1325
1445
  ```
1326
1446
 
1327
1447
  ### Boolean attributes
@@ -1329,8 +1449,7 @@ Then this renders:
1329
1449
  In HTML, boolean attributes are usually rendered with no value. Consider the example below where the first button is disabled and the second is not:
1330
1450
 
1331
1451
  ```html
1332
- <button disabled> Click me! </button>
1333
- <button> Click me! </button>
1452
+ <button disabled>Click me!</button> <button>Click me!</button>
1334
1453
  ```
1335
1454
 
1336
1455
  HTML rendering with `html_attrs` tag or `attributes_to_string` works the same way, where `key=True` is rendered simply as `key`, and `key=False` is not render at all.
@@ -1354,8 +1473,7 @@ And template:
1354
1473
  Then this renders:
1355
1474
 
1356
1475
  ```html
1357
- <div disabled>
1358
- </div>
1476
+ <div disabled></div>
1359
1477
  ```
1360
1478
 
1361
1479
  ### Default attributes
@@ -1404,8 +1522,7 @@ And on `html_attrs` tag, we set the key `class`:
1404
1522
  Then these will be merged and rendered as:
1405
1523
 
1406
1524
  ```html
1407
- <div data-value="my-class pa-4 some-class">
1408
- </div>
1525
+ <div data-value="my-class pa-4 some-class"></div>
1409
1526
  ```
1410
1527
 
1411
1528
  To simplify merging of variables, you can supply the same key multiple times, and these will be all joined together:
@@ -1523,8 +1640,8 @@ Then:
1523
1640
  ### Full example for `html_attrs`
1524
1641
 
1525
1642
  ```py
1526
- @component.register("my_comp")
1527
- class MyComp(component.Component):
1643
+ @register("my_comp")
1644
+ class MyComp(Component):
1528
1645
  template: t.django_html = """
1529
1646
  <div
1530
1647
  {% html_attrs attrs
@@ -1545,8 +1662,8 @@ class MyComp(component.Component):
1545
1662
  "class_from_var": "extra-class"
1546
1663
  }
1547
1664
 
1548
- @component.register("parent")
1549
- class Parent(component.Component):
1665
+ @register("parent")
1666
+ class Parent(Component):
1550
1667
  template: t.django_html = """
1551
1668
  {% component "my_comp"
1552
1669
  date=date
@@ -1579,8 +1696,7 @@ will be appended to it.
1579
1696
  So by default, `MyComp` renders:
1580
1697
 
1581
1698
  ```html
1582
- <div class="pa-4 text-red my-comp-date extra-class" data-id="123">
1583
- ...
1699
+ <div class="pa-4 text-red my-comp-date extra-class" data-id="123">...</div>
1584
1700
  ```
1585
1701
 
1586
1702
  Next, let's consider what will be rendered when we call `MyComp` from `Parent`
@@ -1650,6 +1766,7 @@ attributes_to_string(attrs)
1650
1766
  _New in version 0.80_:
1651
1767
 
1652
1768
  Django components supports dependency injection with the combination of:
1769
+
1653
1770
  1. `{% provide %}` tag
1654
1771
  1. `inject()` method of the `Component` class
1655
1772
 
@@ -1670,6 +1787,7 @@ This feature is inspired by Vue's [Provide / Inject](https://vuejs.org/guide/com
1670
1787
  ### How to use provide / inject
1671
1788
 
1672
1789
  As the name suggest, using provide / inject consists of 2 steps
1790
+
1673
1791
  1. Providing data
1674
1792
  2. Injecting provided data
1675
1793
 
@@ -1692,6 +1810,7 @@ First we use the `{% provide %}` tag to define the data we want to "provide" (ma
1692
1810
  Notice that the `provide` tag REQUIRES a name as a first argument. This is the _key_ by which we can then access the data passed to this tag.
1693
1811
 
1694
1812
  `provide` tag _key_, similarly to the _name_ argument in `component` or `slot` tags, has these requirements:
1813
+
1695
1814
  - The _key_ must be a string literal
1696
1815
  - It must be a valid identifier (AKA a valid Python variable name)
1697
1816
 
@@ -1699,9 +1818,10 @@ Once you've set the name, you define the data you want to "provide" by passing i
1699
1818
 
1700
1819
  > NOTE: Kwargs passed to `{% provide %}` are NOT added to the context.
1701
1820
  > In the example below, the `{{ key }}` won't render anything:
1821
+ >
1702
1822
  > ```django
1703
1823
  > {% provide "my_data" key="hi" another=123 %}
1704
- > {{ key }}
1824
+ > {{ key }}
1705
1825
  > {% endprovide %}
1706
1826
  > ```
1707
1827
 
@@ -1714,7 +1834,7 @@ For a component to be able to "inject" some data, the component (`{% component %
1714
1834
  In the example from previous section, we've defined two kwargs: `key="hi" another=123`. That means that if we now inject `"my_data"`, we get an object with 2 attributes - `key` and `another`.
1715
1835
 
1716
1836
  ```py
1717
- class ChildComponent(component.Component):
1837
+ class ChildComponent(Component):
1718
1838
  def get_context_data(self):
1719
1839
  my_data = self.inject("my_data")
1720
1840
  print(my_data.key) # hi
@@ -1729,7 +1849,7 @@ with given key is found, `inject` raises a `KeyError`.
1729
1849
  To avoid the error, you can pass a second argument to `inject` to which will act as a default value, similar to `dict.get(key, default)`:
1730
1850
 
1731
1851
  ```py
1732
- class ChildComponent(component.Component):
1852
+ class ChildComponent(Component):
1733
1853
  def get_context_data(self):
1734
1854
  my_data = self.inject("invalid_key", DEFAULT_DATA)
1735
1855
  assert my_data == DEFAUKT_DATA
@@ -1741,12 +1861,11 @@ have all the keys that were passed to the `provide` tag.
1741
1861
 
1742
1862
  > NOTE: `inject()` works strictly only in `get_context_data`. If you try to call it from elsewhere, it will raise an error.
1743
1863
 
1744
-
1745
1864
  ### Full example
1746
1865
 
1747
1866
  ```py
1748
- @component.register("child")
1749
- class ChildComponent(component.Component):
1867
+ @register("child")
1868
+ class ChildComponent(Component):
1750
1869
  template = """
1751
1870
  <div> {{ my_data.key }} </div>
1752
1871
  <div> {{ my_data.another }} </div>
@@ -1768,15 +1887,15 @@ template_str = """
1768
1887
  renders:
1769
1888
 
1770
1889
  ```html
1771
- <div> hi </div>
1772
- <div> 123 </div>
1890
+ <div>hi</div>
1891
+ <div>123</div>
1773
1892
  ```
1774
1893
 
1775
1894
  ## Component context and scope
1776
1895
 
1777
1896
  By default, context variables are passed down the template as in regular Django - deeper scopes can access the variables from the outer scopes. So if you have several nested forloops, then inside the deep-most loop you can access variables defined by all previous loops.
1778
1897
 
1779
- With this in mind, the `{% component %}` tag behaves similarly to `{% include %}` tag - inside the component tag, you can access all variables that were defined outside of it.
1898
+ With this in mind, the `{% component %}` tag behaves similarly to `{% include %}` tag - inside the component tag, you can access all variables that were defined outside of it.
1780
1899
 
1781
1900
  And just like with `{% include %}`, if you don't want a specific component template to have access to the parent context, add `only` to the end of the `{% component %}` tag:
1782
1901
 
@@ -1795,6 +1914,7 @@ Components can also access the outer context in their context methods like `get_
1795
1914
  django_component's management of files builds on top of [Django's `Media` class](https://docs.djangoproject.com/en/5.0/topics/forms/media/).
1796
1915
 
1797
1916
  To be familiar with how Django handles static files, we recommend reading also:
1917
+
1798
1918
  - [How to manage static files (e.g. images, JavaScript, CSS)](https://docs.djangoproject.com/en/5.0/howto/static-files/)
1799
1919
 
1800
1920
  ### Defining file paths relative to component or static dirs
@@ -1804,10 +1924,10 @@ files with a component, you set them as `template_name`, `Media.js` and `Media.c
1804
1924
 
1805
1925
  ```py
1806
1926
  # In a file [project root]/components/calendar/calendar.py
1807
- from django_components import component
1927
+ from django_components import Component, register
1808
1928
 
1809
- @component.register("calendar")
1810
- class Calendar(component.Component):
1929
+ @register("calendar")
1930
+ class Calendar(Component):
1811
1931
  template_name = "template.html"
1812
1932
 
1813
1933
  class Media:
@@ -1823,10 +1943,10 @@ Assuming that `STATICFILES_DIRS` contains path `[project root]/components`, we c
1823
1943
 
1824
1944
  ```py
1825
1945
  # In a file [project root]/components/calendar/calendar.py
1826
- from django_components import component
1946
+ from django_components import Component, register
1827
1947
 
1828
- @component.register("calendar")
1829
- class Calendar(component.Component):
1948
+ @register("calendar")
1949
+ class Calendar(Component):
1830
1950
  template_name = "calendar/template.html"
1831
1951
 
1832
1952
  class Media:
@@ -1841,7 +1961,7 @@ NOTE: In case of conflict, the preference goes to resolving the files relative t
1841
1961
  Each component can have only a single template. However, you can define as many JS or CSS files as you want using a list.
1842
1962
 
1843
1963
  ```py
1844
- class MyComponent(component.Component):
1964
+ class MyComponent(Component):
1845
1965
  class Media:
1846
1966
  js = ["path/to/script1.js", "path/to/script2.js"]
1847
1967
  css = ["path/to/style1.css", "path/to/style2.css"]
@@ -1857,7 +1977,7 @@ See the corresponding [Django Documentation](https://docs.djangoproject.com/en/5
1857
1977
  Again, you can set either a single file or a list of files per media type:
1858
1978
 
1859
1979
  ```py
1860
- class MyComponent(component.Component):
1980
+ class MyComponent(Component):
1861
1981
  class Media:
1862
1982
  css = {
1863
1983
  "all": "path/to/style1.css",
@@ -1866,7 +1986,7 @@ class MyComponent(component.Component):
1866
1986
  ```
1867
1987
 
1868
1988
  ```py
1869
- class MyComponent(component.Component):
1989
+ class MyComponent(Component):
1870
1990
  class Media:
1871
1991
  css = {
1872
1992
  "all": ["path/to/style1.css", "path/to/style2.css"],
@@ -1876,10 +1996,10 @@ class MyComponent(component.Component):
1876
1996
 
1877
1997
  NOTE: When you define CSS as a string or a list, the `all` media type is implied.
1878
1998
 
1879
-
1880
1999
  ### Supported types for file paths
1881
2000
 
1882
2001
  File paths can be any of:
2002
+
1883
2003
  - `str`
1884
2004
  - `bytes`
1885
2005
  - `PathLike` (`__fspath__` method)
@@ -1891,7 +2011,7 @@ from pathlib import Path
1891
2011
 
1892
2012
  from django.utils.safestring import mark_safe
1893
2013
 
1894
- class SimpleComponent(component.Component):
2014
+ class SimpleComponent(Component):
1895
2015
  class Media:
1896
2016
  css = [
1897
2017
  mark_safe('<link href="/static/calendar/style.css" rel="stylesheet" />'),
@@ -1930,8 +2050,8 @@ class LazyJsPath:
1930
2050
  f'<script type="module" src="{full_path}"></script>'
1931
2051
  )
1932
2052
 
1933
- @component.register("calendar")
1934
- class Calendar(component.Component):
2053
+ @register("calendar")
2054
+ class Calendar(Component):
1935
2055
  template_name = "calendar/template.html"
1936
2056
 
1937
2057
  def get_context_data(self, date):
@@ -1943,7 +2063,7 @@ class Calendar(component.Component):
1943
2063
  css = "calendar/style.css"
1944
2064
  js = [
1945
2065
  # <script> tag constructed by Media class
1946
- "calendar/script1.js",
2066
+ "calendar/script1.js",
1947
2067
  # Custom <script> tag
1948
2068
  LazyJsPath("calendar/script2.js"),
1949
2069
  ]
@@ -1959,7 +2079,7 @@ To change how the tags are constructed, you can override the [`Media.render_js`
1959
2079
 
1960
2080
  ```py
1961
2081
  from django.forms.widgets import Media
1962
- from django_components import component
2082
+ from django_components import Component, register
1963
2083
 
1964
2084
  class MyMedia(Media):
1965
2085
  # Same as original Media.render_js, except
@@ -1976,14 +2096,14 @@ class MyMedia(Media):
1976
2096
  )
1977
2097
  return tags
1978
2098
 
1979
- @component.register("calendar")
1980
- class Calendar(component.Component):
2099
+ @register("calendar")
2100
+ class Calendar(Component):
1981
2101
  template_name = "calendar/template.html"
1982
2102
 
1983
2103
  class Media:
1984
2104
  css = "calendar/style.css"
1985
2105
  js = "calendar/script.js"
1986
-
2106
+
1987
2107
  # Override the behavior of Media class
1988
2108
  media_class = MyMedia
1989
2109
  ```
@@ -1994,6 +2114,7 @@ NOTE: The instance of the `Media` class (or it's subclass) is available under `C
1994
2114
 
1995
2115
  The JS and CSS files included in components are not automatically rendered.
1996
2116
  Instead, use the following tags to specify where to render the dependencies:
2117
+
1997
2118
  - `component_dependencies` - Renders both JS and CSS
1998
2119
  - `component_js_dependencies` - Renders only JS
1999
2120
  - `component_css_dependencies` - Reneders only CSS
@@ -2045,16 +2166,16 @@ COMPONENTS = {
2045
2166
  Where `mysite/components/forms.py` may look like this:
2046
2167
 
2047
2168
  ```py
2048
- @component.register("form_simple")
2049
- class FormSimple(component.Component):
2169
+ @register("form_simple")
2170
+ class FormSimple(Component):
2050
2171
  template = """
2051
2172
  <form>
2052
2173
  ...
2053
2174
  </form>
2054
2175
  """
2055
2176
 
2056
- @component.register("form_other")
2057
- class FormOther(component.Component):
2177
+ @register("form_other")
2178
+ class FormOther(Component):
2058
2179
  template = """
2059
2180
  <form>
2060
2181
  ...
@@ -2104,15 +2225,17 @@ This has two modes:
2104
2225
 
2105
2226
  - `"django"` - Default - The default Django template behavior.
2106
2227
 
2107
- Inside the `{% fill %}` tag, the context variables you can access are a union of:
2108
- - All the variables that were OUTSIDE the fill tag, including any loops or with tag
2109
- - Data returned from `get_context_data()` of the component that wraps the fill tag.
2228
+ Inside the `{% fill %}` tag, the context variables you can access are a union of:
2229
+
2230
+ - All the variables that were OUTSIDE the fill tag, including any loops or with tag
2231
+ - Data returned from `get_context_data()` of the component that wraps the fill tag.
2110
2232
 
2111
2233
  - `"isolated"` - Similar behavior to [Vue](https://vuejs.org/guide/components/slots.html#render-scope) or React, this is useful if you want to make sure that components don't accidentally access variables defined outside of the component.
2112
2234
 
2113
- Inside the `{% fill %}` tag, you can ONLY access variables from 2 places:
2114
- - `get_context_data()` of the component which defined the template (AKA the "root" component)
2115
- - Any loops (`{% for ... %}`) that the `{% fill %}` tag is part of.
2235
+ Inside the `{% fill %}` tag, you can ONLY access variables from 2 places:
2236
+
2237
+ - `get_context_data()` of the component which defined the template (AKA the "root" component)
2238
+ - Any loops (`{% for ... %}`) that the `{% fill %}` tag is part of.
2116
2239
 
2117
2240
  ```python
2118
2241
  COMPONENTS = {
@@ -2125,7 +2248,7 @@ COMPONENTS = {
2125
2248
  Given this template:
2126
2249
 
2127
2250
  ```py
2128
- class RootComp(component.Component):
2251
+ class RootComp(Component):
2129
2252
  template = """
2130
2253
  {% with cheese="feta" %}
2131
2254
  {% component 'my_comp' %}
@@ -2162,7 +2285,7 @@ all the data defined in the outer layers, like the `{% with %}` tag.
2162
2285
  Given this template:
2163
2286
 
2164
2287
  ```py
2165
- class RootComp(component.Component):
2288
+ class RootComp(Component):
2166
2289
  template = """
2167
2290
  {% with cheese="feta" %}
2168
2291
  {% component 'my_comp' %}