django-components 0.89__tar.gz → 0.91__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 (64) hide show
  1. {django_components-0.89/src/django_components.egg-info → django_components-0.91}/PKG-INFO +218 -22
  2. {django_components-0.89 → django_components-0.91}/README.md +217 -21
  3. {django_components-0.89 → django_components-0.91}/pyproject.toml +1 -1
  4. django_components-0.91/src/django_components/__init__.py +32 -0
  5. {django_components-0.89 → django_components-0.91}/src/django_components/app_settings.py +8 -1
  6. django_components-0.91/src/django_components/attributes.py +77 -0
  7. {django_components-0.89 → django_components-0.91}/src/django_components/component.py +9 -10
  8. {django_components-0.89 → django_components-0.91}/src/django_components/component_registry.py +37 -67
  9. {django_components-0.89 → django_components-0.91}/src/django_components/expression.py +21 -4
  10. django_components-0.91/src/django_components/library.py +60 -0
  11. {django_components-0.89 → django_components-0.91}/src/django_components/slots.py +2 -4
  12. django_components-0.91/src/django_components/tag_formatter.py +219 -0
  13. {django_components-0.89 → django_components-0.91}/src/django_components/template_parser.py +12 -5
  14. django_components-0.91/src/django_components/templatetags/component_tags.py +614 -0
  15. {django_components-0.89 → django_components-0.91}/src/django_components/utils.py +4 -0
  16. {django_components-0.89 → django_components-0.91/src/django_components.egg-info}/PKG-INFO +218 -22
  17. {django_components-0.89 → django_components-0.91}/src/django_components.egg-info/SOURCES.txt +4 -0
  18. {django_components-0.89 → django_components-0.91}/tests/test_attributes.py +29 -1
  19. {django_components-0.89 → django_components-0.91}/tests/test_context.py +1 -1
  20. {django_components-0.89 → django_components-0.91}/tests/test_registry.py +46 -7
  21. django_components-0.91/tests/test_tag_formatter.py +402 -0
  22. {django_components-0.89 → django_components-0.91}/tests/test_template_parser.py +25 -14
  23. {django_components-0.89 → django_components-0.91}/tests/test_templatetags_component.py +35 -21
  24. {django_components-0.89 → django_components-0.91}/tests/test_templatetags_provide.py +19 -1
  25. {django_components-0.89 → django_components-0.91}/tests/test_templatetags_slot_fill.py +51 -1
  26. {django_components-0.89 → django_components-0.91}/tests/test_templatetags_templating.py +1 -1
  27. django_components-0.91/tests/test_utils.py +20 -0
  28. django_components-0.89/src/django_components/__init__.py +0 -19
  29. django_components-0.89/src/django_components/attributes.py +0 -104
  30. django_components-0.89/src/django_components/templatetags/component_tags.py +0 -512
  31. {django_components-0.89 → django_components-0.91}/LICENSE +0 -0
  32. {django_components-0.89 → django_components-0.91}/setup.cfg +0 -0
  33. {django_components-0.89 → django_components-0.91}/src/django_components/apps.py +0 -0
  34. {django_components-0.89 → django_components-0.91}/src/django_components/autodiscover.py +0 -0
  35. {django_components-0.89 → django_components-0.91}/src/django_components/component_media.py +0 -0
  36. {django_components-0.89 → django_components-0.91}/src/django_components/context.py +0 -0
  37. {django_components-0.89 → django_components-0.91}/src/django_components/logger.py +0 -0
  38. {django_components-0.89 → django_components-0.91}/src/django_components/management/__init__.py +0 -0
  39. {django_components-0.89 → django_components-0.91}/src/django_components/management/commands/__init__.py +0 -0
  40. {django_components-0.89 → django_components-0.91}/src/django_components/management/commands/startcomponent.py +0 -0
  41. {django_components-0.89 → django_components-0.91}/src/django_components/management/commands/upgradecomponent.py +0 -0
  42. {django_components-0.89 → django_components-0.91}/src/django_components/middleware.py +0 -0
  43. {django_components-0.89 → django_components-0.91}/src/django_components/node.py +0 -0
  44. {django_components-0.89 → django_components-0.91}/src/django_components/provide.py +0 -0
  45. {django_components-0.89 → django_components-0.91}/src/django_components/py.typed +0 -0
  46. {django_components-0.89 → django_components-0.91}/src/django_components/safer_staticfiles/__init__.py +0 -0
  47. {django_components-0.89 → django_components-0.91}/src/django_components/safer_staticfiles/apps.py +0 -0
  48. {django_components-0.89 → django_components-0.91}/src/django_components/template_loader.py +0 -0
  49. {django_components-0.89 → django_components-0.91}/src/django_components/templatetags/__init__.py +0 -0
  50. {django_components-0.89 → django_components-0.91}/src/django_components/types.py +0 -0
  51. {django_components-0.89 → django_components-0.91}/src/django_components.egg-info/dependency_links.txt +0 -0
  52. {django_components-0.89 → django_components-0.91}/src/django_components.egg-info/requires.txt +0 -0
  53. {django_components-0.89 → django_components-0.91}/src/django_components.egg-info/top_level.txt +0 -0
  54. {django_components-0.89 → django_components-0.91}/tests/test_autodiscover.py +0 -0
  55. {django_components-0.89 → django_components-0.91}/tests/test_command_startcomponent.py +0 -0
  56. {django_components-0.89 → django_components-0.91}/tests/test_component.py +0 -0
  57. {django_components-0.89 → django_components-0.91}/tests/test_component_as_view.py +0 -0
  58. {django_components-0.89 → django_components-0.91}/tests/test_component_media.py +0 -0
  59. {django_components-0.89 → django_components-0.91}/tests/test_dependency_rendering.py +0 -0
  60. {django_components-0.89 → django_components-0.91}/tests/test_safer_staticfiles.py +0 -0
  61. {django_components-0.89 → django_components-0.91}/tests/test_settings.py +0 -0
  62. {django_components-0.89 → django_components-0.91}/tests/test_template_loader.py +0 -0
  63. {django_components-0.89 → django_components-0.91}/tests/test_templatetags.py +0 -0
  64. {django_components-0.89 → django_components-0.91}/tests/testutils.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: django_components
