jinjafile

Class info

Classes

Name	Children	Inherits
JinjaFile jinjarope.jinjafile A file defining filters / tests.		dict
JinjaItem jinjarope.jinjafile An item representing a filter / test.		object

🛈 DocStrings

JinjaFile

Bases: dict[str, Any]

A file defining filters / tests.

Source code in src/jinjarope/jinjafile.py

class JinjaFile(dict[str, Any]):
    """A file defining filters / tests."""

    def __init__(self, path: str | os.PathLike[str]):
        """Instanciate the file.

        Args:
            path: Path to the jinja file
        """
        super().__init__()
        text = envglobals.load_file_cached(os.fspath(path))
        data = _load(text)
        self.update(data)

    @property
    def filters(self) -> list[JinjaItem]:
        """Return list of filters defined in the file."""
        return [
            JinjaItem(filter_name, typ="filter", **dct)
            for filter_name, dct in self.get("filters", {}).items()
            if all(envtests.is_installed(i) for i in dct.get("required_packages", []))
        ]

    @property
    def tests(self) -> list[JinjaItem]:
        """Return list of tests defined in the file."""
        return [
            JinjaItem(filter_name, typ="test", **dct)
            for filter_name, dct in self.get("tests", {}).items()
            if all(envtests.is_installed(i) for i in dct.get("required_packages", []))
        ]

    @property
    def functions(self) -> list[JinjaItem]:
        """Return list of functions defined in the file."""
        return [
            JinjaItem(filter_name, typ="function", **dct)
            for filter_name, dct in self.get("functions", {}).items()
            if all(envtests.is_installed(i) for i in dct.get("required_packages", []))
        ]

    @property
    def filters_dict(self) -> dict[str, Callable[..., Any]]:
        """Return a dictionary with all filters.

        Can directly get merged into env filters.
        """
        dct = {}
        for f in self.filters:
            dct[f.identifier] = f.filter_fn
            for alias in f.aliases:
                dct[alias] = f.filter_fn
        return dct

    @property
    def tests_dict(self) -> dict[str, Callable[..., bool]]:
        """Return a dictionary with all filters.

        Can directly get merged into env filters.
        """
        dct = {}
        for f in self.tests:
            dct[f.identifier] = f.filter_fn
            for alias in f.aliases:
                dct[alias] = f.filter_fn
        return dct

    @property
    def functions_dict(self) -> dict[str, Callable[..., Any]]:
        """Return a dictionary with all filters.

        Can directly get merged into env filters.
        """
        dct = {}
        for f in self.functions:
            dct[f.identifier] = f.filter_fn
            for alias in f.aliases:
                dct[alias] = f.filter_fn
        return dct

    @property
    def envconfig(self) -> envconfig.EnvConfig:
        """Return the config object defined in this Jinja file."""
        cfg = self.get("config", {})
        return envconfig.EnvConfig(**cfg, loader=self.loader)

    @property
    def loader(self) -> jinja2.BaseLoader | None:
        """Return a (composed Choice-) loader defined in this Jinja file."""
        return loaders.from_json(self.get("loaders", []))

envconfig property

envconfig: EnvConfig

Return the config object defined in this Jinja file.

filters property

filters: list[JinjaItem]

Return list of filters defined in the file.

filters_dict property

filters_dict: dict[str, Callable[..., Any]]

Return a dictionary with all filters.

Can directly get merged into env filters.

functions property

functions: list[JinjaItem]

Return list of functions defined in the file.

functions_dict property

functions_dict: dict[str, Callable[..., Any]]

Return a dictionary with all filters.

Can directly get merged into env filters.

loader property

loader: BaseLoader | None

Return a (composed Choice-) loader defined in this Jinja file.

tests property

tests: list[JinjaItem]

Return list of tests defined in the file.

tests_dict property

tests_dict: dict[str, Callable[..., bool]]

Return a dictionary with all filters.

Can directly get merged into env filters.

__init__

__init__(path: str | PathLike[str])

Instanciate the file.

Parameters:

Name	Type	Description	Default
path	str | PathLike[str]	Path to the jinja file	required

Source code in src/jinjarope/jinjafile.py

def __init__(self, path: str | os.PathLike[str]):
    """Instanciate the file.

    Args:
        path: Path to the jinja file
    """
    super().__init__()
    text = envglobals.load_file_cached(os.fspath(path))
    data = _load(text)
    self.update(data)

JinjaItem dataclass

An item representing a filter / test.

Source code in src/jinjarope/jinjafile.py

