citry-django 0.1.0__tar.gz

citry_django-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+venv/
+citry-src/
+__pycache__/
+*.pyc
+*.egg-info/
+db.sqlite3
+.static/
+.media/
+.pytest_cache/
+.ruff_cache/

citry_django-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joey Jurjens
+
+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.

citry_django-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.5
+Name: citry-django
+Version: 0.1.0
+Summary: Citry and Django's template engines, composed: real Django tags and filters inside Citry components, and Citry components inside Django templates.
+Project-URL: Repository, https://github.com/joeyjurjens/citry-django
+Project-URL: Issues, https://github.com/joeyjurjens/citry-django/issues
+Author-email: Joey Jurjens <joeyjurjens@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: citry,components,django,templates
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: citry>=0.4.3
+Requires-Dist: django>=5.2
+Provides-Extra: compressor
+Requires-Dist: citry-django-compressor; extra == 'compressor'
+Provides-Extra: django-components
+Requires-Dist: citry-django-djc; extra == 'django-components'
+Description-Content-Type: text/markdown
+
+# citry-django
+
+Citry and Django's template engines, composed.
+
+```python
+from citry import Citry
+from citry_django import CitryDjangoExtension
+
+app = Citry(extensions=[CitryDjangoExtension()])
+```
+
+```python
+# settings.py
+TEMPLATES = [{"BACKEND": "citry_django.backend.CitryTemplates", "APP_DIRS": True, ...}]
+CITRY_APP = "myproject.app:app"
+```
+
+Any `{% tag %}` you can `{% load %}` in Django then works inside a Citry
+component, and Citry components work in your existing Django templates. Neither
+syntax changes, and the adapter names no tag: each engine's own parser decides
+what belongs to it.
+
+See the [repository README](https://github.com/joeyjurjens/citry-django) for the
+full picture, the limits, and how it works.
+
+## Optional extras
+
+```bash
+pip install citry-django[compressor]
+```
+
+Routes each component's CSS and JS through [django-compressor], so assets are
+preprocessed (SCSS, Less, ...) and minified. See `citry-django-compressor`.
+
+[django-compressor]: https://django-compressor.readthedocs.io/

citry_django-0.1.0/README.md

@@ -0,0 +1,35 @@
+# citry-django
+
+Citry and Django's template engines, composed.
+
+```python
+from citry import Citry
+from citry_django import CitryDjangoExtension
+
+app = Citry(extensions=[CitryDjangoExtension()])
+```
+
+```python
+# settings.py
+TEMPLATES = [{"BACKEND": "citry_django.backend.CitryTemplates", "APP_DIRS": True, ...}]
+CITRY_APP = "myproject.app:app"
+```
+
+Any `{% tag %}` you can `{% load %}` in Django then works inside a Citry
+component, and Citry components work in your existing Django templates. Neither
+syntax changes, and the adapter names no tag: each engine's own parser decides
+what belongs to it.
+
+See the [repository README](https://github.com/joeyjurjens/citry-django) for the
+full picture, the limits, and how it works.
+
+## Optional extras
+
+```bash
+pip install citry-django[compressor]
+```
+
+Routes each component's CSS and JS through [django-compressor], so assets are
+preprocessed (SCSS, Less, ...) and minified. See `citry-django-compressor`.
+
+[django-compressor]: https://django-compressor.readthedocs.io/

citry_django-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "citry-django"
+version = "0.1.0"
+description = "Citry and Django's template engines, composed: real Django tags and filters inside Citry components, and Citry components inside Django templates."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Joey Jurjens", email = "joeyjurjens@gmail.com" }]
+keywords = ["citry", "django", "templates", "components"]
+dependencies = ["citry>=0.4.3", "django>=5.2"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Web Environment",
+    "Framework :: Django",
+    "Framework :: Django :: 5.2",
+    "Framework :: Django :: 6.0",
+    "Framework :: Django :: 6.1",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "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",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+django-components = ["citry-django-djc"]
+compressor = ["citry-django-compressor"]
+
+[project.urls]
+Repository = "https://github.com/joeyjurjens/citry-django"
+Issues = "https://github.com/joeyjurjens/citry-django/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/citry_django"]

citry_django-0.1.0/src/citry_django/__init__.py

@@ -0,0 +1,23 @@
+"""
+citry_django -- Citry and Django's template engines, composed.
+
+Each engine owns its own files and delegates the other's syntax to the other's
+*real* engine, so both keep their full feature sets::
+
+    from citry import Citry
+    from citry_django import CitryDjangoExtension
+
+    app = Citry(extensions=[CitryDjangoExtension()])
+
+Any ``{% tag %}`` you can ``{% load %}`` in Django then works inside a Citry
+component, with no per-tag code. For the reverse direction -- Citry syntax in
+your existing Django templates -- point ``settings.TEMPLATES`` at
+``citry_django.backend.CitryTemplates`` and set ``CITRY_APP``.
+"""
+
+from .extension import CitryDjangoExtension, ForeignNode
+
+__all__ = [
+    "CitryDjangoExtension",
+    "ForeignNode",
+]

citry_django-0.1.0/src/citry_django/backend.py

@@ -0,0 +1,75 @@
+"""
+A Django template backend that understands Citry element syntax.
+
+Swap ``BACKEND`` in ``settings.TEMPLATES`` and ``<c-hero/>`` works in every
+Django template::
+
+    TEMPLATES = [{
+        "BACKEND": "citry_django.backend.CitryTemplates",
+        "DIRS": [...],
+        "APP_DIRS": True,
+        "OPTIONS": {"context_processors": [...]},
+    }]
+
+This is still Django's own engine: same lexer, same tags, same inheritance. The
+only difference is that source is rewritten as it is read, so ``<c-component/>``
+becomes a tag Django can compile. A template with no Citry syntax in it is
+returned unchanged.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.template.backends.django import DjangoTemplates
+
+from .rewrite import rewrite_source
+
+_TAGS = "citry_django.templatetags.citry"
+
+
+class _RewriteMixin:
+    """Rewrites Citry element syntax as a loader reads a template."""
+
+    def get_contents(self, origin: Any) -> str:
+        return rewrite_source(super().get_contents(origin), origin=origin.name)
+
+
+def _enable_rewriting(loaders: Any) -> None:
+    """
+    Teach every configured loader to rewrite, whoever wrote it.
+
+    Django resolves ``get_contents`` on the loader that finally reads the file,
+    so rewriting is added there rather than by substituting loader classes. A
+    project that configures its own ``loaders`` -- for a component library, a
+    pattern library, or just to control caching -- keeps them and gets Citry
+    syntax in the templates they load.
+    """
+    for loader in loaders:
+        nested = getattr(loader, "loaders", None)
+        if nested:
+            _enable_rewriting(nested)
+        elif not isinstance(loader, _RewriteMixin):
+            cls = type(loader)
+            loader.__class__ = type(f"Rewriting{cls.__name__}", (_RewriteMixin, cls), {})
+
+
+class CitryTemplates(DjangoTemplates):
+    def __init__(self, params: dict) -> None:
+        params = params.copy()
+        options = params.setdefault("OPTIONS", {}).copy()
+        params["OPTIONS"] = options
+
+        # The rewriter injects its tag into templates that have no `{% load %}`
+        # line of their own, so it has to resolve as a builtin.
+        builtins = list(options.get("builtins", []))
+        if _TAGS not in builtins:
+            builtins.append(_TAGS)
+        options["builtins"] = builtins
+
+        super().__init__(params)
+        _enable_rewriting(self.engine.template_loaders)
+
+    def from_string(self, template_code: str) -> Any:
+        # `from_string` never reaches a loader, so it rewrites here as well.
+        return super().from_string(rewrite_source(template_code, origin="<string template>"))

citry_django-0.1.0/src/citry_django/expressions.py

@@ -0,0 +1,86 @@
+"""
+Deciding who owns a ``{{ ... }}`` inside a Citry template.
+
+Both engines spell interpolation the same way, so the decision is made per
+expression, at compile time:
+
+1. Not a valid Python expression -> Django (``{{ x|date:"Y-m-d" }}``).
+2. A plain dotted path -> Django, whose lookup is a superset of Python's
+   attribute access: dictionary, then attribute, then index. ``{{ d.key }}``
+   on a dict is why this matters.
+3. A filter chain whose filter names Django's live registry knows -> Django.
+4. Otherwise -> Citry.
+
+Rule 3 is the only genuine overlap: ``a|b`` is both a filter application and a
+bitwise or, resolved by asking the registry the template's own ``{% load %}``
+lines populate. A Python variable named after a registered filter is therefore
+read as the filter.
+"""
+
+from __future__ import annotations
+
+import ast
+from functools import cache
+
+
+def is_django_expression(expression: str, engine, extra_libraries: tuple[str, ...] = ()) -> bool:
+    """Whether ``{{ expression }}`` should be handed to Django."""
+    text = expression.strip()
+    if not text:
+        return True
+
+    try:
+        parsed = ast.parse(text, mode="eval")
+    except SyntaxError:
+        # Not Python at all: filter arguments (`|date:"Y-m-d"`), translation
+        # syntax, and so on.
+        return True
+
+    node = parsed.body
+
+    # A plain dotted path is Django's, because Django's lookup is a superset of
+    # Python's attribute access there: it tries dictionary, then attribute,
+    # then index. `{{ d.key }}` on a dict is the case that matters -- Python
+    # attribute access fails on it, Django resolves it, and every Django
+    # template in existence writes it that way.
+    if _is_dotted_path(node):
+        return True
+
+    if not (isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr)):
+        return False
+
+    known = _filter_names(engine, extra_libraries)
+    while isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
+        if not (isinstance(node.right, ast.Name) and node.right.id in known):
+            return False
+        node = node.left
+    return True
+
+
+def _is_dotted_path(node: ast.AST) -> bool:
+    """
+    Whether the expression is only names joined by dots, e.g. ``a.b.c``.
+
+    A bare name is excluded: both engines resolve one identically, and leaving
+    it with Citry keeps Citry's strictness about unknown names. Anything with a
+    call, subscript or operator stays Citry's too, since Django cannot express
+    those at all.
+    """
+    if not isinstance(node, ast.Attribute):
+        return False
+    while isinstance(node, ast.Attribute):
+        node = node.value
+    return isinstance(node, ast.Name)
+
+
+@cache
+def _filter_names(engine, extra_libraries: tuple[str, ...]) -> frozenset[str]:
+    """Every filter name in scope: the engine's builtins plus loaded libraries."""
+    names: set[str] = set()
+    for library in engine.template_builtins:
+        names.update(library.filters)
+    for label in extra_libraries:
+        library = engine.template_libraries.get(label)
+        if library is not None:
+            names.update(library.filters)
+    return frozenset(names)