3
- Version: 0.89
3
+ Version: 0.91
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
@@ -61,6 +61,7 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
61
61
  - [Rendering HTML attributes](#rendering-html-attributes)
62
62
  - [Prop drilling and dependency injection (provide / inject)](#prop-drilling-and-dependency-injection-provide--inject)
63
63
  - [Component context and scope](#component-context-and-scope)
64
+ - [Customizing component tags with TagFormatter](#customizing-component-tags-with-tagformatter)
64
65
  - [Defining HTML/JS/CSS files](#defining-htmljscss-files)
65
66
  - [Rendering JS/CSS dependencies](#rendering-jscss-dependencies)
66
67
  - [Available settings](#available-settings)
@@ -72,6 +73,34 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
72
73
 
73
74
  ## Release notes
74
75
 
76
+ **Version 0.90**
77
+ - All tags (`component`, `slot`, `fill`, ...) now support "self-closing" or "inline" form, where you can omit the closing tag:
78
+ ```django
79
+ {# Before #}
80
+ {% component "button" %}{% endcomponent %}
81
+ {# After #}
82
+ {% component "button" / %}
83
+ ```
84
+ - All tags now support the "dictionary key" or "aggregate" syntax (`kwarg:key=val`):
85
+ ```django
86
+ {% component "button" attrs:class="hidden" %}
87
+ ```
88
+ - You can change how the components are written in the template with [TagFormatter](#customizing-component-tags-with-tagformatter).
89
+
90
+ The default is `django_components.component_formatter`:
91
+ ```django
92
+ {% component "button" href="..." disabled %}
93
+ Click me!
94
+ {% endcomponent %}
95
+ ```
96
+
97
+ While `django_components.shorthand_component_formatter` allows you to write components like so:
98
+
99
+ ```django
100
+ {% button href="..." disabled %}
101
+ Click me!
102
+ {% endbutton %}
103
+
75
104
  🚨📢 **Version 0.85** Autodiscovery module resolution changed. Following undocumented behavior was removed:
76
105
 
77
106
  - Previously, autodiscovery also imported any `[app]/components.py` files, and used `SETTINGS_MODULE` to search for component dirs.
@@ -444,6 +473,10 @@ First load the `component_tags` tag library, then use the `component_[js/css]_de
444
473
  <html>
445
474
  ```
446
475
 
476
+ > NOTE: Instead of writing `{% endcomponent %}` at the end, you can use a self-closing tag:
477
+ >
478
+ > `{% component "calendar" date="2015-06-19" / %}`
479
+
447
480
  The output from the above template will be:
448
481
 
449
482
  ```html
@@ -485,7 +518,7 @@ class SimpleComponent(Component):
485
518
  hello: {{ hello }}
486
519
  foo: {{ foo }}
487
520
  kwargs: {{ kwargs|safe }}
488
- slot_first: {% slot "first" required %}{% endslot %}
521
+ slot_first: {% slot "first" required / %}
489
522
  """
490
523
 
491
524
  def get_context_data(self, arg1, arg2, **kwargs):
@@ -621,7 +654,7 @@ class Calendar(Component):
621
654
  template = """
622
655
  <div class="calendar-component">
623
656
  <div class="header">
624
- {% slot "header" %}{% endslot %}
657
+ {% slot "header" / %}
625
658
  </div>
626
659
  <div class="body">
627
660
  Today's date is <span>{{ date }}</span>
@@ -1158,7 +1191,7 @@ To negate the meaning of `component_vars.is_filled`, simply treat it as boolean
1158
1191
  ```htmldjango
1159
1192
  {% if not component_vars.is_filled.subtitle %}
1160
1193
  <div class="subtitle">
1161
- {% slot "subtitle" %}{% endslot %}
1194
+ {% slot "subtitle" / %}
1162
1195
  </div>
1163
1196
  {% endif %}
1164
1197
  ```
@@ -1290,8 +1323,7 @@ so are still valid:
1290
1323
 
1291
1324
  ```django
1292
1325
  <body>
1293
- {% component "calendar" my-date="2015-06-19" @click.native=do_something #some_id=True %}
1294
- {% endcomponent %}
1326
+ {% component "calendar" my-date="2015-06-19" @click.native=do_something #some_id=True / %}
1295
1327
  </body>
1296
1328
  ```
1297
1329
 
@@ -1326,8 +1358,7 @@ But for that, we need to define this dictionary on Python side:
1326
1358
  @register("my_comp")
1327
1359
  class MyComp(Component):
1328
1360
  template = """
1329
- {% component "other" attrs=attrs %}
1330
- {% endcomponent %}
1361
+ {% component "other" attrs=attrs / %}
1331
1362
  """
1332
1363
 
1333
1364
  def get_context_data(self, some_id: str):
@@ -1358,8 +1389,7 @@ class MyComp(Component):
1358
1389
  attrs:class="pa-4 flex"
1359
1390
  attrs:data-some-id=some_id
1360
1391
  attrs:@click.stop="onClickHandler"
1361
- %}
1362
- {% endcomponent %}
1392
+ / %}
1363
1393
  """
1364
1394
 
1365
1395
  def get_context_data(self, some_id: str):
@@ -1373,8 +1403,7 @@ Sweet! Now all the relevant HTML is inside the template, and we can move it to a
1373
1403
  attrs:class="pa-4 flex"
1374
1404
  attrs:data-some-id=some_id
1375
1405
  attrs:@click.stop="onClickHandler"
1376
- %}
1377
- {% endcomponent %}
1406
+ / %}
1378
1407
  ```
1379
1408
 
1380
1409
  > Note: It is NOT possible to define nested dictionaries, so
@@ -1670,8 +1699,7 @@ class Parent(Component):
1670
1699
  attrs:class="pa-0 border-solid border-red"
1671
1700
  attrs:data-json=json_data
1672
1701
  attrs:@click="(e) => onClick(e, 'from_parent')"
1673
- %}
1674
- {% endcomponent %}
1702
+ / %}
1675
1703
  """
1676
1704
 
1677
1705
  def get_context_data(self, date: Date):
@@ -1799,12 +1827,10 @@ First we use the `{% provide %}` tag to define the data we want to "provide" (ma
1799
1827
 
1800
1828
  ```django
1801
1829
  {% provide "my_data" key="hi" another=123 %}
1802
- {% component "child" %} <--- Can access "my_data"
1803
- {% endcomponent %}
1830
+ {% component "child" / %} <--- Can access "my_data"
1804
1831
  {% endprovide %}
1805
1832
 
1806
- {% component "child" %} <--- Cannot access "my_data"
1807
- {% endcomponent %}
1833
+ {% component "child" / %} <--- Cannot access "my_data"
1808
1834
  ```
1809
1835
 
1810
1836
  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.
@@ -1878,8 +1904,7 @@ class ChildComponent(Component):
1878
1904
  template_str = """
1879
1905
  {% load component_tags %}
1880
1906
  {% provide "my_data" key="hi" another=123 %}
1881
- {% component "child" %}
1882
- {% endcomponent %}
1907
+ {% component "child" / %}
1883
1908
  {% endprovide %}
1884
1909
  """
1885
1910
  ```
@@ -1897,7 +1922,7 @@ By default, context variables are passed down the template as in regular Django
1897
1922
 
1898
1923
  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.
1899
1924
 
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:
1925
+ 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 `{% component %}` tag:
1901
1926
 
1902
1927
  ```htmldjango
1903
1928
  {% component "calendar" date="2015-06-19" only %}{% endcomponent %}
@@ -1909,6 +1934,155 @@ If you find yourself using the `only` modifier often, you can set the [context_b
1909
1934
 
1910
1935
  Components can also access the outer context in their context methods like `get_context_data` by accessing the property `self.outer_context`.
1911
1936
 
1937
+ ## Customizing component tags with TagFormatter
1938
+
1939
+ _New in version 0.89_
1940
+
1941
+ By default, components are rendered using the pair of `{% component %}` / `{% endcomponent %}` template tags:
1942
+
1943
+ ```django
1944
+ {% component "button" href="..." disabled %}
1945
+ Click me!
1946
+ {% endcomponent %}
1947
+
1948
+ {# or #}
1949
+
1950
+ {% component "button" href="..." disabled / %}
1951
+ ```
1952
+
1953
+ You can change this behaviour in the settings under the [`COMPONENTS.tag_formatter`](#tag-formatter-setting).
1954
+
1955
+ For example, if you set the tag formatter to `django_components.shorthand_component_formatter`, the components will use their name as the template tags:
1956
+
1957
+ ```django
1958
+ {% button href="..." disabled %}
1959
+ Click me!
1960
+ {% endbutton %}
1961
+
1962
+ {# or #}
1963
+
1964
+ {% button href="..." disabled / %}
1965
+ ```
1966
+
1967
+ ### Available TagFormatters
1968
+
1969
+ django_components provides following predefined TagFormatters:
1970
+
1971
+ - **`ComponentFormatter` (`django_components.component_formatter`)**
1972
+
1973
+ Default
1974
+
1975
+ Uses the `component` and `endcomponent` tags, and the component name is gives as the first positional argument.
1976
+
1977
+ Example as block:
1978
+ ```django
1979
+ {% component "button" href="..." %}
1980
+ {% fill "content" %}
1981
+ ...
1982
+ {% endfill %}
1983
+ {% endcomponent %}
1984
+ ```
1985
+
1986
+ Example as inlined tag:
1987
+ ```django
1988
+ {% component "button" href="..." / %}
1989
+ ```
1990
+
1991
+ - **`ShorthandComponentFormatter` (`django_components.shorthand_component_formatter`)**
1992
+
1993
+ Uses the component name as start tag, and `end<component_name>`
1994
+ as an end tag.
1995
+
1996
+ Example as block:
1997
+ ```django
1998
+ {% button href="..." %}
1999
+ Click me!
2000
+ {% endbutton %}
2001
+ ```
2002
+
2003
+ Example as inlined tag:
2004
+ ```django
2005
+ {% button href="..." / %}
2006
+ ```
2007
+
2008
+ ### Writing your own TagFormatter
2009
+
2010
+ #### Background
2011
+
2012
+ First, let's discuss how TagFormatters work, and how components are rendered in django_components.
2013
+
2014
+ When you render a component with `{% component %}` (or your own tag), the following happens:
2015
+ 1. `component` must be registered as a Django's template tag
2016
+ 2. Django triggers django_components's tag handler for tag `component`.
2017
+ 3. The tag handler passes the tag contents for pre-processing to `TagFormatter.parse()`.
2018
+
2019
+ So if you render this:
2020
+ ```django
2021
+ {% component "button" href="..." disabled %}
2022
+ {% endcomponent %}
2023
+ ```
2024
+
2025
+ Then `TagFormatter.parse()` will receive a following input:
2026
+ ```py
2027
+ ["component", '"button"', 'href="..."', 'disabled']
2028
+ ```
2029
+ 4. `TagFormatter` extracts the component name and the remaining input.
2030
+
2031
+ So, given the above, `TagFormatter.parse()` returns the following:
2032
+ ```py
2033
+ TagResult(
2034
+ component_name="button",
2035
+ tokens=['href="..."', 'disabled']
2036
+ )
2037
+ ```
2038
+ 5. The tag handler resumes, using the tokens returned from `TagFormatter`.
2039
+
2040
+ So, continuing the example, at this point the tag handler practically behaves as if you rendered:
2041
+ ```django
2042
+ {% component href="..." disabled %}
2043
+ ```
2044
+ 6. Tag handler looks up the component `button`, and passes the args, kwargs, and slots to it.
2045
+
2046
+ #### TagFormatter
2047
+
2048
+ `TagFormatter` handles following parts of the process above:
2049
+ - Generates start/end tags, given a component. This is what you then call from within your template as `{% component %}`.
2050
+
2051
+ - When you `{% component %}`, tag formatter pre-processes the tag contents, so it can link back the custom template tag to the right component.
2052
+
2053
+ To do so, subclass from `TagFormatterABC` and implement following method:
2054
+ - `start_tag`
2055
+ - `end_tag`
2056
+ - `parse`
2057
+
2058
+ For example, this is the implementation of [`ShorthandComponentFormatter`](#available-tagformatters)
2059
+
2060
+ ```py
2061
+ class ShorthandComponentFormatter(TagFormatterABC):
2062
+ # Given a component name, generate the start template tag
2063
+ def start_tag(self, name: str) -> str:
2064
+ return name # e.g. 'button'
2065
+
2066
+ # Given a component name, generate the start template tag
2067
+ def end_tag(self, name: str) -> str:
2068
+ return f"end{name}" # e.g. 'endbutton'
2069
+
2070
+ # Given a tag, e.g.
2071
+ # `{% button href="..." disabled %}`
2072
+ #
2073
+ # The parser receives:
2074
+ # `['button', 'href="..."', 'disabled']`
2075
+ def parse(self, tokens: List[str]) -> TagResult:
2076
+ tokens = [*tokens]
2077
+ name = tokens.pop(0)
2078
+ return TagResult(
2079
+ name, # e.g. 'button'
2080
+ tokens # e.g. ['href="..."', 'disabled']
2081
+ )
2082
+ ```
2083
+
2084
+ That's it! And once your `TagFormatter` is ready, don't forget to update the settings!
2085
+
1912
2086
  ## Defining HTML/JS/CSS files
1913
2087
 
1914
2088
  django_component's management of files builds on top of [Django's `Media` class](https://docs.djangoproject.com/en/5.0/topics/forms/media/).
@@ -2211,7 +2385,7 @@ COMPONENTS = {
2211
2385
  }
2212
2386
  ```
2213
2387
 
2214
- ### Context behavior
2388
+ ### Context behavior setting
2215
2389
 
2216
2390
  > NOTE: `context_behavior` and `slot_context_behavior` options were merged in v0.70.
2217
2391
  >
@@ -2316,6 +2490,28 @@ But since `"cheese"` is not defined there, it's empty.
2316
2490
 
2317
2491
  Notice that the variables defined with the `{% with %}` tag are ignored inside the `{% fill %}` tag with the `"isolated"` mode.
2318
2492
 
2493
+ ### Tag formatter setting
2494
+
2495
+ Set the [`TagFormatter`](#available-tagformatters) instance.
2496
+
2497
+ Can be set either as direct reference, or as an import string;
2498
+
2499
+ ```py
2500
+ COMPONENTS = {
2501
+ "tag_formatter": "django_components.component_formatter"
2502
+ }
2503
+ ```
2504
+
2505
+ Or
2506
+
2507
+ ```py
2508
+ from django_components import component_formatter
2509
+
2510
+ COMPONENTS = {
2511
+ "tag_formatter": component_formatter
2512
+ }
2513
+ ```
2514
+
2319
2515
  ## Logging and debugging
2320
2516
 
2321
2517
  Django components supports [logging with Django](https://docs.djangoproject.com/en/5.0/howto/logging/#logging-how-to). This can help with troubleshooting.