appm 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

appm/manager.py

@@ -1,68 +1,25 @@
 from __future__ import annotations
 
-import re
 import shutil
-from collections.abc import Mapping
+from copy import deepcopy
 from pathlib import Path
-from typing import Any, Sequence, overload
+from typing import Any
 
-from ruamel.yaml import YAML, CommentedMap, CommentedSeq
+from ruamel.yaml import YAML
 
 from appm.__version__ import __version__
+from appm.default import DEFAULT_TEMPLATE
 from appm.exceptions import (
-    FileFormatMismatch,
-    MetadataFileNotFoundErr,
-    ProjectNotFoundErr,
     UnsupportedFileExtension,
 )
-from appm.model import ExtDecl, ProjectMetadata
+from appm.model import Project
+from appm.utils import to_flow_style, validate_path
 
 yaml = YAML()
 yaml.indent(mapping=2, sequence=4, offset=2)
 yaml.preserve_quotes = True  # optional, if you want to preserve quotes
 
 
-def to_flow_style(obj: Any) -> Any:
-    """Recursively convert dict/list to ruamel structures with ALL lists using flow-style."""
-    if isinstance(obj, Mapping):
-        cm = CommentedMap()
-        for k, v in obj.items():
-            cm[k] = to_flow_style(v)
-        return cm
-    if isinstance(obj, Sequence) and not isinstance(obj, str):
-        cs = CommentedSeq()
-        for item in obj:
-            cs.append(to_flow_style(item))
-        cs.fa.set_flow_style()
-        return cs
-    return obj
-
-
-class ExtManager:
-    def __init__(self, ext: str, decl: ExtDecl) -> None:
-        self.ext = ext
-        self.decl = decl
-
-    @property
-    def pattern(self) -> str:
-        return (
-            r"^"
-            + self.decl.sep.join([f"({p})" for _, p in self.decl.format])
-            + r"(.*)$"
-        )
-
-    def match(self, name: str) -> dict[str, str]:
-        match = re.match(self.pattern, name)
-        if not match:
-            raise FileFormatMismatch(f"Name: {name}. Pattern: {self.pattern}")
-        groups = match.groups()
-        result = {}
-        for i, (field, _) in enumerate(self.decl.format):
-            result[field] = groups[i]
-        result["*"] = groups[-1]
-        return result
-
-
 class ProjectManager:
     METADATA_NAME: str = "metadata.yaml"
 
@@ -72,30 +29,68 @@ class ProjectManager:
         root: str | Path,
     ) -> None:
         self.root = Path(root)
-        self.metadata = ProjectMetadata.model_validate(metadata)
-        self.handlers = {
-            ext: ExtManager(ext, ext_decl)
-            for ext, ext_decl in self.metadata.file.items()
-        }
+        self.metadata = Project.model_validate(metadata)
+        self.handlers = {ext: handler for ext, handler in self.metadata.file.items()}
+
+    @property
+    def location(self) -> Path:
+        return self.root / self.metadata.project_name
 
-    def match(self, name: str) -> dict[str, str]:
+    def match(self, name: str) -> dict[str, str | None]:
+        """Match a file name and separate into format defined field components
+
+        The result contains a * which captures all non-captured values.
+
+        Args:
+            name (str): file name
+
+        Raises:
+            UnsupportedFileExtension: the metadata does not define an
+            extension declaration for the file's extension.
+
+        Returns:
+            dict[str, str]: key value dictionary of the field component
+            defined using the format field.
+        """
         ext = name.split(".")[-1]
-        if ext not in self.handlers:
-            raise UnsupportedFileExtension(ext)
-        return self.handlers[ext].match(name)
+        if ext in self.handlers:
+            return self.handlers[ext].match(name)
+        if "*" in self.handlers:
+            return self.handlers["*"].match(name)
+        raise UnsupportedFileExtension(str(ext))
 
     def get_file_placement(self, name: str) -> str:
-        layout = self.metadata.layout
+        """Find location where a file should be placed.
+
+        Determination is based on the metadata's layout field,
+        the file extension format definition, and the file name.
+        More concretely, field component - values are matched using the
+        RegEx defined in format. Fields that match layout values will be
+        extracted and path-appended in the order they appear in layout.
+
+        Args:
+            name (str): file name
+
+        Returns:
+            str: file placement directory
+        """
+        layout = self.metadata.parsed_layout
         groups = self.match(name)
