hexdoc.core.properties

  1from __future__ import annotations
  2
  3import logging
  4from collections import defaultdict
  5from functools import cached_property
  6from pathlib import Path
  7from typing import Annotated, Any, Literal, Self, Sequence
  8
  9from pydantic import Field, PrivateAttr, field_validator, model_validator
 10from pydantic.json_schema import (
 11    DEFAULT_REF_TEMPLATE,
 12    GenerateJsonSchema,
 13    SkipJsonSchema,
 14)
 15from typing_extensions import override
 16from yarl import URL
 17
 18from hexdoc.model.base import HexdocSettings
 19from hexdoc.model.strip_hidden import StripHiddenModel
 20from hexdoc.utils import (
 21    TRACE,
 22    PydanticOrderedSet,
 23    RelativePath,
 24    ValidationContext,
 25    git_root,
 26    load_toml_with_placeholders,
 27    relative_path_root,
 28)
 29from hexdoc.utils.deserialize.toml import GenerateJsonSchemaTOML
 30from hexdoc.utils.types import PydanticURL
 31
 32from .resource import ResourceLocation
 33from .resource_dir import ResourceDir
 34
 35logger = logging.getLogger(__name__)
 36
 37JINJA_NAMESPACE_ALIASES = {
 38    "patchouli": "hexdoc",
 39}
 40
 41
 42class EnvironmentVariableProps(HexdocSettings):
 43    # default Actions environment variables
 44    github_repository: str
 45    github_sha: str
 46
 47    # set by CI
 48    github_pages_url: PydanticURL
 49
 50    # for putting books somewhere other than the site root
 51    hexdoc_subdirectory: str | None = None
 52
 53    # optional for debugging
 54    debug_githubusercontent: PydanticURL | None = None
 55
 56    @property
 57    def asset_url(self) -> URL:
 58        if self.debug_githubusercontent is not None:
 59            return URL(str(self.debug_githubusercontent))
 60
 61        return (
 62            URL("https://raw.githubusercontent.com")
 63            / self.github_repository
 64            / self.github_sha
 65        )
 66
 67    @property
 68    def source_url(self) -> URL:
 69        return (
 70            URL("https://github.com")
 71            / self.github_repository
 72            / "tree"
 73            / self.github_sha
 74        )
 75
 76    @property
 77    def repo_owner(self):
 78        return self._github_repository_parts[0]
 79
 80    @property
 81    def repo_name(self):
 82        return self._github_repository_parts[1]
 83
 84    @property
 85    def _github_repository_parts(self):
 86        owner, repo_name = self.github_repository.split("/", maxsplit=1)
 87        return owner, repo_name
 88
 89    @model_validator(mode="after")
 90    def _append_subdirectory(self) -> Self:
 91        if self.hexdoc_subdirectory:
 92            self.github_pages_url /= self.hexdoc_subdirectory
 93        return self
 94
 95
 96class TemplateProps(StripHiddenModel, validate_assignment=True):
 97    static_dir: RelativePath | None = None
 98    icon: RelativePath | None = None
 99    include: PydanticOrderedSet[str]
