chameleon_partials 0.2.0__tar.gz

chameleon_partials-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Michael Kennedy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chameleon_partials-0.2.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: chameleon_partials
+Version: 0.2.0
+Summary: Simple reuse of partial HTML page templates in the Chameleon template language for Python web frameworks.
+Author-email: Michael Kennedy <michael@talkpython.fm>
+License: MIT
+Project-URL: Homepage, https://github.com/mikeckennedy/chameleon_partials
+Project-URL: Repository, https://github.com/mikeckennedy/chameleon_partials
+Project-URL: Documentation, https://mkennedy.codes/docs/chameleon-partials/
+Project-URL: Issues, https://github.com/mikeckennedy/chameleon_partials/issues
+Project-URL: Changelog, https://github.com/mikeckennedy/chameleon_partials/blob/main/CHANGELOG.md
+Project-URL: Funding, https://github.com/sponsors/mikeckennedy
+Keywords: chameleon,partials,templates,templating,template-engine,html,rendering,render-partial,components,fragments,reusable,web,web-development,web-framework,pyramid,fastapi,htmx,frontend,jinja-partials,zpt,tal,metal
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: chameleon
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-clarity; extra == "dev"
+Requires-Dist: ty; extra == "dev"
+Requires-Dist: pyrefly; extra == "dev"
+Requires-Dist: great-docs; python_version >= "3.11" and extra == "dev"
+Dynamic: license-file
+
+# Chameleon Partials
+
+Simple reuse of partial HTML page templates in the Chameleon template language for Python web frameworks.
+(There is also a [Jinja2/Flask version here](https://github.com/mikeckennedy/jinja_partials).)
+
+## Overview
+
+When building real-world web apps with Chameleon, it's easy to end up with repeated HTML fragments.
+Just like organizing code for reuse, it would be ideal to reuse smaller sections of HTML template code.
+That's what this library is all about.
+
+## Documentation
+
+Full documentation lives at
+[mkennedy.codes/docs/chameleon-partials](https://mkennedy.codes/docs/chameleon-partials/),
+including the complete [API reference](https://mkennedy.codes/docs/chameleon-partials/reference/)
+generated from the library's docstrings.
+
+## Example
+
+This project comes with a sample Pyramid application (see the `example` folder). This app displays videos
+that can be played on YouTube. The image, author subtitle, and view count are reused throughout the
+app. Here's a visual:
+
+![Video image, author, and view count HTML reused across pages of the demo app](https://raw.githubusercontent.com/mikeckennedy/chameleon_partials/main/readme_resources/reused-html-visual.png)
+
+Check out the [**demo / example application**](https://github.com/mikeckennedy/chameleon_partials/tree/main/example) 
+to see it in action. 
+
+## Installation
+
+It's just `pip install chameleon-partials` and you're all set with this pure Python package.
+
+## Usage
+
+Using the library is incredibly easy. The first step is to register the partial method with Chameleon.
+Do this once at app startup:
+
+```python
+from pathlib import Path
+
+from pyramid.config import Configurator
+
+import chameleon_partials
+
+def main(_, **settings):
+    """ This function returns a Pyramid WSGI application.
+    """
+    with Configurator(settings=settings) as config:
+        config.include('pyramid_chameleon')
+        config.include('.routes')
+        config.scan()
+        
+        # Register the extension for working with Chameleon.
+        folder = (Path(__file__).parent / "templates").as_posix()
+        chameleon_partials.register_extensions(folder, auto_reload=True, cache_init=True)
+
+    return config.make_wsgi_app()
+```
+
+Next, you define your main HTML (Chameleon) templates as usual. Then 
+define your partial templates. I recommend locating and naming them accordingly:
+
+```
+├── templates
+│   ├── errors
+│   │   └── 404.pt
+│   ├── home
+│   │   ├── index.pt
+│   │   └── listing.pt
+│   └── shared
+│       ├── _layout.pt
+│       └── partials
+│           ├── video_image.pt
+│           └── video_square.pt
+```
+
+Notice the `partials` subfolder in the `templates/shared` folder.
+
+The templates are just HTML fragments. Here is a stand-alone one for the YouTube thumbnail from
+the example app:
+
+```html
+<img src="https://img.youtube.com/vi/${ video.id }/maxresdefault.jpg"
+     class="img img-responsive ${ ' '.join(classes or []) }"
+     alt="${ video.title }"
+     title="${ video.title }">
+```
+
+Notice that an object called `video` and a list of classes are passed in as the model.
+
+Templates can also be nested. Here is the whole single video fragment with the image as well as other info
+linking out to YouTube:
+
+```html
+<div>
+    <a href="https://www.youtube.com/watch?v=${ video.id }" target="_blank">
+        ${ render_partial('shared/partials/video_image.pt', video=video, classes=[]) }
+    </a>
+    <a href="https://www.youtube.com/watch?v=${ video.id }" target="_blank"
+       class="author">${ video.author }</a>
+    <div class="views">${ "{:,}".format(video.views) } views</div>
+</div>
+```
+
+Now you see the `render_partial()` method. It takes the subpath into the templates folder and
+any model data passed in as keyword arguments.
+
+We can finally generate the list of video blocks as follows:
+
+```html
+<span class="video" tal:repeat="v videos">
+    ${ render_partial('shared/partials/video_square.pt', video=v) }
+</span>
+```
+
+This time, we reframe each item in the list from the outer template (called `v`) as the `video` model
+in the inner HTML section.
+
+## The View Methods
+
+In order to share the `render_partial()` function with your template, you'll need to pass it along to the
+template with your model (dictionary). 
+
+If you are using the **Pyramid web framework**, you can add this file as middleware. Just drop it into
+your `views` folder:
+
+```python
+# views/partials_middleware.py
+from pyramid.events import subscriber, BeforeRender
+
+import chameleon_partials
+
+
+@subscriber(BeforeRender)
+def add_global(event):
+    event['render_partial'] = chameleon_partials.render_partial
+```
+
+For other frameworks using Chameleon (e.g. FastAPI), you can add `render_partial` to the
+resulting dictionary. We've built a simple function to keep this fool-proof: 
+
+```python
+chameleon_partials.extend_model(model)
+```
+
+Here's a typical view method that uses `render_partial`, notice the use of extending the 
+model before passing it to the template (the example app's views skip this because the 
+middleware above handles it):
+
+```python
+@view_config(route_name='listing', renderer='demo_chameleon_partials:templates/home/listing.pt')
+def listing(_):
+    videos = video_service.all_videos()
+    model = dict(videos=videos)
+    return chameleon_partials.extend_model(model)
+```
+
+Again: If you are using Pyramid, use the middleware. Otherwise, use the `extend_model()` method or something 
+similar to the middleware in your framework.

chameleon_partials-0.2.0/README.md

@@ -0,0 +1,160 @@
+# Chameleon Partials
+
+Simple reuse of partial HTML page templates in the Chameleon template language for Python web frameworks.
+(There is also a [Jinja2/Flask version here](https://github.com/mikeckennedy/jinja_partials).)
+
+## Overview
+
+When building real-world web apps with Chameleon, it's easy to end up with repeated HTML fragments.
+Just like organizing code for reuse, it would be ideal to reuse smaller sections of HTML template code.
+That's what this library is all about.
+
+## Documentation
+
+Full documentation lives at
+[mkennedy.codes/docs/chameleon-partials](https://mkennedy.codes/docs/chameleon-partials/),
+including the complete [API reference](https://mkennedy.codes/docs/chameleon-partials/reference/)
+generated from the library's docstrings.
+
+## Example
+
+This project comes with a sample Pyramid application (see the `example` folder). This app displays videos
+that can be played on YouTube. The image, author subtitle, and view count are reused throughout the
+app. Here's a visual:
+
+![Video image, author, and view count HTML reused across pages of the demo app](https://raw.githubusercontent.com/mikeckennedy/chameleon_partials/main/readme_resources/reused-html-visual.png)
+
+Check out the [**demo / example application**](https://github.com/mikeckennedy/chameleon_partials/tree/main/example) 
+to see it in action. 
+
+## Installation
+
+It's just `pip install chameleon-partials` and you're all set with this pure Python package.
+
+## Usage
+
+Using the library is incredibly easy. The first step is to register the partial method with Chameleon.
+Do this once at app startup:
+
+```python
+from pathlib import Path
+
+from pyramid.config import Configurator
+
+import chameleon_partials
+
+def main(_, **settings):
+    """ This function returns a Pyramid WSGI application.
+    """
+    with Configurator(settings=settings) as config:
+        config.include('pyramid_chameleon')
+        config.include('.routes')
+        config.scan()
+        
+        # Register the extension for working with Chameleon.
+        folder = (Path(__file__).parent / "templates").as_posix()
+        chameleon_partials.register_extensions(folder, auto_reload=True, cache_init=True)
+
+    return config.make_wsgi_app()
+```
+
+Next, you define your main HTML (Chameleon) templates as usual. Then 
+define your partial templates. I recommend locating and naming them accordingly:
+
+```
+├── templates
+│   ├── errors
+│   │   └── 404.pt
+│   ├── home
+│   │   ├── index.pt
+│   │   └── listing.pt
+│   └── shared
+│       ├── _layout.pt
+│       └── partials
+│           ├── video_image.pt
+│           └── video_square.pt
+```
+
+Notice the `partials` subfolder in the `templates/shared` folder.
+
+The templates are just HTML fragments. Here is a stand-alone one for the YouTube thumbnail from
+the example app:
+
+```html
+<img src="https://img.youtube.com/vi/${ video.id }/maxresdefault.jpg"
+     class="img img-responsive ${ ' '.join(classes or []) }"
+     alt="${ video.title }"
+     title="${ video.title }">
+```
+
+Notice that an object called `video` and a list of classes are passed in as the model.
+
+Templates can also be nested. Here is the whole single video fragment with the image as well as other info
+linking out to YouTube:
+
+```html
+<div>
+    <a href="https://www.youtube.com/watch?v=${ video.id }" target="_blank">
+        ${ render_partial('shared/partials/video_image.pt', video=video, classes=[]) }
+    </a>
+    <a href="https://www.youtube.com/watch?v=${ video.id }" target="_blank"
+       class="author">${ video.author }</a>
+    <div class="views">${ "{:,}".format(video.views) } views</div>
+</div>
+```
+
+Now you see the `render_partial()` method. It takes the subpath into the templates folder and
+any model data passed in as keyword arguments.
+
+We can finally generate the list of video blocks as follows:
+
+```html
+<span class="video" tal:repeat="v videos">
+    ${ render_partial('shared/partials/video_square.pt', video=v) }
+</span>
+```
+
+This time, we reframe each item in the list from the outer template (called `v`) as the `video` model
+in the inner HTML section.
+
+## The View Methods
+
+In order to share the `render_partial()` function with your template, you'll need to pass it along to the
+template with your model (dictionary). 
+
+If you are using the **Pyramid web framework**, you can add this file as middleware. Just drop it into
+your `views` folder:
+
+```python
+# views/partials_middleware.py
+from pyramid.events import subscriber, BeforeRender
+
+import chameleon_partials
+
+
+@subscriber(BeforeRender)
+def add_global(event):
+    event['render_partial'] = chameleon_partials.render_partial
+```
+
+For other frameworks using Chameleon (e.g. FastAPI), you can add `render_partial` to the
+resulting dictionary. We've built a simple function to keep this fool-proof: 
+
+```python
+chameleon_partials.extend_model(model)
+```
+
+Here's a typical view method that uses `render_partial`, notice the use of extending the 
+model before passing it to the template (the example app's views skip this because the 
+middleware above handles it):
+
+```python
+@view_config(route_name='listing', renderer='demo_chameleon_partials:templates/home/listing.pt')
+def listing(_):
+    videos = video_service.all_videos()
+    model = dict(videos=videos)
+    return chameleon_partials.extend_model(model)
+```
+
+Again: If you are using Pyramid, use the middleware. Otherwise, use the `extend_model()` method or something 
+similar to the middleware in your framework.

chameleon_partials-0.2.0/chameleon_partials/__init__.py

@@ -0,0 +1,201 @@
+"""
+chameleon_partials - Simple reuse of partial HTML page templates in the
+Chameleon template language for Python web frameworks.
+
+Register your template folder once at application startup, then call `render_partial`
+from any Chameleon template to insert a reusable HTML fragment, passing keyword
+arguments as the fragment's model. Partials can nest: every partial automatically
+receives `render_partial`, so fragments can compose further fragments. Works with any
+framework that renders Chameleon templates (Pyramid, FastAPI, and friends).
+
+A minimal quickstart:
+
+```python
+import chameleon_partials
+
+chameleon_partials.register_extensions('path/to/templates')
+html = chameleon_partials.render_partial('shared/partials/video_image.pt', video=video)
+```
+"""
+
+__version__ = '0.2.0'
+__author__ = 'Michael Kennedy <michael@talkpython.fm>'
+__all__ = [
+    'register_extensions',
+    'render_partial',
+    'PartialsException',
+    'extend_model',
+]
+
+import os
+from typing import Any, Dict, Optional
+
+from chameleon import PageTemplate, PageTemplateLoader
+
+has_registered_extensions: bool = False
+
+__templates: Optional[PageTemplateLoader] = None
+template_path: Optional[str] = None
+
+
+class PartialsException(Exception):
+    """Raised when chameleon_partials is configured or used incorrectly.
+
+    Examples include registering with a missing template folder, rendering a partial
+    before calling `register_extensions`, or passing a non-dictionary model to
+    `extend_model`. Errors raised by Chameleon itself, such as the `ValueError` for a
+    missing template file, are propagated unchanged rather than wrapped in this type.
+    """
+
+
+def register_extensions(template_folder: str, auto_reload: bool = False, cache_init: bool = True) -> None:
+    """Register chameleon_partials with Chameleon so partials can be rendered.
+
+    Call this once during application startup, before any template is rendered. It builds a
+    Chameleon `PageTemplateLoader` rooted at `template_folder` and stores it in module-level
+    state that `render_partial` uses to locate templates. Registration is process-wide and is
+    not guarded by a lock, so call it from normal single-threaded startup code rather than
+    from concurrent request handlers.
+
+    Args:
+        template_folder: Path to the root folder containing your Chameleon templates (with a
+            `partials` subfolder by convention). Must be an existing directory. Partials are
+            later looked up by path relative to this folder.
+        auto_reload: When `True`, Chameleon reloads a template from disk whenever the file
+            changes. Useful during development; leave `False` in production.
+        cache_init: When `True` (the default), calling this again after a previous
+            successful registration is a no-op, which makes repeated startup calls safe.
+            Pass `False` to force re-registration, for example to point at a different
+            template folder in tests.
+
+    Raises:
+        PartialsException: If `template_folder` is empty or is not an existing directory.
+
+    Examples:
+        ```python
+        import chameleon_partials
+
+        # At startup; use auto_reload=True while developing.
+        chameleon_partials.register_extensions('path/to/templates', auto_reload=True)
+        ```
+    """
+    global has_registered_extensions
+    global __templates, template_path
+
+    if has_registered_extensions and cache_init:
+        return
+
+    if not template_folder:
+        msg = 'The template_folder must be specified.'
+        raise PartialsException(msg)
+
+    if not os.path.isdir(template_folder):
+        msg = f"The specified template folder must be a folder, it's not: {template_folder}"
+        raise PartialsException(msg)
+
+    template_path = template_folder
+    __templates = PageTemplateLoader(template_folder, auto_reload=auto_reload)
+
+    # Mark as registered only after the loader was built successfully, so a call that
+    # raised above does not leave the extension flagged as registered (which would turn a
+    # later default cache_init=True retry into a silent no-op).
+    has_registered_extensions = True
+
+
+class HTML:
+    """A thin wrapper that marks a string as already-rendered, safe HTML.
+
+    `render_partial` returns one of these. Chameleon (and other template engines) call an
+    object's `__html__` method when present, so the wrapped markup is inserted verbatim
+    instead of being escaped. This type is internal and is not part of the public `__all__`
+    API; read the `html_text` attribute when you need the raw markup, for example in tests.
+
+    Attributes:
+        html_text: The rendered markup as a `str`.
+    """
+
+    def __init__(self, html_text: str) -> None:
+        self.html_text: str = html_text
+
+    def __html__(self) -> str:
+        return self.html_text
+
+
+def render_partial(template_file: str, **template_data: Any) -> HTML:
+    """Render a partial template to an HTML fragment.
+
+    Looks up `template_file` in the folder registered with `register_extensions` and renders
+    it with the supplied keyword arguments as its model. `render_partial` is injected into the
+    model automatically, so a partial can render further nested partials. The fragment is
+    rendered as text (`str`); any `bytes` values in the model are decoded as UTF-8.
+
+    Args:
+        template_file: Path to the partial, relative to the registered templates folder, for
+            example `shared/partials/video_image.pt`.
+        **template_data: Keyword arguments passed to the template as its model (the variables
+            the template can reference). Values may be any Python objects your template
+            expressions use. The name `encoding` is reserved and cannot be used; `translate`,
+            `target_language`, and `repeat` have special meaning to Chameleon.
+
+    Returns:
+        An `HTML` wrapper whose `__html__` method yields the rendered markup as safe, pre-escaped HTML.
+
+    Raises:
+        PartialsException: If `register_extensions` has not been called yet.
+        ValueError: Propagated from Chameleon if `template_file` does not exist under the registered folder.
+
+    Examples:
+        ```python
+        import chameleon_partials
+
+        chameleon_partials.register_extensions('path/to/templates')
+        html = chameleon_partials.render_partial('shared/partials/user_card.pt', name='Sarah', age=32)
+        print(html.html_text)
+        ```
+    """
+    if not has_registered_extensions:
+        raise PartialsException('You must call register_extensions() before this function can be used.')
+
+    if 'render_partial' not in template_data:
+        template_data['render_partial'] = render_partial
+
+    assert __templates is not None  # Guaranteed by the has_registered_extensions guard above.
+    page: PageTemplate = __templates[template_file]
+    html_source = page.render(encoding='utf-8', **template_data)
+    return HTML(html_source)
+
+
+def extend_model(model: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    """Add `render_partial` to a view model so templates can call it.
+
+    Use this in frameworks where a view returns a model dictionary (for example FastAPI) and
+    you need `render_partial` available inside the template. For Pyramid, prefer the
+    `BeforeRender` middleware shown in the README instead. Any existing `render_partial` key
+    in the model is replaced.
+
+    Args:
+        model: The view model dictionary to extend. `None` is treated as an empty model.
+
+    Returns:
+        The same dictionary with a `render_partial` key added, or a new dictionary when `model` is `None`.
+
+    Raises:
+        PartialsException: If `model` is not a dictionary (and not `None`).
+
+    Examples:
+        ```python
+        import chameleon_partials
+
+        model = {'name': 'Sarah'}
+        model = chameleon_partials.extend_model(model)
+        # model['render_partial'] is now callable from the template.
+        ```
+    """
+    if model is None:
+        model = {}
+
+    if not isinstance(model, dict):
+        raise PartialsException('The model must be a dictionary.')
+
+    model['render_partial'] = render_partial
+    return model

chameleon_partials-0.2.0/chameleon_partials.egg-info/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: chameleon_partials
+Version: 0.2.0
+Summary: Simple reuse of partial HTML page templates in the Chameleon template language for Python web frameworks.
+Author-email: Michael Kennedy <michael@talkpython.fm>
+License: MIT
+Project-URL: Homepage, https://github.com/mikeckennedy/chameleon_partials
+Project-URL: Repository, https://github.com/mikeckennedy/chameleon_partials
+Project-URL: Documentation, https://mkennedy.codes/docs/chameleon-partials/
+Project-URL: Issues, https://github.com/mikeckennedy/chameleon_partials/issues
+Project-URL: Changelog, https://github.com/mikeckennedy/chameleon_partials/blob/main/CHANGELOG.md
+Project-URL: Funding, https://github.com/sponsors/mikeckennedy
+Keywords: chameleon,partials,templates,templating,template-engine,html,rendering,render-partial,components,fragments,reusable,web,web-development,web-framework,pyramid,fastapi,htmx,frontend,jinja-partials,zpt,tal,metal
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: chameleon
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-clarity; extra == "dev"
+Requires-Dist: ty; extra == "dev"
+Requires-Dist: pyrefly; extra == "dev"
+Requires-Dist: great-docs; python_version >= "3.11" and extra == "dev"
+Dynamic: license-file
+
+# Chameleon Partials
+
+Simple reuse of partial HTML page templates in the Chameleon template language for Python web frameworks.
+(There is also a [Jinja2/Flask version here](https://github.com/mikeckennedy/jinja_partials).)
+
+## Overview
+
+When building real-world web apps with Chameleon, it's easy to end up with repeated HTML fragments.
+Just like organizing code for reuse, it would be ideal to reuse smaller sections of HTML template code.
+That's what this library is all about.
+
+## Documentation
+
+Full documentation lives at
+[mkennedy.codes/docs/chameleon-partials](https://mkennedy.codes/docs/chameleon-partials/),
+including the complete [API reference](https://mkennedy.codes/docs/chameleon-partials/reference/)
+generated from the library's docstrings.
+
+## Example
+
+This project comes with a sample Pyramid application (see the `example` folder). This app displays videos
+that can be played on YouTube. The image, author subtitle, and view count are reused throughout the
+app. Here's a visual:
+
+![Video image, author, and view count HTML reused across pages of the demo app](https://raw.githubusercontent.com/mikeckennedy/chameleon_partials/main/readme_resources/reused-html-visual.png)
+
+Check out the [**demo / example application**](https://github.com/mikeckennedy/chameleon_partials/tree/main/example) 
+to see it in action. 
+
+## Installation
+
+It's just `pip install chameleon-partials` and you're all set with this pure Python package.
+
+## Usage
+
+Using the library is incredibly easy. The first step is to register the partial method with Chameleon.
+Do this once at app startup:
+
+```python
+from pathlib import Path
+
+from pyramid.config import Configurator
+
+import chameleon_partials
+
+def main(_, **settings):
+    """ This function returns a Pyramid WSGI application.
+    """
+    with Configurator(settings=settings) as config:
+        config.include('pyramid_chameleon')
+        config.include('.routes')
+        config.scan()
+        
+        # Register the extension for working with Chameleon.
+        folder = (Path(__file__).parent / "templates").as_posix()
+        chameleon_partials.register_extensions(folder, auto_reload=True, cache_init=True)
+
+    return config.make_wsgi_app()
+```
+
+Next, you define your main HTML (Chameleon) templates as usual. Then 
+define your partial templates. I recommend locating and naming them accordingly:
+
+```
+├── templates
+│   ├── errors
+│   │   └── 404.pt
+│   ├── home
+│   │   ├── index.pt
+│   │   └── listing.pt
+│   └── shared
+│       ├── _layout.pt
+│       └── partials
+│           ├── video_image.pt
+│           └── video_square.pt
+```
+
+Notice the `partials` subfolder in the `templates/shared` folder.
+
+The templates are just HTML fragments. Here is a stand-alone one for the YouTube thumbnail from
+the example app:
+
+```html
+<img src="https://img.youtube.com/vi/${ video.id }/maxresdefault.jpg"
+     class="img img-responsive ${ ' '.join(classes or []) }"
+     alt="${ video.title }"
+     title="${ video.title }">
+```
+
+Notice that an object called `video` and a list of classes are passed in as the model.
+
+Templates can also be nested. Here is the whole single video fragment with the image as well as other info
+linking out to YouTube:
+
+```html
+<div>
+    <a href="https://www.youtube.com/watch?v=${ video.id }" target="_blank">
+        ${ render_partial('shared/partials/video_image.pt', video=video, classes=[]) }
+    </a>
+    <a href="https://www.youtube.com/watch?v=${ video.id }" target="_blank"
+       class="author">${ video.author }</a>
+    <div class="views">${ "{:,}".format(video.views) } views</div>
+</div>
+```
+
+Now you see the `render_partial()` method. It takes the subpath into the templates folder and
+any model data passed in as keyword arguments.
+
+We can finally generate the list of video blocks as follows:
+
+```html
+<span class="video" tal:repeat="v videos">
+    ${ render_partial('shared/partials/video_square.pt', video=v) }
+</span>
+```
+
+This time, we reframe each item in the list from the outer template (called `v`) as the `video` model
+in the inner HTML section.
+
+## The View Methods
+
+In order to share the `render_partial()` function with your template, you'll need to pass it along to the
+template with your model (dictionary). 
+
+If you are using the **Pyramid web framework**, you can add this file as middleware. Just drop it into
+your `views` folder:
+
+```python
+# views/partials_middleware.py
+from pyramid.events import subscriber, BeforeRender
+
+import chameleon_partials
+
+
+@subscriber(BeforeRender)
+def add_global(event):
+    event['render_partial'] = chameleon_partials.render_partial
+```
+
+For other frameworks using Chameleon (e.g. FastAPI), you can add `render_partial` to the
+resulting dictionary. We've built a simple function to keep this fool-proof: 
+
+```python
+chameleon_partials.extend_model(model)
+```
+
+Here's a typical view method that uses `render_partial`, notice the use of extending the 
+model before passing it to the template (the example app's views skip this because the 
+middleware above handles it):
+
+```python
+@view_config(route_name='listing', renderer='demo_chameleon_partials:templates/home/listing.pt')
+def listing(_):
+    videos = video_service.all_videos()
+    model = dict(videos=videos)
+    return chameleon_partials.extend_model(model)
+```
+
+Again: If you are using Pyramid, use the middleware. Otherwise, use the `extend_model()` method or something 
+similar to the middleware in your framework.

chameleon_partials-0.2.0/chameleon_partials.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+requirements-dev.txt
+requirements.txt
+chameleon_partials/__init__.py
+chameleon_partials/py.typed
+chameleon_partials.egg-info/PKG-INFO
+chameleon_partials.egg-info/SOURCES.txt
+chameleon_partials.egg-info/dependency_links.txt
+chameleon_partials.egg-info/requires.txt
+chameleon_partials.egg-info/top_level.txt
+tests/test_rendering.py

chameleon_partials-0.2.0/chameleon_partials.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

chameleon_partials-0.2.0/chameleon_partials.egg-info/requires.txt

@@ -0,0 +1,10 @@
+chameleon
+
+[dev]
+pytest
+pytest-clarity
+ty
+pyrefly
+
+[dev:python_version >= "3.11"]
+great-docs

chameleon_partials-0.2.0/chameleon_partials.egg-info/top_level.txt

@@ -0,0 +1 @@
+chameleon_partials

chameleon_partials-0.2.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chameleon_partials"
+description = "Simple reuse of partial HTML page templates in the Chameleon template language for Python web frameworks."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Michael Kennedy", email = "michael@talkpython.fm" }]
+requires-python = ">=3.9"
+keywords = [
+    "chameleon",
+    "partials",
+    "templates",
+    "templating",
+    "template-engine",
+    "html",
+    "rendering",
+    "render-partial",
+    "components",
+    "fragments",
+    "reusable",
+    "web",
+    "web-development",
+    "web-framework",
+    "pyramid",
+    "fastapi",
+    "htmx",
+    "frontend",
+    "jinja-partials",
+    "zpt",
+    "tal",
+    "metal",
+]
+# version, dependencies, and optional-dependencies are read dynamically below so the
+# package version stays single-sourced in chameleon_partials/__init__.py and the
+# requirements*.txt files remain the source of truth for dependencies.
+dynamic = ["version", "dependencies", "optional-dependencies"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+]
+
+[project.urls]
+Homepage = "https://github.com/mikeckennedy/chameleon_partials"
+Repository = "https://github.com/mikeckennedy/chameleon_partials"
+Documentation = "https://mkennedy.codes/docs/chameleon-partials/"
+Issues = "https://github.com/mikeckennedy/chameleon_partials/issues"
+Changelog = "https://github.com/mikeckennedy/chameleon_partials/blob/main/CHANGELOG.md"
+Funding = "https://github.com/sponsors/mikeckennedy"
+
+[tool.setuptools]
+packages = ["chameleon_partials"]
+
+# Ship the PEP 561 marker so type checkers consume the package's inline annotations.
+# Explicit because the build floor (setuptools>=64) predates automatic py.typed inclusion.
+[tool.setuptools.package-data]
+chameleon_partials = ["py.typed"]
+
+[tool.setuptools.dynamic]
+version = { attr = "chameleon_partials.__version__" }
+dependencies = { file = ["requirements.txt"] }
+
+[tool.setuptools.dynamic.optional-dependencies]
+dev = { file = ["requirements-dev.txt"] }
+
+# Only collect this package's own tests by default. The `example/` demo is a
+# standalone Pyramid project with its own test suite and dependencies (Pyramid,
+# WebTest — see example/setup.py's `testing` extra), so a bare `pytest` from the
+# repo root must not try to import them.
+[tool.pytest.ini_options]
+testpaths = ["tests"]

chameleon_partials-0.2.0/requirements-dev.txt

@@ -0,0 +1,9 @@
+pytest
+pytest-clarity
+# Type checkers; the package ships a py.typed marker, so keep its annotations honest.
+ty
+pyrefly
+# great-docs builds the documentation site (Phase 1 of the docs playbook). The
+# marker keeps `pip install .[dev]` working on Python 3.10 and below, where
+# great-docs (which requires >=3.11) is simply skipped.
+great-docs; python_version >= '3.11'

chameleon_partials-0.2.0/requirements.txt

@@ -0,0 +1 @@
+chameleon

chameleon_partials-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

chameleon_partials-0.2.0/tests/test_rendering.py

@@ -0,0 +1,65 @@
+"""Rendering tests for chameleon_partials: bare partials, partials with model data,
+layouts, nested (recursive) partials, and error conditions (missing template, and
+rendering before register_extensions)."""
+
+from pathlib import Path
+
+# noinspection PyPackageRequirements
+import pytest as pytest
+
+import chameleon_partials
+
+
+@pytest.fixture
+def registered_extension():
+    folder = (Path(__file__).parent / 'test_templates').as_posix()
+    chameleon_partials.register_extensions(folder, auto_reload=True, cache_init=True)
+
+    # Allow test to work with extensions as registered
+    print('********************************************')
+    print(folder)
+    print('********************************************')
+    yield
+
+    # Roll back the fact that we registered the extensions for future tests.
+    chameleon_partials.has_registered_extensions = False
+
+
+def test_render_empty(registered_extension):
+    html: chameleon_partials.HTML = chameleon_partials.render_partial('render/bare.pt')
+    assert '<h1>This is bare HTML fragment</h1>' in html.html_text
+
+
+def test_render_with_data(registered_extension):
+    name = 'Sarah'
+    age = 32
+    html: chameleon_partials.HTML = chameleon_partials.render_partial('render/with_data.pt', name=name, age=age)
+    assert f'<span>Your name is {name} and age is {age}</span>' in html.html_text
+
+
+def test_render_with_layout(registered_extension):
+    value_text = 'The message is clear'
+    html: chameleon_partials.HTML = chameleon_partials.render_partial('render/with_layout.pt', message=value_text)
+    assert '<title>Chameleon Partials Test Template</title>' in html.html_text
+    assert value_text in html.html_text
+
+
+def test_render_recursive(registered_extension):
+    value_text = 'The message is clear'
+    inner_text = 'The message is recursive'
+
+    html: chameleon_partials.HTML = chameleon_partials.render_partial(
+        'render/recursive.pt', message=value_text, inner=inner_text
+    )
+    assert value_text in html.html_text
+    assert inner_text in html.html_text
+
+
+def test_missing_template(registered_extension):
+    with pytest.raises(ValueError):
+        chameleon_partials.render_partial('no-way.pt', message=7)
+
+
+def test_not_registered():
+    with pytest.raises(chameleon_partials.PartialsException):
+        chameleon_partials.render_partial('doesnt-matter.pt', message=7)