django-components 0.80__tar.gz → 0.81__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 (54) hide show
  1. {django_components-0.80/src/django_components.egg-info → django_components-0.81}/PKG-INFO +138 -4
  2. {django_components-0.80 → django_components-0.81}/README.md +137 -3
  3. {django_components-0.80 → django_components-0.81}/pyproject.toml +1 -1
  4. {django_components-0.80 → django_components-0.81}/src/django_components/component.py +282 -126
  5. {django_components-0.80 → django_components-0.81}/src/django_components/component_registry.py +1 -1
  6. {django_components-0.80 → django_components-0.81}/src/django_components/slots.py +31 -16
  7. {django_components-0.80 → django_components-0.81/src/django_components.egg-info}/PKG-INFO +138 -4
  8. django_components-0.81/tests/test_component.py +511 -0
  9. {django_components-0.80 → django_components-0.81}/tests/test_component_as_view.py +8 -8
  10. {django_components-0.80 → django_components-0.81}/tests/test_component_media.py +2 -4
  11. django_components-0.80/tests/test_component.py +0 -128
  12. {django_components-0.80 → django_components-0.81}/LICENSE +0 -0
  13. {django_components-0.80 → django_components-0.81}/setup.cfg +0 -0
  14. {django_components-0.80 → django_components-0.81}/src/django_components/__init__.py +0 -0
  15. {django_components-0.80 → django_components-0.81}/src/django_components/app_settings.py +0 -0
  16. {django_components-0.80 → django_components-0.81}/src/django_components/apps.py +0 -0
  17. {django_components-0.80 → django_components-0.81}/src/django_components/attributes.py +0 -0
  18. {django_components-0.80 → django_components-0.81}/src/django_components/context.py +0 -0
  19. {django_components-0.80 → django_components-0.81}/src/django_components/expression.py +0 -0
  20. {django_components-0.80 → django_components-0.81}/src/django_components/logger.py +0 -0
  21. {django_components-0.80 → django_components-0.81}/src/django_components/management/__init__.py +0 -0
  22. {django_components-0.80 → django_components-0.81}/src/django_components/management/commands/__init__.py +0 -0
  23. {django_components-0.80 → django_components-0.81}/src/django_components/management/commands/startcomponent.py +0 -0
  24. {django_components-0.80 → django_components-0.81}/src/django_components/management/commands/upgradecomponent.py +0 -0
  25. {django_components-0.80 → django_components-0.81}/src/django_components/middleware.py +0 -0
  26. {django_components-0.80 → django_components-0.81}/src/django_components/node.py +0 -0
  27. {django_components-0.80 → django_components-0.81}/src/django_components/provide.py +0 -0
  28. {django_components-0.80 → django_components-0.81}/src/django_components/py.typed +0 -0
  29. {django_components-0.80 → django_components-0.81}/src/django_components/safer_staticfiles/__init__.py +0 -0
  30. {django_components-0.80 → django_components-0.81}/src/django_components/safer_staticfiles/apps.py +0 -0
  31. {django_components-0.80 → django_components-0.81}/src/django_components/template_loader.py +0 -0
  32. {django_components-0.80 → django_components-0.81}/src/django_components/template_parser.py +0 -0
  33. {django_components-0.80 → django_components-0.81}/src/django_components/templatetags/__init__.py +0 -0
  34. {django_components-0.80 → django_components-0.81}/src/django_components/templatetags/component_tags.py +0 -0
  35. {django_components-0.80 → django_components-0.81}/src/django_components/types.py +0 -0
  36. {django_components-0.80 → django_components-0.81}/src/django_components/utils.py +0 -0
  37. {django_components-0.80 → django_components-0.81}/src/django_components.egg-info/SOURCES.txt +0 -0
  38. {django_components-0.80 → django_components-0.81}/src/django_components.egg-info/dependency_links.txt +0 -0
  39. {django_components-0.80 → django_components-0.81}/src/django_components.egg-info/requires.txt +0 -0
  40. {django_components-0.80 → django_components-0.81}/src/django_components.egg-info/top_level.txt +0 -0
  41. {django_components-0.80 → django_components-0.81}/tests/test_attributes.py +0 -0
  42. {django_components-0.80 → django_components-0.81}/tests/test_autodiscover.py +0 -0
  43. {django_components-0.80 → django_components-0.81}/tests/test_command_startcomponent.py +0 -0
  44. {django_components-0.80 → django_components-0.81}/tests/test_context.py +0 -0
  45. {django_components-0.80 → django_components-0.81}/tests/test_dependency_rendering.py +0 -0
  46. {django_components-0.80 → django_components-0.81}/tests/test_registry.py +0 -0
  47. {django_components-0.80 → django_components-0.81}/tests/test_settings.py +0 -0
  48. {django_components-0.80 → django_components-0.81}/tests/test_template_parser.py +0 -0
  49. {django_components-0.80 → django_components-0.81}/tests/test_templatetags.py +0 -0
  50. {django_components-0.80 → django_components-0.81}/tests/test_templatetags_component.py +0 -0
  51. {django_components-0.80 → django_components-0.81}/tests/test_templatetags_provide.py +0 -0
  52. {django_components-0.80 → django_components-0.81}/tests/test_templatetags_slot_fill.py +0 -0
  53. {django_components-0.80 → django_components-0.81}/tests/test_templatetags_templating.py +0 -0
  54. {django_components-0.80 → django_components-0.81}/tests/testutils.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: django_components
