flinventory 0.3.0__py3-none-any.whl

flinventory/__init__.py

@@ -0,0 +1,8 @@
+from .box import BoxedThing
+from .location import Location, Schema
+from .inventory_io import Inventory
+from .sign import Sign
+from .defaulted_data import DefaultedDict
+from .constant import Options
+from .thing import Thing
+from .signprinter_latex import SignPrinterLaTeX

flinventory/__main__.py

@@ -0,0 +1,45 @@
+"""Entrypoint to the package if called for running without import.
+
+Command-line interface with the different housekeeping tasks.
+"""
+
+import argparse
+
+from . import generate_labels, inventory_io
+from . import datacleanup
+
+
+def parse_args():
+    """Parse the command-line arguments.
+
+    Supply information from command-line arguments.
+
+    Add various subparsers that have each a func
+    default that tells the main program which
+    function should be called if this subcommand
+    is issued.
+
+    Returns:
+        Options as a dict-like object.
+
+    """
+    parser = argparse.ArgumentParser(
+        description="""Collection of various data cleaning tasks and label making.""",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    subparsers = parser.add_subparsers()
+    inventory_io.add_file_args(parser)
+    datacleanup.add_arg_parsers(subparsers)
+    generate_labels.add_arg_parsers(subparsers)
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    arguments = parse_args()
+    datacleanup.logging_config(arguments)
+    try:
+        function = arguments.func
+    except AttributeError:
+        print("No command given. See -h for help information.")
+    else:
+        function(arguments)

flinventory/box.py

@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+"""Class representing a thing in an inventory for a specific workshop with location and sign."""
+import itertools
+import os.path
+
+import collections.abc
+from typing import Any, Optional, Self, Union, cast
+
+from . import constant
+from . import defaulted_data
+
+from .location import Location, Schema
+from .sign import Sign
+from .thing import Thing
+
+
+class BoxedThing:
+    """Represents one thing in the workshop inventory.
+
+    That is: a thing, a location, a sign, an image.
+
+    Dictionary-like functions are forwarded to the underlying thing.
+
+    Location and sign are special members, given by the respective files.
+
+    Properties:
+        location: Location   Where this thing is stored.
+        sign: Sign           Parameters for the sign for this thing.
+        options: Options     Global options.
+        directory: str      Where information about this thing is stored.
+                             Accessible only via property directory.
+    """
+
+    def __init__(
+        self,
+        options: constant.Options,
+        schema: Schema,
+        directory: str,
+        thing: Optional[Thing] = None,
+        location: Optional[Location] = None,
+        sign: Optional[Sign] = None,
+    ):
+        """Create a thing from the given data.
+
+        If created empty, adding a name afterward is heavily encouraged.
+        If thing and sign are given, sign.default must be thing.
+        The directory for thing, sign and location must be the same.
+        Args:
+            directory: directory where the thing data should be saved (later).
+            options: global options
+            schema: location schema for the location
+            thing: the thing to be stored. If None, replaced with empty thing.
+            location: where the thing is stored. If none, empty location is created.
+            sign: how the sign for this thing looks like. If none, empty sign information is used.
+        """
+        self._thing = (
+            Thing(data={}, default={}, options=options, directory=directory)
+            if thing is None
+            else thing
+        )
+        self._location = (
+            Location(schema=schema, data={}, directory=directory, options=options)
+            if location is None
+            else location
+        )
+        self._sign = (
+            Sign(
+                data={},
+                thing=self._thing,
+                options=options,
+                directory=directory,
+            )
+            if sign is None
+            else sign
+        )
+        self._directory = directory
+        self.options = options
+        assert (error := self.consistent()) == "", error
+
+    @property
+    def thing(self):
+        """The underlying thing."""
+        return self._thing
+
+    @property
+    def location(self):
+        """The location of the box."""
+        return self._location
+
+    @property
+    def sign(self):
+        """The sign information for this box."""
+        return self._sign
+
+    def consistent(self):
+        """Checks if the data in all sub elements (thing, sign, location) are consistent.
+
+        - .directory is the same
+        - thing is default of sign
+        - todo: options are the same for all
+
+        Usable in assert statement:
+        assert (error := self.consistent) == "", error
+
+        Returns:
+            "" if fine, error message str if not consistent
+        """
+        if self._sign.default != self._thing:
+            return (
+                "When creating a boxed thing, the default for sign data must the thing."
+            )
+        if self._sign.directory != self.directory:
+            return (
+                f"When creating a boxed thing, the directory for the sign must "
+                f"be same as for the box, not {self._sign.directory=} != {self.directory=}."
+            )
+        if self._location.directory != self.directory:
+            return (
+                f"When creating a boxed thing, the directory for the sign must "
+                f"be same as for the box, not {self._location.directory=} != {self.directory=}."
+            )
+        if self._thing.directory != self.directory:
+            return (
+                f"When creating a boxed thing, the directory for the thing must "
+                f"be same as for the box, not {self._thing.directory=} != {self.directory=}."
+            )
+        return ""
+
+    @classmethod
+    def from_files(
+        cls, directory: str, options: constant.Options, schema: Schema
+    ) -> Self:
+        """Create a new boxed thing based on yaml files in directory.
+
+        Arguments:
+            directory: directory which includes a THING_FILE file and maybe
+                a SIGN_FILE and LOCATION_FILE (a missing THING_FILE raises no error
+                but is a bit useless)
+            options: global options
+            schema: location schema to interpret location data
+        """
+        thing = Thing.from_yaml_file(directory=directory, default={}, options=options)
+        location = Location.from_yaml_file(
+            directory=directory, schema=schema, options=options
+        )
+        sign = Sign.from_yaml_file(directory=directory, thing=thing, options=options)
+        return cls(
+            options=options,
+            schema=schema,
+            directory=directory,
+            thing=thing,
+            location=location,
+            sign=sign,
+        )
+
+    def __getitem__(
+        self, key: Union[defaulted_data.Key, tuple[str, int]]
+    ) -> defaulted_data.Value:
+        """Uses self.thing[item] on internal thing."""
+        return self._thing[key]
+
+    def get(self, key: Union[defaulted_data.Key, tuple[str, int]], default: Any) -> Any:
+        """Call self.thing.get(key, default)."""
+        return self._thing.get(key, default)
+
+    def __setitem__(
+        self,
+        key: Union[defaulted_data.Key, tuple[str, int]],
+        value: Union[defaulted_data.Value, dict[str, defaulted_data.Value]],
+    ):
+        """Calls self.thing[key] = value"""
+        self._thing[key] = value
+
+    def __delitem__(self, key: defaulted_data.Key):
+        """Calls del self.thing[key]."""
+        del self._thing[key]
+
+    def __contains__(self, key: defaulted_data.Key):
+        """Calls key in self.thing."""
+        key in self.thing
+
+    def best(self, translated_key: str, **backup: Any):
+        """Calls best on self.thing."""
+        return self._thing.best(translated_key, **backup)
+
+    @property
+    def where(self):
+        """Where the thing is as a printable string."""
+        return "" if self.location is None else str(self.location)
+
+    @property
+    def directory(self) -> str:
+        """Directory where information about this thing is saved."""
+        return self._directory
+
+    @directory.setter
+    def directory(self, new_directory: str):
+        """Change directory where information about this thing is saved.
+
+        Move the existing data but does not save the current in-memory data.
+        Use save() for that.
+
+        Deletes original directory if it is empty.
+
+        Args:
+            new_directory: where the thing data should be saved from now on.
+        Raises:
+            FileExistsException:
+                - if new_directory is a regular file
+                - if there are files with the special names for data in the new directory
+            (if there is no location saved in this thing and a LOCATION_FILE already exists
+            the error is also raised even if currently no data would be overwritten)
+
+        """
+        if self._directory == new_directory:
+            # nothing to be done
+            return
+        if os.path.isfile(new_directory):
+            raise FileExistsError(
+                f"{new_directory} is a regular file. "
+                f"Cannot save thing data since it is not a directory."
+            )
+        if os.path.exists(new_directory):
+            # must be directory
+            for reserved in constant.RESERVED_FILENAMES:
+                if os.path.exists(os.path.join(new_directory, reserved)):
+                    raise FileExistsError(
+                        f"{os.path.join(new_directory, reserved)} exists. Do not overwrite it."
+                    )
+        else:
+            os.makedirs(new_directory)
+        # setting new directory deletes old and creates new file
+        self._thing.directory = new_directory
+        self._location.directory = new_directory
+        self._sign.directory = new_directory
+        self._directory = new_directory
+        assert self.consistent()
+        try:
+            os.rmdir(self._directory)
+        except (OSError, FileNotFoundError):
+            # not empty or not existing
+            pass
+
+    def markdown_representation(self):
+        """Create representation in Markdown syntax for this thing."""
+        sec = self.get(("name", 1), "")
+        prim = self.get(("name", 0), sec)
+        title = f"- **{prim}**"
+        if prim != sec and sec:
+            title += f" (**{sec}**)"
+        return f"{title}: {self.where}"
+
+    def alt_names_markdown(self):
+        """Create markdown lines with references of alternative names.
+
+        Each line is a dictionary entry mapping the alt name to the
+        markdown line.
+        """
+        # if there is a primary name all other names are only in
+        # parentheses behind the primary name (see markdown_representation)
+        # and therefore not in the correct alphabetical place
+        # so add it to alternative names
+        prim = self.best("name", backup="")
+        return {
+            alt_name: f"- **{alt_name}** → {prim} {self.where}"
+            for alt_name in filter(
+                lambda other_name: other_name and other_name != prim,
+                itertools.chain(
+                    cast(collections.abc.Mapping, self.get("name", {})).values(),
+                    *cast(collections.abc.Mapping, self.get("name_alt", {})).values(),
+                ),
+            )
+        }
+
+    def save(self) -> None:
+        """Save all information into a directory.
+
+        If target files already exists, they are overwritten.
+
+        Calling this save should not be really needed since the data
+        is saved upon change. But who knows if I missed something.
+        Raises:
+            yaml.representer.RepresenterError:
+                If any data is not safe for yaml writing and was not caught
+                by checks in location, sign, thing.
+        """
+        self._thing.save()
+        self._sign.save()
+        self._location.save()

flinventory/constant.py

@@ -0,0 +1,285 @@
+#!/usr/bin/env python
+"""Collection of constants.
+
+By extracting it into a file that is not importing any other one,
+this can be imported everywhere without circular import problem.
+"""
+import os.path
+
+from typing import Any, Self, Union, Optional
+import yaml
+import pycountry
+
+try:
+    import slugify
+except ModuleNotFoundError:
+    print(
+        "module slugify not found. "
+        "Install it system-wide or create a conda environment "
+        "with the environment.yml named bikeparts "
+        "or a virtual environment with the necessary packages liste in environment.yml."
+    )
+    import sys
+
+    sys.exit(1)
+
+VALID_LANGUAGES = {}
+for gl_language in pycountry.languages:
+    try:
+        VALID_LANGUAGES[gl_language.alpha_2] = gl_language
+    except AttributeError:
+        VALID_LANGUAGES[gl_language.alpha_3] = gl_language
+
+
+class InvalidLanguageError(Exception):
+    """Raised if an invalid language code is used."""
+
+
+SCHEMA_FILE = "schema.yaml"
+"""File name of the schema."""
+
+OPTION_FILE = "preferences.yaml"
+"""File name of the preferences."""
+
+THING_DIRECTORY = "things"
+"""Directory within the main data directory with a directory for every thing"""
+THING_FILE = "thing.yaml"
+"""File name for thing (non-localised information) data in directory for a single thing."""
+LOCATION_FILE = "location.yaml"
+"""File name for location data in directory for a single thing."""
+SIGN_FILE = "sign.yaml"
+"""File name for sign data in directory for a single thing."""
+IMAGE_FILE_BASE = "image"
+"""File base name (without extension) for image file."""
+IMAGE_FILE_TYPES = ["jpg", "png", "jpeg", "PNG", "JPG", "JPEG", "webp"]
+"""All supported image file types."""
+RESERVED_FILENAMES = {THING_FILE, LOCATION_FILE, SIGN_FILE} | {
+    IMAGE_FILE_BASE + filetype for filetype in IMAGE_FILE_TYPES
+}
+"""List of all reserved file names in a thing data directory."""
+DISPLAY_RESOURCES = "website_resources"
+"""The directory within main_data_directory with the favicon and possibly more data for UIs."""
+
+YAML_DUMP_OPTIONS = {
+    "Dumper": yaml.SafeDumper,
+    "sort_keys": False,
+    "allow_unicode": True,
+    "indent": 2,
+}
+"""Options for dumping to yaml files. Should be the same everywhere."""
+
+
+def normalize_file_name(file_name: str) -> str:
+    """Normalize a string such that it is a file name that makes no problems."""
+    return slugify.slugify(
+        file_name,
+        separator="_",
+        # allow . in file name:
+        regex_pattern=r"[^-a-z0-9_.]+",
+        replacements=[
+            ["Ü", "Ue"],
+            ["ü", "ue"],
+            ["Ä", "Ae"],
+            ["ä", "ae"],
+            ["Ö", "Oe"],
+            ["ö", "oe"],
+            ["ẞ", "Ss"],
+            ["ß", "ss"],
+        ],
+    ).replace(
+        ".jpeg", ".jpg"
+    )  # this replacement after slugify
+    # to also replace JPEG by jpg (slugify lowers)
+
+
+class Options:
+    """Collections of kinda global options.
+
+    The following **class** members are just for documentation. There are never
+    filled or intended to be used but instead the **instance** members of the same name.
+
+    Maybe one could use the class members and not pass the options object around
+    but instead refer to the class and its members. But then it would be a huge hassle
+    to support for different options in the same program in case one ever wants that.
+    """
+
+    separator: str
+    """How different parts of location shortcuts are separated."""
+
+    languages: list[str]
+    """Language codes in order of preference.
+
+    The corresponding language can be found in VALID_LANGUAGES.
+    """
+
+    main_data_directory: str
+    """The directory with all data."""
+
+    length_unit: str
+    """length unit (preferably mm) for all lengths, mainly sign size.
+
+    For backwards compatibility, the default is cm (centimeter).
+
+    Should be a length unit that LaTeχ understands.
+    """
+
+    sign_max_width: float
+    """Maximum width for a sign in length_unit.
+
+    Should be set if length_unit is set to fit to it.
+    By default 18 which in cm fits to A4 portrait page.
+    """
+
+    sign_max_height: float
+    """Maximum height for a sign in length_unit.
+
+    Should be set if length_unit is set to fit to it.
+    By default 28 which in cm fits to A4 portrait page.
+    """
+
+    @classmethod
+    def from_file(cls, directory: str = ".") -> Self:
+        """Parse options from the options file.
+
+        No possibility to set the config file. Convention over customization!
+        Args:
+            directory: the directory in which to find the config file
+        """
+        try:
+            option_file = open(
+                os.path.join(directory, OPTION_FILE), mode="r", encoding="utf-8"
+            )
+        except FileNotFoundError:
+            return cls({"main_data_directory": directory})
+        with option_file:
+            return cls(yaml.safe_load(option_file) | {"main_data_directory": directory})
+
+    def __init__(self, options: dict[str, Any]):
+        """Create options from content of option file."""
+        self.languages = options.get("languages", ["de", "en"])
+        if isinstance(self.languages, str):
+            self.languages = [self.languages]
+        if not isinstance(self.languages, list):
+            raise ValueError(
+                "Language codes must be a list of strings of "
+                "valid language codes or a single valid language code."
+            )
+        for language in self.languages:
+            if language not in VALID_LANGUAGES:
+                raise ValueError(
+                    f"{language} is not a valid language code. "
+                    f"Valid language codes are {VALID_LANGUAGES}."
+                )
+        if not self.languages:
+            # empty list
+            raise ValueError("We need to use at least one language.")
+
+        for simple_option, default, data_type in (
+            ("separator", "-", str),
+            ("length_unit", "cm", str),
+            ("sign_max_height", 28, (int, float)),
+            ("sign_max_width", 18, (int, float)),
+        ):
+            vars(self)[simple_option] = options.get(simple_option, default)
+            if not isinstance(vars(self)[simple_option], data_type):
+                raise ValueError(
+                    f"{simple_option} unit must a {data_type}, "
+                    f"not {vars(self)[simple_option]} "
+                    f"of type {type(vars(self)[simple_option])}"
+                )
+
+        self.main_data_directory = options.get("main_data_directory", ".")
+
+    def to_yaml(self) -> None:
+        """Write options to options file.
+
+        Overwrites existing options file. Therefore, delete all invalid options
+        and add all defaults.
+        """
+        with open(
+            os.path.join(self.main_data_directory, OPTION_FILE),
+            mode="w",
+            encoding="utf-8",
+        ) as option_file:
+            yaml.dump(
+                {
+                    "separator": self.separator,
+                    "languages": self.languages,
+                    "length_unit": self.length_unit,
+                    "sign_max_height": self.sign_max_height,
+                    "sign_max_width": self.sign_max_width,
+                },
+                option_file,
+                **YAML_DUMP_OPTIONS,
+            )
+
+
+def merge_lists(orig: list[Any], additional: list[Any]) -> list[Any]:
+    """Add all elements of additional to orig that are not in there yet.
+
+    Duplicates in orig and additional individually are preserved.
+    """
+    return orig + [element for element in additional if element not in orig]
+
+
+def fix_deprecated_language_keys(
+    data: dict[str, Any], options: Options, delimiter: str = "_"
+) -> None:
+    """Change language suffixes into subelements.
+
+    Deprecated. Probably does not work anymore.
+
+    For each key xyz_LA move data["xyz_LA"] into data["xyz"]["LA"]
+    where LA is a recognized language suffix.
+
+    If the value is a list, merge it with an existing list.
+
+    Args:
+        data: dictionary that is changed
+        options: options including the language suffixes
+        delimiter: what splits the language from the actual key
+    Raises:
+        ValueError: if I would overwrite data. The keys that are processed
+        before the error are changed. (Yes, this is a bug.)
+    """
+    for key in data:
+        if any(key.endswith(f"{delimiter}{LA}") for LA in options.languages):
+            new_key, language = key.rsplit(delimiter, 1)
+            if new_key in data:
+                if not isinstance(new_key, dict):
+                    raise ValueError(
+                        f"{new_key} has no support for languages, "
+                        f"cannot insert {key}: {data[key]}"
+                    )
+                if data[new_key][language] == data[key]:
+                    # already there
+                    del data[key]
+                elif isinstance(data[new_key][language], list):
+                    if isinstance(data[key], list):
+                        data[new_key][language] = merge_lists(
+                            data[new_key][language], data[key]
+                        )
+                    else:
+                        data[new_key][language].append(data[key])
+                    del data[key]
+                elif isinstance(data[new_key][language], dict):
+                    raise NotImplementedError(
+                        "Inserting into dictionaries at level 2 not supported."
+                    )
+                elif isinstance(data[key], (str, int, float, bool)):
+                    raise ValueError(
+                        f"Value {data[new_key][language]} for key {new_key} in {language} "
+                        f"would be overwritten by value {data[key]} for key {new_key}."
+                    )
+                else:
+                    raise NotImplementedError(
+                        "Did not think of this possibility of"
+                        f"key = {key}, "
+                        f"value = {data[key]}, "
+                        f"type = {type(data[key])}, "
+                        f"new_key = {new_key}, "
+                        f"language = {language}, "
+                        f"existing value = {data[key][language]}, "
+                    )
+            # else: new_key not in data
+            data[new_key] = {language: data[key]}