-        values = [groups[component] for component in layout]
-        return "/".join(values)
+        return layout.get_path(groups)
 
     def init_project(self) -> None:
-        self.root.mkdir(exist_ok=True, parents=True)
+        """Create a project:
+
+        - Determine the project's name from nameing_convention and metadata
+        - Create a folder based on project's root and project name
+        - Create a metadata file in the project's location
+        """
+        self.location.mkdir(exist_ok=True, parents=True)
         self.save_metadata()
 
     def save_metadata(self) -> None:
-        metadata_path = self.root / self.METADATA_NAME
+        """Save the current metadata to the project location"""
+        metadata_path = self.location / self.METADATA_NAME
         with metadata_path.open("w") as file:
             data = self.metadata.model_dump(mode="json")
             data["version"] = __version__
@@ -104,84 +99,86 @@ class ProjectManager:
                 file,
             )
 
-    def copy_file(self, src_path: Path) -> None:
-        if src_path.exists():
-            raise FileNotFoundError(str(src_path))
-        location = self.get_file_placement(src_path.name)
-        dst_path = self.root / location
+    def copy_file(self, src_path: str | Path) -> None:
+        """Copy a file located at `src_path` to an appropriate
+        location in the project.
+
+        Args:
+            src_path (str | Path): path to where src data is found
+        """
+        src_path = validate_path(src_path)
+        dst_path = self.location / self.get_file_placement(src_path.name)
         dst_path.mkdir(parents=True, exist_ok=True)
         shutil.copy2(src_path, dst_path)
 
-    @overload
     @classmethod
