django-components 0.95__tar.gz → 0.96__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 (65) hide show
  1. {django_components-0.95/src/django_components.egg-info → django_components-0.96}/PKG-INFO +286 -54
  2. {django_components-0.95 → django_components-0.96}/README.md +285 -53
  3. {django_components-0.95 → django_components-0.96}/pyproject.toml +1 -1
  4. {django_components-0.95 → django_components-0.96}/src/django_components/__init__.py +4 -0
  5. {django_components-0.95 → django_components-0.96}/src/django_components/component.py +205 -28
  6. {django_components-0.95 → django_components-0.96}/src/django_components/slots.py +2 -0
  7. {django_components-0.95 → django_components-0.96}/src/django_components/types.py +14 -1
  8. django_components-0.96/src/django_components/utils.py +168 -0
  9. {django_components-0.95 → django_components-0.96/src/django_components.egg-info}/PKG-INFO +286 -54
  10. {django_components-0.95 → django_components-0.96}/tests/test_component.py +577 -37
  11. {django_components-0.95 → django_components-0.96}/tests/test_context.py +50 -17
  12. django_components-0.95/src/django_components/utils.py +0 -38
  13. {django_components-0.95 → django_components-0.96}/LICENSE +0 -0
  14. {django_components-0.95 → django_components-0.96}/setup.cfg +0 -0
  15. {django_components-0.95 → django_components-0.96}/src/django_components/app_settings.py +0 -0
  16. {django_components-0.95 → django_components-0.96}/src/django_components/apps.py +0 -0
  17. {django_components-0.95 → django_components-0.96}/src/django_components/attributes.py +0 -0
  18. {django_components-0.95 → django_components-0.96}/src/django_components/autodiscover.py +0 -0
  19. {django_components-0.95 → django_components-0.96}/src/django_components/component_media.py +0 -0
  20. {django_components-0.95 → django_components-0.96}/src/django_components/component_registry.py +0 -0
  21. {django_components-0.95 → django_components-0.96}/src/django_components/components/__init__.py +0 -0
  22. {django_components-0.95 → django_components-0.96}/src/django_components/components/dynamic.py +0 -0
  23. {django_components-0.95 → django_components-0.96}/src/django_components/context.py +0 -0
  24. {django_components-0.95 → django_components-0.96}/src/django_components/expression.py +0 -0
  25. {django_components-0.95 → django_components-0.96}/src/django_components/library.py +0 -0
  26. {django_components-0.95 → django_components-0.96}/src/django_components/logger.py +0 -0
  27. {django_components-0.95 → django_components-0.96}/src/django_components/management/__init__.py +0 -0
  28. {django_components-0.95 → django_components-0.96}/src/django_components/management/commands/__init__.py +0 -0
  29. {django_components-0.95 → django_components-0.96}/src/django_components/management/commands/startcomponent.py +0 -0
  30. {django_components-0.95 → django_components-0.96}/src/django_components/management/commands/upgradecomponent.py +0 -0
  31. {django_components-0.95 → django_components-0.96}/src/django_components/middleware.py +0 -0
  32. {django_components-0.95 → django_components-0.96}/src/django_components/node.py +0 -0
  33. {django_components-0.95 → django_components-0.96}/src/django_components/provide.py +0 -0
  34. {django_components-0.95 → django_components-0.96}/src/django_components/py.typed +0 -0
  35. {django_components-0.95 → django_components-0.96}/src/django_components/safer_staticfiles/__init__.py +0 -0
  36. {django_components-0.95 → django_components-0.96}/src/django_components/safer_staticfiles/apps.py +0 -0
  37. {django_components-0.95 → django_components-0.96}/src/django_components/tag_formatter.py +0 -0
  38. {django_components-0.95 → django_components-0.96}/src/django_components/template_loader.py +0 -0
  39. {django_components-0.95 → django_components-0.96}/src/django_components/template_parser.py +0 -0
  40. {django_components-0.95 → django_components-0.96}/src/django_components/templatetags/__init__.py +0 -0
  41. {django_components-0.95 → django_components-0.96}/src/django_components/templatetags/component_tags.py +0 -0
  42. {django_components-0.95 → django_components-0.96}/src/django_components.egg-info/SOURCES.txt +0 -0
  43. {django_components-0.95 → django_components-0.96}/src/django_components.egg-info/dependency_links.txt +0 -0
  44. {django_components-0.95 → django_components-0.96}/src/django_components.egg-info/requires.txt +0 -0
  45. {django_components-0.95 → django_components-0.96}/src/django_components.egg-info/top_level.txt +0 -0
  46. {django_components-0.95 → django_components-0.96}/tests/test_attributes.py +0 -0
  47. {django_components-0.95 → django_components-0.96}/tests/test_autodiscover.py +0 -0
  48. {django_components-0.95 → django_components-0.96}/tests/test_command_startcomponent.py +0 -0
  49. {django_components-0.95 → django_components-0.96}/tests/test_component_as_view.py +0 -0
  50. {django_components-0.95 → django_components-0.96}/tests/test_component_media.py +0 -0
  51. {django_components-0.95 → django_components-0.96}/tests/test_dependency_rendering.py +0 -0
  52. {django_components-0.95 → django_components-0.96}/tests/test_expression.py +0 -0
  53. {django_components-0.95 → django_components-0.96}/tests/test_registry.py +0 -0
  54. {django_components-0.95 → django_components-0.96}/tests/test_safer_staticfiles.py +0 -0
  55. {django_components-0.95 → django_components-0.96}/tests/test_settings.py +0 -0
  56. {django_components-0.95 → django_components-0.96}/tests/test_tag_formatter.py +0 -0
  57. {django_components-0.95 → django_components-0.96}/tests/test_template_loader.py +0 -0
  58. {django_components-0.95 → django_components-0.96}/tests/test_template_parser.py +0 -0
  59. {django_components-0.95 → django_components-0.96}/tests/test_templatetags.py +0 -0
  60. {django_components-0.95 → django_components-0.96}/tests/test_templatetags_component.py +0 -0
  61. {django_components-0.95 → django_components-0.96}/tests/test_templatetags_provide.py +0 -0
  62. {django_components-0.95 → django_components-0.96}/tests/test_templatetags_slot_fill.py +0 -0
  63. {django_components-0.95 → django_components-0.96}/tests/test_templatetags_templating.py +0 -0
  64. {django_components-0.95 → django_components-0.96}/tests/test_utils.py +0 -0
  65. {django_components-0.95 → django_components-0.96}/tests/testutils.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: django_components