@dataclasses.dataclass(frozen=True)
class JinjaItem:
    """An item representing a filter / test."""

    identifier: str
    typ: Literal["filter", "test", "function"]
    fn: str
    group: str
    icon: str | None = None
    examples: dict[str, dict[str, str]] = dataclasses.field(default_factory=dict)
    description: str | None = None
    aliases: list[str] = dataclasses.field(default_factory=list)
    required_packages: list[str] = dataclasses.field(default_factory=list)

    def __repr__(self):
        return utils.get_repr(self, self.identifier)

    @property
    def filter_fn(self) -> Callable[..., Any]:
        """Return the callable to use as filter / test / function."""
        try:
            obj = utils.resolve(self.fn)
        except AttributeError:
            msg = f"Could not import jinja item {self.identifier!r} from {self.fn!r}"
            raise ImportError(msg) from AttributeError
        if not callable(obj):
            msg = "Filter needs correct, importable Path for callable"
            raise TypeError(msg)
        return obj

    @classmethod
    def for_function(
        cls,
        fn: Callable[..., Any],
        typ: Literal["filter", "test", "function"],
        group: str = "imported",
        **kwargs: Any,
    ) -> Self:
        """Alternative ctor to construct a JinjaItem based on a callable.

        Args:
            fn: Callable to get a JinjaItem for
            typ: The item type
            group: Group for metadata
            kwargs: Additional keyword arguments for JinjaItem ctor
        """
        return cls(
            fn.__name__,
            typ=typ,
            fn=f"{fn.__module__}.{fn.__name__}",
            group=group,
            **kwargs,
        )

    def apply(self, *args: Any, **kwargs: Any) -> Any:
        """Apply the filter function using given arguments and keywords.

        Args:
            args: The arguments for the call
            kwargs: They keyword arguments for the call
        """
        return self.filter_fn(*args, **kwargs)

    def resolve_example(self, example_name: str) -> str:
        """Render example with given name and return the result.

        Args:
            example_name: The example identifier
        """
        example = self.examples[example_name]
        loader = jinjarope.FileSystemLoader("")
        env = jinjarope.Environment(loader=loader)
        return env.render_string(example["template"])

filter_fn property

filter_fn: Callable[..., Any]

Return the callable to use as filter / test / function.

apply

apply(*args: Any, **kwargs: Any) -> Any

Apply the filter function using given arguments and keywords.

Parameters:

Name	Type	Description	Default
args	Any	The arguments for the call	()
kwargs	Any	They keyword arguments for the call	{}

Source code in src/jinjarope/jinjafile.py

def apply(self, *args: Any, **kwargs: Any) -> Any:
    """Apply the filter function using given arguments and keywords.

    Args:
        args: The arguments for the call
        kwargs: They keyword arguments for the call
    """
    return self.filter_fn(*args, **kwargs)

for_function classmethod

for_function(
    fn: Callable[..., Any],
    typ: Literal["filter", "test", "function"],
    group: str = "imported",
    **kwargs: Any
) -> Self

Alternative ctor to construct a JinjaItem based on a callable.

Parameters:

Name	Type	Description	Default
fn	Callable[..., Any]	Callable to get a JinjaItem for	required
typ	Literal['filter', 'test', 'function']	The item type	required
group	str	Group for metadata	'imported'
kwargs	Any	Additional keyword arguments for JinjaItem ctor	{}

Source code in src/jinjarope/jinjafile.py

@classmethod
def for_function(
    cls,
    fn: Callable[..., Any],
    typ: Literal["filter", "test", "function"],
    group: str = "imported",
    **kwargs: Any,
) -> Self:
    """Alternative ctor to construct a JinjaItem based on a callable.

    Args:
        fn: Callable to get a JinjaItem for
        typ: The item type
        group: Group for metadata
        kwargs: Additional keyword arguments for JinjaItem ctor
    """
    return cls(
        fn.__name__,
        typ=typ,
        fn=f"{fn.__module__}.{fn.__name__}",
        group=group,
        **kwargs,
    )

resolve_example

resolve_example(example_name: str) -> str

Render example with given name and return the result.

Parameters:

Name	Type	Description	Default
example_name	str	The example identifier	required

Source code in src/jinjarope/jinjafile.py

def resolve_example(self, example_name: str) -> str:
    """Render example with given name and return the result.

    Args:
        example_name: The example identifier
    """
    example = self.examples[example_name]
    loader = jinjarope.FileSystemLoader("")
    env = jinjarope.Environment(loader=loader)
    return env.render_string(example["template"])