-    def from_metadata(
+    def from_template(
         cls,
         root: str | Path,
-        metadata: str | Path,
         year: int,
         summary: str,
         internal: bool = True,
-        researcher: str | None = None,
-        organisation: str | None = None,
-    ) -> ProjectManager: ...
-
-    @overload
-    @classmethod
-    def from_metadata(
-        cls,
-        root: str | Path,
-        metadata: dict[str, Any],
-        year: int,
-        summary: str,
-        internal: bool = True,
-        researcher: str | None = None,
-        organisation: str | None = None,
-    ) -> ProjectManager: ...
-
-    @classmethod
-    def from_metadata(
-        cls,
-        root: str | Path,
-        metadata: str | Path | dict[str, Any],
-        year: int,
-        summary: str,
-        internal: bool = True,
-        researcher: str | None = None,
-        organisation: str | None = None,
+        template: str | Path | dict[str, Any] | None = None,
+        researcherName: str | None = None,
+        organisationName: str | None = None,
     ) -> ProjectManager:
-        if isinstance(metadata, str | Path):
-            metadata = Path(metadata)
-            if not metadata.exists():
-                raise MetadataFileNotFoundErr(str(metadata))
-            with metadata.open("r") as file:
-                _metadata = yaml.load(file)
+        """Create a ProjectManager based on template and meta information
+
+        Args:
+            root (str | Path): parent directory - where project is stored
+            template (str | Path | dict[str, Any]): path to template file or the template content.
+            year (int): meta information - year
+            summary (str): meta information - summary
+            internal (bool, optional): meta information - internal. Defaults to True.
+            researcher (str | None, optional): meta information - researcherName. Defaults to None.
+            organisation (str | None, optional): meta information - organisationName. Defaults to None.
+
+        Returns:
+            ProjectManager: ProjectManager object
+        """
+        if isinstance(template, str | Path):
+            metadata_path = Path(template)
+            metadata_path = validate_path(template)
+            with metadata_path.open("r") as file:
+                metadata = yaml.load(file)
+        elif isinstance(template, dict):
+            metadata = template
+        elif not template:
+            metadata = deepcopy(DEFAULT_TEMPLATE)
         else:
-            _metadata = metadata
-        _metadata.update(
-            {
-                "year": year,
-                "summary": summary,
-                "internal": internal,
-                "researcher": researcher,
-                "organisation": organisation,
-            }
-        )
-        return cls(root=root, metadata=_metadata)
+            raise TypeError(
+                f"Unexpected type for template: {type(template)}. Accepts str, dict or None"
+            )
+        metadata["meta"] = {
+            "year": year,
+            "summary": summary,
+            "internal": internal,
+            "researcherName": researcherName,
+            "organisationName": organisationName,
+        }
+        return cls(root=root, metadata=metadata)
 
     @classmethod
     def load_project(
         cls, project_path: Path | str, metadata_name: str | None = None
     ) -> ProjectManager:
-        project_path = Path(project_path)
-        if not project_path.exists():
-            raise ProjectNotFoundErr(str(project_path))
+        """Load a project from project's path
+
+        Args:
+            project_path (Path | str): path to project to open
+            metadata_name (str | None, optional): name for metadata file. If not provided, use "metadata.yaml". Defaults to None.
+
+        Returns:
+            ProjectManager: ProjectManager object
+        """
+        project_path = validate_path(project_path)
         metadata_path = (
             project_path / cls.METADATA_NAME
             if not metadata_name
             else project_path / metadata_name
         )
-        if not metadata_path.exists():
-            raise MetadataFileNotFoundErr(str(metadata_path))
+        metadata_path = validate_path(metadata_path)
+
         with metadata_path.open("r") as file:
             metadata = yaml.load(file)
-        return cls(metadata=metadata, root=project_path)
+        return cls(metadata=metadata, root=project_path.parent)

appm/model.py

@@ -1,28 +1,231 @@
+from __future__ import annotations
+
+import re
+from collections import Counter
 from typing import Self
 
 from pydantic import BaseModel, model_validator
+from ruamel.yaml import YAML
 
 from appm.__version__ import __version__
+from appm.exceptions import FileFormatMismatch
 from appm.utils import slugify
 
-STRUCTURES = {"year", "summary", "internal", "researcher", "organisation"}
+yaml = YAML()
 
+STRUCTURES = {"year", "summary", "internal", "researcherName", "organisationName"}
 
-class ExtDecl(BaseModel):
-    sep: str = "_"
-    format: list[tuple[str, str]]
+
+class Field(BaseModel):
+    name: str
+    pattern: str
+    required: bool = True
+
+    @property
+    def regex(self) -> str:
+        return f"(?P<{self.name}>{self.pattern})"
+
+    @classmethod
+    def from_tuple(cls, value: tuple[str, str] | list[str]) -> Field:
+        assert len(value) == 2
+        return Field(name=value[0], pattern=value[1])
+
+
+class Group(BaseModel):
+    components: list[tuple[str, str] | Field | Group]
+    sep: str = "-"
+
+    def validate_components(self) -> Self:
+        if not self.components:
+            raise ValueError(f"Components cannot be empty: {self.components}")
+        self._fields: list[Field | Group] = []
+        self._normalised_fields: list[Field] = []
+        for field in self.components:
+            if isinstance(field, tuple | list):
+                f = Field.from_tuple(field)
+                self._fields.append(f)
+                self._normalised_fields.append(f)
+            elif isinstance(field, Field):
+                self._fields.append(field)
+                self._normalised_fields.append(field)
+            else:
+                self._fields.append(field)
+                self._normalised_fields.extend(field.normalised_fields)
+        return self
+
+    def validate_names(self) -> Self:
+        self._names: list[str] = []
+        self._optional_names: set[str] = set()
+        for field in self.fields:
+            if isinstance(field, Field):
+                self._names.append(field.name)
+                if not field.required:
+                    self._optional_names.add(field.name)
+            else:
+                self._names.extend(field.names)
+                self._optional_names.update(field.optional_names)
+        return self
+
+    def validate_regex(self) -> Self:
+        regex_str = []
+        for i, field in enumerate(self.fields):
+            is_optional = isinstance(field, Field) and not field.required
+            pattern = field.regex
+
+            if i == 0:
+                if is_optional:
+                    # First field, no separator; make only field optional
+                    regex_str.append(f"(?:{pattern})?")
+                else:
+                    regex_str.append(pattern)
+            else:
+                if is_optional:
+                    # Wrap separator + field together as optional
+                    regex_str.append(f"(?:{self.sep}{pattern})?")
+                else:
+                    regex_str.append(f"{self.sep}{pattern}")
+        self._regex = "".join(regex_str)
+        return self
+
+    @model_validator(mode="after")
+    def validate_group(self) -> Self:
+        return self.validate_components().validate_names().validate_regex()
+
+    @property
+    def normalised_fields(self) -> list[Field]:
+        return self._normalised_fields
+
+    @property
+    def fields(self) -> list[Field | Group]:
+        return self._fields
+
+    @property
+    def names(self) -> list[str]:
+        return self._names
+
+    @property
+    def optional_names(self) -> set[str]:
+        return self._optional_names
+
+    @property
+    def regex(self) -> str:
+        return self._regex
+
+
+class Extension(Group):
+    default: dict[str, str] | None = None
 
     @property
-    def fields(self) -> set[str]:
-        return {item[0] for item in self.format}
+    def default_names(self) -> set[str]:
+        return set() if not self.default else set(self.default.keys())
 
+    @property
+    def all_names(self) -> set[str]:
+        return set(self.names) | self.default_names
+
+    def validate_regex(self) -> Self:
+        self = super().validate_regex()
+        self._regex = f"^{self._regex}(?P<rest>.*)$"
+        return self
+
+    def validate_unique_names(self) -> Self:
+        count = Counter(self.names)
+        non_uniques = {k: v for k, v in count.items() if v > 1}
+        if non_uniques:
+            raise ValueError(f"Non-unique field name: {non_uniques}")
+        return self
+
+    def validate_reserved_name(self) -> Self:
+        if "rest" in self.names:
+            raise ValueError("Field component must not contain reserved key: rest")
+        return self
 
-class NamingConventionDecl(BaseModel):
+    def validate_first_field_must_be_required(self) -> Self:
+        if not (field := self.normalised_fields[0]).required:
+            raise ValueError(f"First component must be required: {field.name}")
+        return self
+
+    @model_validator(mode="after")
+    def validate_extension(self) -> Self:
+        return (
+            self.validate_components()
+            .validate_names()
+            .validate_regex()
+            .validate_unique_names()
+            .validate_reserved_name()
+            .validate_first_field_must_be_required()
+        )
+
+    def match(self, name: str) -> dict[str, str | None]:
+        m = re.match(self.regex, name)
+        if not m:
+            raise FileFormatMismatch(f"Name: {name}. Pattern: {self.regex}")
+        result = m.groupdict()
+        if self.default:
+            for k, v in self.default.items():
+                if result.get(k) is None:
+                    result[k] = v
+        return result
+
+
+type File = dict[str, Extension]
+
+
+class Layout(BaseModel):
+    structure: list[str]
+    mapping: dict[str, dict[str, str]] | None = None
+
+    @classmethod
+    def from_list(cls, value: list[str]) -> Layout:
+        return cls(structure=value)
+
+    @property
+    def structure_set(self) -> set[str]:
+        return self._structure_set
+
+    @model_validator(mode="after")
+    def validate_layout(self) -> Self:
+        self._structure_set = set(self.structure)
+        if self.mapping:
+            if not set(self.mapping.keys()).issubset(self._structure_set):
+                raise ValueError(
+                    f"Mapping keys must be a subset of structure. Mapping keys: {set(self.mapping.keys())}, structure: {self.structure}"
+                )
+        return self
+
+    def get_path(self, components: dict[str, str | None]) -> str:
+        result: list[str] = []
+        for key in self.structure:
+            value = components.get(key, None)
+            if self.mapping and key in self.mapping and value in self.mapping[key]:
+                value = self.mapping[key][value]
+            if value is None:
+                raise ValueError(
+                    f"None value for key: {key}. Either set a default for Extension definition, change Extension pattern to capture key value, or rename file."
+                )
+            result.append(value)
+        return "/".join(result)
+
+
+class NamingConv(BaseModel):
     sep: str = "_"
-    structure: list[str] = ["year", "summary", "internal", "researcher", "organisation"]
+    structure: list[str] = [
+        "year",
+        "summary",
+        "internal",
+        "researcherName",
+        "organisationName",
+    ]
 
     @model_validator(mode="after")
-    def validate_structure_values(self) -> Self:
+    def validate_naming_convention(self) -> Self:
+        """Validate structure value
+
+        structure:
+            - cannot be empty
+            - cannot have repeated component(s)
+            - cannot have a field component that is not one of the metadata fields.
+        """
         counter: dict[str, int] = {}
         if len(self.structure) == 0:
             raise ValueError("Invalid naming structure - empty structure")
@@ -37,40 +240,68 @@ class NamingConventionDecl(BaseModel):
         return self
 
 
-class ProjectDecl(BaseModel):
-    layout: list[str]
-    file: dict[str, ExtDecl]
-    naming_convention: NamingConventionDecl = NamingConventionDecl()
+class Template(BaseModel):
+    layout: Layout | list[str]
+    file: File
+    naming_convention: NamingConv = NamingConv()
+    version: str = __version__
 
-    @property
-    def layout_set(self) -> set[str]:
-        return set(self.layout)
+    def validate_layout(self) -> Self:
+        if isinstance(self.layout, list):
+            self._layout = Layout.from_list(self.layout)
+        else:
+            self._layout = self.layout
+        return self
 
-    @model_validator(mode="after")
-    def validate_format_and_layout(self) -> Self:
+    def validate_file_non_empty(self) -> Self:
+        if not self.file:
+            raise ValueError("Empty extension")
+        return self
+
+    def validate_file_name_subset_layout(self) -> Self:
         for ext, decl in self.file.items():
-            if not self.layout_set.issubset(decl.fields):
-                raise ValueError(
-                    f"""Format fields must be a superset of layout fields. 
-                    Extension: {ext}. Format fields: {decl.fields}. Layout fields: {self.layout_set}"""
-                )
+            for field in self.parsed_layout.structure_set:
+                if field not in decl.all_names:
+                    raise ValueError(
+                        f"Component fields must be a superset of layout fields: {field}. Ext: {ext}"
+                    )
+                if field in decl.optional_names and field not in decl.default_names:
+                    raise ValueError(
+                        f"Optional field that is also a layout field must have a default value: {field}. Ext: {ext}"
+                    )
         return self
 
+    @property
+    def parsed_layout(self) -> Layout:
+        return self._layout
+
+    @model_validator(mode="after")
+    def validate_template(self) -> Self:
+        return (
+            self.validate_layout()
+            .validate_file_non_empty()
+            .validate_file_name_subset_layout()
+        )
+
 
-class ProjectMetadata(ProjectDecl):
+class Metadata(BaseModel):
     year: int
     summary: str
-    internal: bool
-    researcher: str | None = None
-    organisation: str | None = None
-    version: str | None = __version__
+    internal: bool = True
+    researcherName: str | None = None
+    organisationName: str | None = None
+
+
+class Project(Template):
+    meta: Metadata
 
     @property
-    def name(self) -> str:
+    def project_name(self) -> str:
+        """Project name based on metadata and naming convention definiton"""
         fields = self.naming_convention.structure
         name: list[str] = []
         for field in fields:
-            value = getattr(self, field)
+            value = getattr(self.meta, field)
             if value is not None:
                 if isinstance(value, str):
                     name.append(slugify(value))

appm/utils.py

@@ -1,4 +1,11 @@
 import re
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from ruamel.yaml import CommentedMap, CommentedSeq
+
+from appm.exceptions import NotAFileErr, NotFoundErr
 
 
 def slugify(text: str) -> str:
@@ -25,3 +32,41 @@ def slugify(text: str) -> str:
     # Replace spaces with hyphens
     text = re.sub(r"[\s\-]+", "-", text)
     return text.strip("-")
+
+
+def to_flow_style(obj: Any) -> Any:
+    """Recursively convert dict/list to ruamel structures with ALL lists using flow-style."""
+    if isinstance(obj, Mapping):
+        cm = CommentedMap()
+        for k, v in obj.items():
+            cm[k] = to_flow_style(v)
+        return cm
+    if isinstance(obj, Sequence) and not isinstance(obj, str):
+        cs = CommentedSeq()
+        for item in obj:
+            cs.append(to_flow_style(item))
+        cs.fa.set_flow_style()
+        return cs
+    return obj
+
+
+def validate_path(path: str | Path, is_file: bool = False) -> Path:
+    """Verify that path describes an existing file/folder
+
+    Args:
+        path (str | Path): path to validate
+        is_file (bool): whether path is a file. Defaults to False.
+
+    Raises:
+        NotFoundErr: path item doesnt exist
+        NotAFileErr: path doesn't describe a file
+
+    Returns:
+        Path: validated path
+    """
+    _path = Path(path)
+    if not _path.exists():
+        raise NotFoundErr(str(path))
+    if is_file and not _path.is_file():
+        raise NotAFileErr(str(path))
+    return _path