3
- Version: 0.80
3
+ Version: 0.81
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,10 @@ Read on to learn about the details!
69
69
 
70
70
  ## Release notes
71
71
 
72
+ 🚨📢 **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.
73
+
74
+ - BREAKING CHANGE: The order of arguments to `render_to_response` has changed.
75
+
72
76
  **Version 0.80** introduces dependency injection with the `{% provide %}` tag and `inject()` method.
73
77
 
74
78
  🚨📢 **Version 0.79**
@@ -337,7 +341,7 @@ This makes it easy to create small components without having to create a separat
337
341
 
338
342
  Note that the `t.django_html`, `t.css`, and `t.js` types are used to specify the type of the template, CSS, and JS files, respectively. This is not necessary, but if you're using VSCode with the [Python Inline Source Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=samwillis.python-inline-source) extension, it will give you syntax highlighting for the template, CSS, and JS.
339
343
 
340
- ## Use the component in a template
344
+ ## Use components in templates
341
345
 
342
346
  First load the `component_tags` tag library, then use the `component_[js/css]_dependencies` and `component` tags to render the component to the page.
343
347
 
@@ -382,13 +386,143 @@ The output from the above template will be:
382
386
 
383
387
  This makes it possible to organize your front-end around reusable components. Instead of relying on template tags and keeping your CSS and Javascript in the static directory.
384
388
 