3
- Version: 0.95
3
+ Version: 0.96
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
@@ -69,6 +69,7 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
69
69
  - [Use components in templates](#use-components-in-templates)
70
70
  - [Use components outside of templates](#use-components-outside-of-templates)
71
71
  - [Use components as views](#use-components-as-views)
72
+ - [Typing and validating components](#typing-and-validating-components)
72
73
  - [Pre-defined components](#pre-defined-components)
73
74
  - [Registering components](#registering-components)
74
75
  - [Autodiscovery](#autodiscovery)
@@ -77,7 +78,9 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
77
78
  - [Rendering HTML attributes](#rendering-html-attributes)
78
79
  - [Template tag syntax](#template-tag-syntax)
79
80
  - [Prop drilling and dependency injection (provide / inject)](#prop-drilling-and-dependency-injection-provide--inject)
81
+ - [Component hooks](#component-hooks)
80
82
  - [Component context and scope](#component-context-and-scope)
83
+ - [Pre-defined template variables](#pre-defined-template-variables)
81
84
  - [Customizing component tags with TagFormatter](#customizing-component-tags-with-tagformatter)
82
85
  - [Defining HTML/JS/CSS files](#defining-htmljscss-files)
83
86
  - [Rendering JS/CSS dependencies](#rendering-jscss-dependencies)
@@ -92,6 +95,11 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
92
95
 
93
96
  ## Release notes
94
97
 
98
+ **Version 0.96**
99
+ - Run-time type validation for Python 3.11+ - If the `Component` class is typed, e.g. `Component[Args, Kwargs, ...]`, the args, kwargs, slots, and data are validated against the given types. (See [Runtime input validation with types](#runtime-input-validation-with-types))
100
+ - Render hooks - Set `on_render_before` and `on_render_after` methods on `Component` to intercept or modify the template or context before rendering, or the rendered result afterwards. (See [Component hooks](#component-hooks))
101
+ - `component_vars.is_filled` context variable can be accessed from within `on_render_before` and `on_render_after` hooks as `self.is_filled.my_slot`
102
+
95
103
  **Version 0.95**
96
104
  - Added support for dynamic components, where the component name is passed as a variable. (See [Dynamic components](#dynamic-components))
97
105
  - Changed `Component.input` to raise `RuntimeError` if accessed outside of render context. Previously it returned `None` if unset.
@@ -656,58 +664,6 @@ MyComponent.render_to_response(
656
664
  )
657
665
  ```
658
666
 
659
- ### Adding type hints with Generics
660
-
661
- The `Component` class optionally accepts type parameters
662
- that allow you to specify the types of args, kwargs, slots, and
663
- data.
664
-
665
- ```py
666
- from typing import NotRequired, Tuple, TypedDict, SlotFunc
667
-
668
- # Positional inputs - Tuple
669
- Args = Tuple[int, str]
670
-
671
- # Kwargs inputs - Mapping
672
- class Kwargs(TypedDict):
673
- variable: str
674
- another: int
675
- maybe_var: NotRequired[int]
676
-
677
- # Data returned from `get_context_data` - Mapping
678
- class Data(TypedDict):
679
- variable: str
680
-
681
- # The data available to the `my_slot` scoped slot
682
- class MySlotData(TypedDict):
683
- value: int
684
-
685
- # Slot functions - Mapping
686
- class Slots(TypedDict):
687
- # Use SlotFunc for slot functions.
688
- # The generic specifies the `data` dictionary
689
- my_slot: NotRequired[SlotFunc[MySlotData]]
690
-
691
- class Button(Component[Args, Kwargs, Data, Slots]):
692
- def get_context_data(self, variable, another):
693
- return {
694
- "variable": variable,
695
- }
696
- ```
697
-
698
- When you then call `Component.render` or `Component.render_to_response`, you will get type hints:
699
-
700
- ```py
701
- Button.render(
702
- # Error: First arg must be `int`, got `float`
703
- args=(1.25, "abc"),
704
- # Error: Key "another" is missing
705
- kwargs={
706
- "variable": "text",
707
- },
708
- )
709
- ```
710
-
711
667
  ### Response class of `render_to_response`
712
668
 
713
669
  While `render` method returns a plain string, `render_to_response` wraps the rendered content in a "Response" class. By default, this is `django.http.HttpResponse`.
@@ -879,6 +835,182 @@ class MyComponent(Component):
879
835
  do_something_extra(request, *args, **kwargs)
880
836
  ```
881
837
 
838
+ ## Typing and validating components
839
+
840
+ ### Adding type hints with Generics
841
+
842
+ _New in version 0.92_
843
+
844
+ The `Component` class optionally accepts type parameters
845
+ that allow you to specify the types of args, kwargs, slots, and
846
+ data:
847
+
848
+ ```py
849
+ class Button(Component[Args, Kwargs, Data, Slots]):
850
+ ...
851
+ ```
852
+
853
+ - `Args` - Must be a `Tuple` or `Any`
854
+ - `Kwargs` - Must be a `TypedDict` or `Any`
855
+ - `Data` - Must be a `TypedDict` or `Any`
856
+ - `Slots` - Must be a `TypedDict` or `Any`
857
+
858
+ Here's a full example:
859
+
860
+ ```py
861
+ from typing import NotRequired, Tuple, TypedDict, SlotContent, SlotFunc
862
+
863
+ # Positional inputs
864
+ Args = Tuple[int, str]
865
+
866
+ # Kwargs inputs
867
+ class Kwargs(TypedDict):
868
+ variable: str
869
+ another: int
870
+ maybe_var: NotRequired[int] # May be ommited
871
+
872
+ # Data returned from `get_context_data`
873
+ class Data(TypedDict):
874
+ variable: str
875
+
876
+ # The data available to the `my_slot` scoped slot
877
+ class MySlotData(TypedDict):
878
+ value: int
879
+
880
+ # Slots
881
+ class Slots(TypedDict):
882
+ # Use SlotFunc for slot functions.
883
+ # The generic specifies the `data` dictionary
884
+ my_slot: NotRequired[SlotFunc[MySlotData]]
885
+ # SlotContent == Union[str, SafeString]
886
+ another_slot: SlotContent
887
+
888
+ class Button(Component[Args, Kwargs, Data, Slots]):
889
+ def get_context_data(self, variable, another):
890
+ return {
891
+ "variable": variable,
892
+ }
893
+ ```
894
+
895
+ When you then call `Component.render` or `Component.render_to_response`, you will get type hints:
896
+
897
+ ```py
898
+ Button.render(
899
+ # Error: First arg must be `int`, got `float`
900
+ args=(1.25, "abc"),
901
+ # Error: Key "another" is missing
902
+ kwargs={
903
+ "variable": "text",
904
+ },
905
+ )
906
+ ```
907
+
908
+ #### Usage for Python <3.11
909
+
910
+ On Python 3.8-3.10, use `typing_extensions`
911
+
912
+ ```py
913
+ from typing_extensions import TypedDict, NotRequired
914
+ ```
915
+
916
+ Additionally on Python 3.8-3.9, also import `annotations`:
917
+
918
+ ```py
919
+ from __future__ import annotations
920
+ ```
921
+
922
+ Moreover, on 3.10 and less, you may not be able to use `NotRequired`, and instead you will need to mark either all keys are required, or all keys as optional, using TypeDict's `total` kwarg.
923
+
924
+ [See PEP-655](https://peps.python.org/pep-0655) for more info.
925
+
926
+
927
+ ### Passing additional args or kwargs
928
+
929
+ You may have a function that supports any number of args or kwargs:
930
+
931
+ ```py
932
+ def get_context_data(self, *args, **kwargs):
933
+ ...
934
+ ```
935
+
936
+ This is not supported with the typed components.
937
+
938
+ As a workaround:
939
+ - For `*args`, set a positional argument that accepts a list of values:
940
+
941
+ ```py
942
+ # Tuple of one member of list of strings
943
+ Args = Tuple[List[str]]
944
+ ```
945
+
946
+ - For `*kwargs`, set a keyword argument that accepts a dictionary of values:
947
+
948
+ ```py
949
+ class Kwargs(TypedDict):
950
+ variable: str
951
+ another: int
952
+ # Pass any extra keys under `extra`
953
+ extra: Dict[str, any]
954
+ ```
955
+
956
+ ### Handling no args or no kwargs
957
+
958
+ To declare that a component accepts no Args, Kwargs, etc, you can use `EmptyTuple` and `EmptyDict` types:
959
+
960
+ ```py
961
+ from django_components import Component, EmptyDict, EmptyTuple
962
+
963
+ Args = EmptyTuple
964
+ Kwargs = Data = Slots = EmptyDict
965
+
966
+ class Button(Component[Args, Kwargs, Data, Slots]):
967
+ ...
968
+ ```
969
+
970
+ ### Runtime input validation with types
971
+
972
+ _New in version 0.96_
973
+
974
+ > NOTE: Kwargs, slots, and data validation is supported only for Python >=3.11
975
+
976
+ In Python 3.11 and later, when you specify the component types, you will get also runtime validation of the inputs you pass to `Component.render` or `Component.render_to_response`.
977
+
978
+ So, using the example from before, if you ignored the type errors and still ran the following code:
979
+
980
+ ```py
981
+ Button.render(
982
+ # Error: First arg must be `int`, got `float`
983
+ args=(1.25, "abc"),
984
+ # Error: Key "another" is missing
985
+ kwargs={
986
+ "variable": "text",
987
+ },
988
+ )
989
+ ```
990
+
991
+ This would raise a `TypeError`:
992
+
993
+ ```txt
994
+ Component 'Button' expected positional argument at index 0 to be <class 'int'>, got 1.25 of type <class 'float'>
995
+ ```
996
+
997
+ In case you need to skip these errors, you can either set the faulty member to `Any`, e.g.:
998
+
999
+ ```py
1000
+ # Changed `int` to `Any`
1001
+ Args = Tuple[Any, str]
1002
+ ```
1003
+
1004
+ Or you can replace `Args` with `Any` altogether, to skip the validation of args:
1005
+
1006
+ ```py
1007
+ # Replaced `Args` with `Any`
1008
+ class Button(Component[Any, Kwargs, Data, Slots]):
1009
+ ...
1010
+ ```
1011
+
1012
+ Same applies to kwargs, data, and slots.
1013
+
882
1014
  ## Pre-defined components
883
1015
 
884
1016
  ### Dynamic components
@@ -1371,7 +1503,7 @@ This produces:
1371
1503
 
1372
1504
  _Added in version 0.26._
1373
1505
 
1374
- > NOTE: In version 0.70, `{% if_filled %}` tags were replaced with `{{ component_vars.is_filled }}` variables. If your slot name contained special characters, see the section "Accessing slot names with special characters".
1506
+ > NOTE: In version 0.70, `{% if_filled %}` tags were replaced with `{{ component_vars.is_filled }}` variables. If your slot name contained special characters, see the section [Accessing `is_filled` of slot names with special characters](#accessing-is_filled-of-slot-names-with-special-characters).
1375
1507
 
1376
1508
  In certain circumstances, you may want the behavior of slot filling to depend on
1377
1509
  whether or not a particular slot is filled.
@@ -2456,6 +2588,88 @@ renders:
2456
2588
  <div>123</div>
2457
2589
  ```
2458
2590
 
2591
+ ## Component hooks
2592
+
2593
+ _New in version 0.96_
2594
+
2595
+ Component hooks are functions that allow you to intercept the rendering process at specific positions.
2596
+
2597
+ ### Available hooks
2598
+
2599
+ - `on_render_before`
2600
+
2601
+ ```py
2602
+ def on_render_before(
2603
+ self: Component,
2604
+ context: Context,
2605
+ template: Template
2606
+ ) -> None:
2607
+ ```
2608
+
2609
+ Hook that runs just before the component's template is rendered.
2610
+
2611
+ You can use this hook to access or modify the context or the template:
2612
+
2613
+ ```py
2614
+ def on_render_before(self, context, template) -> None:
2615
+ # Insert value into the Context
2616
+ context["from_on_before"] = ":)"
2617
+
2618
+ # Append text into the Template
2619
+ template.nodelist.append(TextNode("FROM_ON_BEFORE"))
2620
+ ```
2621
+
2622
+ - `on_render_after`
2623
+
2624
+ ```py
2625
+ def on_render_after(
2626
+ self: Component,
2627
+ context: Context,
2628
+ template: Template,
2629
+ content: str
2630
+ ) -> None | str | SafeString:
2631
+ ```
2632
+
2633
+ Hook that runs just after the component's template was rendered.
2634
+ It receives the rendered output as the last argument.
2635
+
2636
+ You can use this hook to access the context or the template, but modifying
2637
+ them won't have any effect.
2638
+
2639
+ To override the content that gets rendered, you can return a string or SafeString from this hook:
2640
+
2641
+ ```py
2642
+ def on_render_after(self, context, template, content):
2643
+ # Prepend text to the rendered content
2644
+ return "Chocolate cookie recipe: " + content
2645
+ ```
2646
+
2647
+ ### Component hooks example
2648
+
2649
+ You can use hooks together with [provide / inject](#how-to-use-provide--inject) to create components
2650
+ that accept a list of items via a slot.
2651
+
2652
+ In the example below, each `tab_item` component will be rendered on a separate tab page, but they are all defined in the default slot of the `tabs` component.
2653
+
2654
+ [See here for how it was done](https://github.com/EmilStenstrom/django-components/discussions/540)
2655
+
2656
+ ```django
2657
+ {% component "tabs" %}
2658
+ {% component "tab_item" header="Tab 1" %}
2659
+ <p>
2660
+ hello from tab 1
2661
+ </p>
2662
+ {% component "button" %}
2663
+ Click me!
2664
+ {% endcomponent %}
2665
+ {% endcomponent %}
2666
+
2667
+ {% component "tab_item" header="Tab 2" %}
2668
+ Hello this is tab 2
2669
+ {% endcomponent %}
2670
+ {% endcomponent %}
2671
+ ```
2672
+
2459
2673
  ## Component context and scope
2460
2674
 
2461
2675
  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.
@@ -2474,6 +2688,24 @@ If you find yourself using the `only` modifier often, you can set the [context_b
2474
2688
 
2475
2689
  Components can also access the outer context in their context methods like `get_context_data` by accessing the property `self.outer_context`.
2476
2690
 
2691
+ ## Pre-defined template variables
2692
+
2693
+ Here is a list of all variables that are automatically available from within the component's template and `on_render_before` / `on_render_after` hooks.
2694
+
2695
+ - `component_vars.is_filled`
2696
+
2697
+ _New in version 0.70_
2698
+
2699
+ Dictonary describing which slots are filled (`True`) or are not (`False`).
2700
+
2701
+ Example:
2702
+
2703
+ ```django
2704
+ {% if component_vars.is_filled.my_slot %}
2705
+ {% slot "my_slot" / %}
2706
+ {% endif %}
2707
+ ```
2708
+
2477
2709
  ## Customizing component tags with TagFormatter
2478
2710
 
2479
2711
  _New in version 0.89_