diff --git a/docs/pkg/py/Brand.qmd b/docs/pkg/py/Brand.qmd index ace75984..8346ab44 100644 --- a/docs/pkg/py/Brand.qmd +++ b/docs/pkg/py/Brand.qmd @@ -65,7 +65,7 @@ path | Name | Description | | --- | --- | -| [from_yaml](#brand_yml.Brand.from_yaml) | Read a Brand YAML file. | +| [from_yaml](#brand_yml.Brand.from_yaml) | Create a Brand instance from a Brand YAML file. | | [from_yaml_str](#brand_yml.Brand.from_yaml_str) | Create a Brand instance from a string of YAML. | | [model_dump_yaml](#brand_yml.Brand.model_dump_yaml) | Serialize the Brand object to YAML. | @@ -75,19 +75,19 @@ path Brand.from_yaml(path) ``` -Read a Brand YAML file. +Create a Brand instance from a Brand YAML file. -Reads a Brand YAML file or finds and reads a `_brand.yml` file and returns -a validated :class:`Brand` instance. +Reads a Brand YAML file or finds and reads a `_brand.yml` file and +returns a validated :class:`Brand` instance. -To find a project-specific `_brand.yaml` file, pass `path` the project +To find a project-specific `_brand.yml` file, pass `path` the project directory or `__file__` (the path of the current Python script). [`brand_yml.Brand.from_yaml`](`brand_yml.Brand.from_yaml`) will look in that directory or any parent directory for a `_brand.yml`, -`brand/_brand.yml` or `_brand/_brand.yml` file. Note that it starts the -search in the directory passed in and moves upward to find the -`_brand.yml` file; it does not search into subdirectories of the current -directory. +`brand/_brand.yml` or `_brand/_brand.yml` file (or the same variants +with a `.yaml` extension). Note that it starts the search in the +directory passed in and moves upward to find the `_brand.yml` file; it +does not search into subdirectories of the current directory. #### Parameters {.doc-section .doc-section-parameters} @@ -95,8 +95,8 @@ directory. : The path to the brand.yml file or a directory where `_brand.yml` is expected to be found. Typically, you can pass `__file__` from the - calling script to find `_brand.yml` in the current directory or any of - its parent directories. + calling script to find `_brand.yml` or `_brand.yaml` in the current + directory or any of its parent directories. #### Returns {.doc-section .doc-section-returns} diff --git a/docs/pkg/py/utilities.qmd b/docs/pkg/py/utilities.qmd index a8bcc42a..1d5b92de 100644 --- a/docs/pkg/py/utilities.qmd +++ b/docs/pkg/py/utilities.qmd @@ -16,8 +16,11 @@ parent directory. In each directory, `find_project_brand_yml()` looks for any of the following files in the given order: * `_brand.yml` +* `_brand.yaml` * `brand/_brand.yml` +* `brand/_brand.yaml` * `_brand/_brand.yml` +* `_brand/_brand.yaml` ## Parameters {.doc-section .doc-section-parameters} diff --git a/pkg-py/src/brand_yml/__init__.py b/pkg-py/src/brand_yml/__init__.py index 12bc3842..9128d2fb 100644 --- a/pkg-py/src/brand_yml/__init__.py +++ b/pkg-py/src/brand_yml/__init__.py @@ -75,27 +75,27 @@ class Brand(BrandBase): @classmethod def from_yaml(cls, path: str | Path): """ - Read a Brand YAML file. + Create a Brand instance from a Brand YAML file. - Reads a Brand YAML file or finds and reads a `_brand.yml` file and returns - a validated :class:`Brand` instance. + Reads a Brand YAML file or finds and reads a `_brand.yml` file and + returns a validated :class:`Brand` instance. - To find a project-specific `_brand.yaml` file, pass `path` the project + To find a project-specific `_brand.yml` file, pass `path` the project directory or `__file__` (the path of the current Python script). [`brand_yml.Brand.from_yaml`](`brand_yml.Brand.from_yaml`) will look in that directory or any parent directory for a `_brand.yml`, - `brand/_brand.yml` or `_brand/_brand.yml` file. Note that it starts the - search in the directory passed in and moves upward to find the - `_brand.yml` file; it does not search into subdirectories of the current - directory. + `brand/_brand.yml` or `_brand/_brand.yml` file (or the same variants + with a `.yaml` extension). Note that it starts the search in the + directory passed in and moves upward to find the `_brand.yml` file; it + does not search into subdirectories of the current directory. Parameters ---------- path The path to the brand.yml file or a directory where `_brand.yml` is expected to be found. Typically, you can pass `__file__` from the - calling script to find `_brand.yml` in the current directory or any of - its parent directories. + calling script to find `_brand.yml` or `_brand.yaml` in the current + directory or any of its parent directories. Returns ------- diff --git a/pkg-py/src/brand_yml/_utils.py b/pkg-py/src/brand_yml/_utils.py index 017638c9..bb0ebdaa 100644 --- a/pkg-py/src/brand_yml/_utils.py +++ b/pkg-py/src/brand_yml/_utils.py @@ -9,7 +9,7 @@ def find_project_file( - filename: str, + filename: tuple[str, ...] | str, dir_: Path, subdir: tuple[str, ...] = (), ) -> Path: @@ -17,12 +17,17 @@ def find_project_file( i = 0 max_parents = 20 + if isinstance(filename, str): + filename = tuple([filename]) + while dir_ != dir_.parent and i < max_parents: - if (dir_ / filename).exists(): - return dir_ / filename + for fname in filename: + if (dir_ / fname).exists(): + return dir_ / fname for sub in subdir: - if (dir_ / sub / filename).exists(): - return dir_ / sub / filename + for fname in filename: + if (dir_ / sub / fname).exists(): + return dir_ / sub / fname dir_ = dir_.parent i += 1 @@ -41,8 +46,11 @@ def find_project_brand_yml(path: Path | str) -> Path: any of the following files in the given order: * `_brand.yml` + * `_brand.yaml` * `brand/_brand.yml` + * `brand/_brand.yaml` * `_brand/_brand.yml` + * `_brand/_brand.yaml` Parameters ---------- @@ -66,7 +74,11 @@ def find_project_brand_yml(path: Path | str) -> Path: if path.is_file(): path = path.parent - return find_project_file("_brand.yml", path, ("brand", "_brand")) + return find_project_file( + filename=("_brand.yml", "_brand.yaml"), + dir_=path, + subdir=("brand", "_brand"), + ) PredicateFuncType = Callable[[Any], bool]