389
+ ## Use components outside of templates
390
+
391
+ _New in version 0.81_
392
+
393
+ Components can be rendered outside of Django templates, calling them as regular functions ("React-style").
394
+
395
+ 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:
396
+
397
+ ```py
398
+ class SimpleComponent(component.Component):
399
+ template = """
400
+ {% load component_tags %}
401
+ hello: {{ hello }}
402
+ foo: {{ foo }}
403
+ kwargs: {{ kwargs|safe }}
404
+ slot_first: {% slot "first" required %}{% endslot %}
405
+ """
406
+
407
+ def get_context_data(self, arg1, arg2, **kwargs):
408
+ return {
409
+ "hello": arg1,
410
+ "foo": arg2,
411
+ "kwargs": kwargs,
412
+ }
413
+
414
+ rendered = SimpleComponent.render(
415
+ args=["world", "bar"],
416
+ kwargs={"kw1": "test", "kw2": "ooo"},
417
+ slots={"first": "FIRST_SLOT"},
418
+ context={"from_context": 98},
419
+ )
420
+ ```
421
+
422
+ Renders:
423
+
424
+ ```
425
+ hello: world
426
+ foo: bar
427
+ kwargs: {'kw1': 'test', 'kw2': 'ooo'}
428
+ slot_first: FIRST_SLOT
429
+ ```
430
+
431
+ ### Inputs of `render` and `render_to_response`
432
+
433
+ Both `render` and `render_to_response` accept the same input:
434
+
435
+ ```py
436
+ Component.render(
437
+ context: Mapping | django.template.Context | None = None,
438
+ args: List[Any] | None = None,
439
+ kwargs: Dict[str, Any] | None = None,
440
+ slots: Dict[str, str | SafeString | SlotRenderFunc] | None = None,
441
+ escape_slots_content: bool = True
442
+ ) -> str:
443
+ ```
444
+
445
+ - _`args`_ - Positional args for the component. This is the same as calling the component
446
+ as `{% component "my_comp" arg1 arg2 ... %}`
447
+
448
+ - _`kwargs`_ - Keyword args for the component. This is the same as calling the component
449
+ as `{% component "my_comp" key1=val1 key2=val2 ... %}`
450
+
451
+ - _`slots`_ - Component slot fills. This is the same as pasing `{% fill %}` tags to the component.
452
+ Accepts a dictionary of `{ slot_name: slot_content }` where `slot_content` can be a string
453
+ or [`SlotRenderFunc`](#slotrenderfunc).
454
+
455
+ - _`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.
456
+
457
+ - _`context`_ - A context (dictionary or Django's Context) within which the component
458
+ is rendered. The keys on the context can be accessed from within the template.
459
+ - NOTE: In "isolated" mode, context is NOT accessible, and data MUST be passed via
460
+ component's args and kwargs.
461
+
462
+ #### `SlotRenderFunc`
463
+
464
+ When rendering components with slots in `render` or `render_to_response`, you can pass either a string or a function.
465
+
466
+ The function has following signature:
467
+
468
+ ```py
469
+ def render_func(
470
+ context: Context,
471
+ data: Dict[str, Any],
472
+ slot_ref: SlotRef,
473
+ ) -> str | SafeString:
474
+ return nodelist.render(ctx)
475
+ ```
476
+
477
+ - _`context`_ - Django's Context available to the Slot Node.
478
+ - _`data`_ - Data passed to the `{% slot %}` tag. See [Scoped Slots](#scoped-slots).
479
+ - _`slot_ref`_ - The default slot content. See [Accessing original content of slots](#accessing-original-content-of-slots).
480
+ - NOTE: The slot is lazily evaluated. To render the slot, convert it to string with `str(slot_ref)`.
481
+
482
+ Example:
483
+ ```py
484
+ def footer_slot(ctx, data, slot_ref):
485
+ return f"""
486
+ SLOT_DATA: {data['abc']}
487
+ ORIGINAL: {slot_ref}
488
+ """
489
+
490
+ MyComponent.render_to_response(
491
+ slots={
492
+ "footer": footer_slot,
493
+ },
494
+ )
495
+ ```
496
+
497
+ ### Response class of `render_to_response`
498
+
499
+ 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`.
500
+
501
+ If you want to use a different Response class in `render_to_response`, set the `Component.response_class` attribute:
502
+
503
+ ```py
504
+ class MyResponse(HttpResponse):
505
+ def __init__(self, *args, **kwargs) -> None:
506
+ super().__init__(*args, **kwargs)
507
+ # Configure response
508
+ self.headers = ...
509
+ self.status = ...
510
+
511
+ class SimpleComponent(component.Component):
512
+ response_class = MyResponse
513
+ template: types.django_html = "HELLO"
514
+
515
+ response = SimpleComponent.render_to_response()
516
+ assert isinstance(response, MyResponse)
517
+ ```
518
+
385
519
  ## Use components as views
386
520
 
387
521
  _New in version 0.34_
388
522
 
389
523
  Components can now be used as views. To do this, `Component` subclasses Django's `View` class. This means that you can use all of the [methods](https://docs.djangoproject.com/en/5.0/ref/class-based-views/base/#view) of `View` in your component. For example, you can override `get` and `post` to handle GET and POST requests, respectively.
390
524
 
391
- In addition, `Component` now has a `render_to_response` method that renders the component template based on the provided context and slots' data and returns an `HttpResponse` object.
525
+ In addition, `Component` now has a [`render_to_response`](#inputs-of-render-and-render_to_response) method that renders the component template based on the provided context and slots' data and returns an `HttpResponse` object.
392
526
 
393
527
  Here's an example of a calendar component defined as a view:
394
528
 
@@ -417,7 +551,7 @@ class Calendar(component.Component):
417
551
  slots = {
418
552
  "header": "Calendar header",
419
553
  }
420
- return self.render_to_response(context, slots)
554
+ return self.render_to_response(context=context, slots=slots)
421
555
  ```
422
556
 
423
557
  Then, to use this component as a view, you should create a `urls.py` file in your components directory, and add a path to the component's view:
@@ -45,6 +45,10 @@ Read on to learn about the details!
45
45
 
46
46
  ## Release notes
47
47
 
48
+ 🚨📢 **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.
49
+
50
+ - BREAKING CHANGE: The order of arguments to `render_to_response` has changed.
51
+
48
52
  **Version 0.80** introduces dependency injection with the `{% provide %}` tag and `inject()` method.
49
53
 
50
54
  🚨📢 **Version 0.79**
@@ -313,7 +317,7 @@ This makes it easy to create small components without having to create a separat
313
317
 
314
318
  Note that the `t.django_html`, `t.css`, and `t.js` types are used to specify the type of the template, CSS, and JS files, respectively. This is not necessary, but if you're using VSCode with the [Python Inline Source Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=samwillis.python-inline-source) extension, it will give you syntax highlighting for the template, CSS, and JS.
315
319
 
316
- ## Use the component in a template
320
+ ## Use components in templates
317
321
 
318
322
  First load the `component_tags` tag library, then use the `component_[js/css]_dependencies` and `component` tags to render the component to the page.
319
323
 
@@ -358,13 +362,143 @@ The output from the above template will be:
358
362
 
359
363
  This makes it possible to organize your front-end around reusable components. Instead of relying on template tags and keeping your CSS and Javascript in the static directory.
360
364
 
365
+ ## Use components outside of templates
366
+
367
+ _New in version 0.81_
368
+
369
+ Components can be rendered outside of Django templates, calling them as regular functions ("React-style").
370
+
371
+ 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:
372
+
373
+ ```py
374
+ class SimpleComponent(component.Component):
375
+ template = """
376
+ {% load component_tags %}
377
+ hello: {{ hello }}
378
+ foo: {{ foo }}
379
+ kwargs: {{ kwargs|safe }}
380
+ slot_first: {% slot "first" required %}{% endslot %}
381
+ """
382
+
383
+ def get_context_data(self, arg1, arg2, **kwargs):
384
+ return {
385
+ "hello": arg1,
386
+ "foo": arg2,
387
+ "kwargs": kwargs,
388
+ }
389
+
390
+ rendered = SimpleComponent.render(
391
+ args=["world", "bar"],
392
+ kwargs={"kw1": "test", "kw2": "ooo"},
393
+ slots={"first": "FIRST_SLOT"},
394
+ context={"from_context": 98},
395
+ )
396
+ ```
397
+
398
+ Renders:
399
+
400
+ ```
401
+ hello: world
402
+ foo: bar
403
+ kwargs: {'kw1': 'test', 'kw2': 'ooo'}
404
+ slot_first: FIRST_SLOT
405
+ ```
406
+
407
+ ### Inputs of `render` and `render_to_response`
408
+
409
+ Both `render` and `render_to_response` accept the same input:
410
+
411
+ ```py
412
+ Component.render(
413
+ context: Mapping | django.template.Context | None = None,
414
+ args: List[Any] | None = None,
415
+ kwargs: Dict[str, Any] | None = None,
416
+ slots: Dict[str, str | SafeString | SlotRenderFunc] | None = None,
417
+ escape_slots_content: bool = True
418
+ ) -> str:
419
+ ```
420
+
421
+ - _`args`_ - Positional args for the component. This is the same as calling the component
422
+ as `{% component "my_comp" arg1 arg2 ... %}`
423
+
424
+ - _`kwargs`_ - Keyword args for the component. This is the same as calling the component
425
+ as `{% component "my_comp" key1=val1 key2=val2 ... %}`
426
+
427
+ - _`slots`_ - Component slot fills. This is the same as pasing `{% fill %}` tags to the component.
428
+ Accepts a dictionary of `{ slot_name: slot_content }` where `slot_content` can be a string
429
+ or [`SlotRenderFunc`](#slotrenderfunc).
430
+
431
+ - _`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.
432
+
433
+ - _`context`_ - A context (dictionary or Django's Context) within which the component
434
+ is rendered. The keys on the context can be accessed from within the template.
435
+ - NOTE: In "isolated" mode, context is NOT accessible, and data MUST be passed via
436
+ component's args and kwargs.
437
+
438
+ #### `SlotRenderFunc`
439
+
440
+ When rendering components with slots in `render` or `render_to_response`, you can pass either a string or a function.
441
+
442
+ The function has following signature:
443
+
444
+ ```py
445
+ def render_func(
446
+ context: Context,
447
+ data: Dict[str, Any],
448
+ slot_ref: SlotRef,
449
+ ) -> str | SafeString:
450
+ return nodelist.render(ctx)
451
+ ```
452
+
453
+ - _`context`_ - Django's Context available to the Slot Node.
454
+ - _`data`_ - Data passed to the `{% slot %}` tag. See [Scoped Slots](#scoped-slots).
455
+ - _`slot_ref`_ - The default slot content. See [Accessing original content of slots](#accessing-original-content-of-slots).
456
+ - NOTE: The slot is lazily evaluated. To render the slot, convert it to string with `str(slot_ref)`.
457
+
458
+ Example:
459
+ ```py
460
+ def footer_slot(ctx, data, slot_ref):
461
+ return f"""
462
+ SLOT_DATA: {data['abc']}
463
+ ORIGINAL: {slot_ref}
464
+ """
465
+
466
+ MyComponent.render_to_response(
467
+ slots={
468
+ "footer": footer_slot,
469
+ },
470
+ )
471
+ ```
472
+
473
+ ### Response class of `render_to_response`
474
+
475
+ 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`.
476
+
477
+ If you want to use a different Response class in `render_to_response`, set the `Component.response_class` attribute:
478
+
479
+ ```py
480
+ class MyResponse(HttpResponse):
481
+ def __init__(self, *args, **kwargs) -> None:
482
+ super().__init__(*args, **kwargs)
483
+ # Configure response
484
+ self.headers = ...
485
+ self.status = ...
486
+
487
+ class SimpleComponent(component.Component):
488
+ response_class = MyResponse
489
+ template: types.django_html = "HELLO"
490
+
491
+ response = SimpleComponent.render_to_response()
492
+ assert isinstance(response, MyResponse)
493
+ ```
494
+
361
495
  ## Use components as views
362
496
 
363
497
  _New in version 0.34_
364
498
 
365
499
  Components can now be used as views. To do this, `Component` subclasses Django's `View` class. This means that you can use all of the [methods](https://docs.djangoproject.com/en/5.0/ref/class-based-views/base/#view) of `View` in your component. For example, you can override `get` and `post` to handle GET and POST requests, respectively.
366
500
 
367
- In addition, `Component` now has a `render_to_response` method that renders the component template based on the provided context and slots' data and returns an `HttpResponse` object.
501
+ In addition, `Component` now has a [`render_to_response`](#inputs-of-render-and-render_to_response) method that renders the component template based on the provided context and slots' data and returns an `HttpResponse` object.
368
502
 
369
503
  Here's an example of a calendar component defined as a view:
370
504
 
@@ -393,7 +527,7 @@ class Calendar(component.Component):
393
527
  slots = {
394
528
  "header": "Calendar header",
395
529
  }
396
- return self.render_to_response(context, slots)
530
+ return self.render_to_response(context=context, slots=slots)
397
531
  ```
398
532
 
399
533
  Then, to use this component as a view, you should create a `urls.py` file in your components directory, and add a path to the component's view:
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "django_components"
7
- version = "0.80"
7
+ version = "0.81"
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"]