100
101    render_from: PydanticOrderedSet[str] = Field(None, validate_default=False)  # type: ignore
102    """List of modids to include default rendered templates from.
103
104    If not provided, defaults to `self.include`.
105    """
106    render: dict[Path, str] = Field(default_factory=dict)
107    extend_render: dict[Path, str] = Field(default_factory=dict)
108
109    redirect: tuple[Path, str] | None = (Path("index.html"), "redirect.html.jinja")
110    """filename, template"""
111
112    args: dict[str, Any]
113
114    _was_render_set: bool = PrivateAttr(False)
115
116    @property
117    def override_default_render(self):
118        return self._was_render_set
119
120    @field_validator("include", "render_from", mode="after")
121    @classmethod
122    def _resolve_aliases(cls, values: PydanticOrderedSet[str] | None):
123        if values:
124            for alias, replacement in JINJA_NAMESPACE_ALIASES.items():
125                if alias in values:
126                    values.remove(alias)
127                    values.add(replacement)
128        return values
129
130    @model_validator(mode="after")
131    def _set_default_render_from(self):
132        if self.render_from is None:  # pyright: ignore[reportUnnecessaryComparison]
133            self.render_from = self.include
134        return self
135
136
137# TODO: support item/block override
138class PNGTextureOverride(StripHiddenModel):
139    url: PydanticURL
140    pixelated: bool
141
142
143class TextureTextureOverride(StripHiddenModel):
144    texture: ResourceLocation
145    """The id of an image texture (eg. `minecraft:textures/item/stick.png`)."""
146
147
148class TexturesProps(StripHiddenModel):
149    enabled: bool = True
150    """Set to False to disable texture rendering."""
151    strict: bool = True
152    """Set to False to print some errors instead of throwing them."""
153    missing: set[ResourceLocation] | Literal["*"] = Field(default_factory=set)
154    override: dict[
155        ResourceLocation,
156        PNGTextureOverride | TextureTextureOverride,
157    ] = Field(default_factory=dict)
158
159
160class LangProps(StripHiddenModel):
161    """Configuration for a specific book language."""
162
163    quiet: bool = False
164    """If `True`, do not log warnings for missing translations.
165
166    Using this option for the default language is not recommended.
167    """
168    ignore_errors: bool = False
169    """If `True`, log fatal errors for this language instead of failing entirely.
170
171    Using this option for the default language is not recommended.
172    """
173
174
175class BaseProperties(StripHiddenModel, ValidationContext):
176    env: SkipJsonSchema[EnvironmentVariableProps]
177    props_dir: SkipJsonSchema[Path]
178
179    @classmethod
180    def load(cls, path: Path) -> Self:
181        return cls.load_data(
182            props_dir=path.parent,
183            data=load_toml_with_placeholders(path),
184        )
185
186    @classmethod
187    def load_data(cls, props_dir: Path, data: dict[str, Any]) -> Self:
188        props_dir = props_dir.resolve()
189
190        with relative_path_root(props_dir):
191            env = EnvironmentVariableProps.model_getenv()
192            props = cls.model_validate(
193                data
194                | {
195                    "env": env,
196                    "props_dir": props_dir,
197                },
198            )
199
200        logger.log(TRACE, props)
201        return props
202
203    @override
204    @classmethod
205    def model_json_schema(
206        cls,
207        by_alias: bool = True,
208        ref_template: str = DEFAULT_REF_TEMPLATE,
209        schema_generator: type[GenerateJsonSchema] = GenerateJsonSchemaTOML,
210        mode: Literal["validation", "serialization"] = "validation",
211    ) -> dict[str, Any]:
212        return super().model_json_schema(by_alias, ref_template, schema_generator, mode)
213
214
215class Properties(BaseProperties):
216    """Pydantic model for `hexdoc.toml` / `properties.toml`."""
217
218    modid: str
219
220    book_type: str = "patchouli"
221    """Modid of the `hexdoc.plugin.BookPlugin` to use when loading this book."""
222
223    # TODO: make another properties type without book_id
224    book_id: ResourceLocation | None = Field(alias="book", default=None)
225    extra_books: list[ResourceLocation] = Field(default_factory=list)
226
227    default_lang: str = "en_us"
228    default_branch: str = "main"
229
230    is_0_black: bool = False
231    """If true, the style `$(0)` changes the text color to black; otherwise it resets
232    the text color to the default."""
233
234    resource_dirs: Sequence[ResourceDir]
235    export_dir: RelativePath | None = None
236
237    entry_id_blacklist: set[ResourceLocation] = Field(default_factory=set)
238
239    macros: dict[str, str] = Field(default_factory=dict)
240    link_overrides: dict[str, str] = Field(default_factory=dict)
241
242    textures: TexturesProps = Field(default_factory=TexturesProps)
243
244    template: TemplateProps | None = None
245
246    lang: defaultdict[
247        str,
248        Annotated[LangProps, Field(default_factory=LangProps)],
249    ] = Field(default_factory=lambda: defaultdict(LangProps))
250    """Per-language configuration. The key should be the language code, eg. `en_us`."""
251
252    extra: dict[str, Any] = Field(default_factory=dict)
253
254    def mod_loc(self, path: str) -> ResourceLocation:
255        """Returns a ResourceLocation with self.modid as the namespace."""
256        return ResourceLocation(self.modid, path)
257
258    @property
259    def prerender_dir(self):
260        return self.cache_dir / "prerender"
261
262    @property
263    def cache_dir(self):
264        return self.repo_root / ".hexdoc"
265
266    @cached_property
267    def repo_root(self):
268        return git_root(self.props_dir)