myth-hash 0.1.0__tar.gz

myth-hash-0.1.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2024 Claas Flint
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

myth-hash-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include myth-hash/data/*.json

myth-hash-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.1
+Name: myth-hash
+Version: 0.1.0
+Summary: A tool for generating human-readable, multilingual fantasy character names based on input string hashes.
+Home-page: https://github.com/yourusername/myth_hash
+Author: Claas Flint
+Author-email: claas.flint@gmail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# Myth Hash
+
+`Myth Hash` is aPython package designed to create human-readable hashes that are not only functional but also cognitively engaging. A key feature of this tool is its multilingual support, enabling the generation of hashes in multiple languages. The concept behind these human-readable hashes is to enhance communication and recognition by creating hashes that form vivid, memorable mental images. The goal is to make the hash as human-compatible as possible, ensuring it effectively serves its purpose in an intuitive and user-friendly manner.
+## Features
+
+- **Character Name Generation:** Generates a unique fantasy name based on an input string.
+- **Supported Languages:** Currently supports English (`en`) and German (`de`).
+- **CLI Support:** Easily generate names via the command line.
+- **Library Usage:** Integrate `Myth Hash` into your Python projects.
+- **Customizable Data:** Modify the included JSON files to customize the generated names.
+
+## Installation
+
+You can install `Myth Hash` using pip:
+
+```bash
+pip install myth-hash
+```
+
+## Usage
+
+### Command Line Interface (CLI)
+
+After installing the package, you can use the myth-hash command to generate fantasy names.
+
+Basic Example:
+    
+```bash
+myth-hash "The moon whispered secrets, but only the cats understood." 
+```
+Example Output:
+```bash
+exotic-thoughtful-Griffin
+```
+
+### Using as a Library
+
+You can also use Myth Hash within your Python code:
+
+Example:
+```python
+import myth_hash
+
+# Generate a character name using the hash_name function
+name_parts = myth_hash.hash_name("The moon whispered secrets, but only the cats understood.", "en")
+print(name_parts)  # Output: ('exotic', 'thoughtful', 'Griffin')
+
+# Access individual parts of the name
+physical_attr, personality_attr, mystical_creature = name_parts
+print(f"Physical Attribute: {physical_attr}")
+print(f"Personality Trait: {personality_attr}")
+print(f"Mystical Creature: {mystical_creature}")
+```
+
+## Contributing
+
+Contributions are welcome! Please fork the repository, create a new branch for your feature or bug fix, and submit a pull request.
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for details.

myth-hash-0.1.0/README.md

@@ -0,0 +1,61 @@
+# Myth Hash
+
+`Myth Hash` is aPython package designed to create human-readable hashes that are not only functional but also cognitively engaging. A key feature of this tool is its multilingual support, enabling the generation of hashes in multiple languages. The concept behind these human-readable hashes is to enhance communication and recognition by creating hashes that form vivid, memorable mental images. The goal is to make the hash as human-compatible as possible, ensuring it effectively serves its purpose in an intuitive and user-friendly manner.
+## Features
+
+- **Character Name Generation:** Generates a unique fantasy name based on an input string.
+- **Supported Languages:** Currently supports English (`en`) and German (`de`).
+- **CLI Support:** Easily generate names via the command line.
+- **Library Usage:** Integrate `Myth Hash` into your Python projects.
+- **Customizable Data:** Modify the included JSON files to customize the generated names.
+
+## Installation
+
+You can install `Myth Hash` using pip:
+
+```bash
+pip install myth-hash
+```
+
+## Usage
+
+### Command Line Interface (CLI)
+
+After installing the package, you can use the myth-hash command to generate fantasy names.
+
+Basic Example:
+    
+```bash
+myth-hash "The moon whispered secrets, but only the cats understood." 
+```
+Example Output:
+```bash
+exotic-thoughtful-Griffin
+```
+
+### Using as a Library
+
+You can also use Myth Hash within your Python code:
+
+Example:
+```python
+import myth_hash
+
+# Generate a character name using the hash_name function
+name_parts = myth_hash.hash_name("The moon whispered secrets, but only the cats understood.", "en")
+print(name_parts)  # Output: ('exotic', 'thoughtful', 'Griffin')
+
+# Access individual parts of the name
+physical_attr, personality_attr, mystical_creature = name_parts
+print(f"Physical Attribute: {physical_attr}")
+print(f"Personality Trait: {personality_attr}")
+print(f"Mystical Creature: {mystical_creature}")
+```
+
+## Contributing
+
+Contributions are welcome! Please fork the repository, create a new branch for your feature or bug fix, and submit a pull request.
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for details.

myth-hash-0.1.0/myth_hash/__init__.py

@@ -0,0 +1,5 @@
+from .core import hash_name
+
+__all__ = [
+    "hash_name",
+]

myth-hash-0.1.0/myth_hash/cli.py

@@ -0,0 +1,89 @@
+import argparse
+import json
+import logging
+
+from myth_hash import hash_name
+
+
+def setup_logging(log_level: str) -> None:
+    numeric_level = getattr(logging, log_level.upper(), None)
+    if not isinstance(numeric_level, int):
+        raise ValueError(f"Invalid log level: {log_level}")
+    logging.basicConfig(level=numeric_level)
+
+
+def hash_name_cli(input_string: str, language: str, output_format: str) -> None:
+    try:
+        physical_attr, personality_attr, character = hash_name(input_string, language)
+    except Exception as e:
+        logging.error(f"Failed to generate fantasy name: {e}")
+        raise
+
+    if output_format == "text":
+        print(f"{physical_attr}-{personality_attr}-{character.replace(' ', '')}")
+    elif output_format == "json":
+        output = {
+            "physical_attribute": physical_attr,
+            "personality_attribute": personality_attr,
+            "character": character,
+        }
+        print(json.dumps(output, ensure_ascii=False))
+
+
+def parse_arguments() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Generates a fantasy name consisting of two character attributes and a mythical creature from a hash value of an input string."
+    )
+    parser.add_argument(
+        "input_string",
+        type=str,
+        help="Input string to hash and generate a fantasy name.",
+    )
+    parser.add_argument(
+        "-l",
+        "--language",
+        type=str,
+        default="en",
+        choices=["en", "de"],
+        help="Specify the output language. Supported languages: English (en) and German (de). Default is English.",
+    )
+    parser.add_argument(
+        "-f",
+        "--format",
+        type=str,
+        default="text",
+        choices=["text", "json"],
+        help="Specify the output format. Choose between plain text (text) and JSON (json). Default is text.",
+    )
+    parser.add_argument(
+        "--log-level",
+        type=str,
+        default="INFO",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+        help="Set the logging level. Default is INFO.",
+    )
+
+    return parser.parse_args()
+
+
+def validate_input_string(input_string: str) -> None:
+    if not input_string.strip():
+        raise ValueError("Input string cannot be empty.")
+
+
+def main():
+    args = parse_arguments()
+
+    setup_logging(args.log_level)
+
+    try:
+        validate_input_string(args.input_string)
+        hash_name_cli(args.input_string, args.language, args.format)
+    except ValueError as ve:
+        logging.error(f"Input validation error: {ve}")
+    except Exception as e:
+        logging.error(f"An unexpected error occurred: {e}")
+
+
+if __name__ == "__main__":
+    main()

myth-hash-0.1.0/myth_hash/core/__init__.py

@@ -0,0 +1,13 @@
+from .character_data_loader import CharacterData, CharacterDataLoader
+from .hash_util import check_language, generate_indices, hash_name
+from .words import CharacterNoun, NominativAdjective
+
+__all__ = [
+    "CharacterDataLoader",
+    "CharacterData",
+    "hash_name",
+    "generate_indices",
+    "check_language",
+    "CharacterNoun",
+    "NominativAdjective",
+]

myth-hash-0.1.0/myth_hash/core/character_data_loader.py

@@ -0,0 +1,70 @@
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from .words import CharacterNoun, NominativAdjective
+
+BASE_PATH = Path(__file__).parent.parent / "data"
+CHARACTER_NOUNS_FILE = BASE_PATH / "character_nouns.json"
+PHYSICAL_ATTRIBUTES_FILE = BASE_PATH / "physical_attributes.json"
+PERSONALITY_ATTRIBUTES_FILE = BASE_PATH / "personality_attributes.json"
+
+
+@dataclass
+class CharacterData:
+    character_nouns: list[CharacterNoun]
+    physical_attributes: list[NominativAdjective]
+    personality_attributes: list[NominativAdjective]
+
+
+class CharacterDataLoader:
+    _instance: Optional["CharacterDataLoader"] = None
+    _character_data: CharacterData | None = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._load_data()
+        return cls._instance
+
+    def _load_data(self) -> None:
+        self._character_data = CharacterData(
+            character_nouns=self._load_character_nouns(),
+            physical_attributes=self._load_attributes(PHYSICAL_ATTRIBUTES_FILE),
+            personality_attributes=self._load_attributes(PERSONALITY_ATTRIBUTES_FILE),
+        )
+
+    @staticmethod
+    def _load_attributes(file_path: Path) -> list[NominativAdjective]:
+        try:
+            with open(file_path, encoding="utf8") as f:
+                json_dict = json.load(f)
+        except (FileNotFoundError, json.JSONDecodeError) as e:
+            raise RuntimeError(f"Error loading attributes from {file_path}: {e}") from e
+
+        return [
+            NominativAdjective(word_id, data["words"])
+            for word_id, data in json_dict.items()
+        ]
+
+    @staticmethod
+    def _load_character_nouns() -> list[CharacterNoun]:
+        try:
+            with open(CHARACTER_NOUNS_FILE, encoding="utf8") as f:
+                json_dict = json.load(f)
+        except (FileNotFoundError, json.JSONDecodeError) as e:
+            raise RuntimeError(
+                f"Error loading character nouns from {CHARACTER_NOUNS_FILE}: {e}"
+            ) from e
+
+        return [
+            CharacterNoun(char_id, data["data"]) for char_id, data in json_dict.items()
+        ]
+
+    @property
+    def character_data(self) -> CharacterData:
+        if self._character_data is None:
+            self._load_data()
+        assert self._character_data is not None
+        return self._character_data

myth-hash-0.1.0/myth_hash/core/hash_util.py

@@ -0,0 +1,63 @@
+import hashlib
+
+from .character_data_loader import CharacterData, CharacterDataLoader
+
+SUPPORTED_LANGUAGES = {"en", "de"}
+
+
+def check_language(language: str) -> None:
+    if language not in SUPPORTED_LANGUAGES:
+        raise ValueError(
+            f"Unsupported language '{language}'. Supported languages are: {', '.join(SUPPORTED_LANGUAGES)}."
+        )
+
+
+def generate_indices(input_string: str, list_sizes: list[int]) -> list[int]:
+    sha256 = hashlib.sha256(input_string.encode())
+    d = sha256.digest()
+    hash_length = len(d)
+    indices = []
+
+    for i, size in enumerate(list_sizes):
+        start = (hash_length // len(list_sizes)) * i
+        end = start + (hash_length // len(list_sizes))
+
+        segment = int.from_bytes(d[start:end], "big")
+
+        index = segment % size
+        indices.append(index)
+
+    return indices
+
+
+def hash_name(input_string: str, language: str = "en") -> tuple[str, str, str]:
+    check_language(language)
+
+    data_loader = CharacterDataLoader()
+    character_data: CharacterData = data_loader.character_data
+
+    indices = generate_indices(
+        input_string,
+        [
+            len(character_data.physical_attributes),
+            len(character_data.personality_attributes),
+            len(character_data.character_nouns),
+        ],
+    )
+
+    physical_attr_index = indices[0]
+    personality_attr_index = indices[1]
+    character_nouns_index = indices[2]
+
+    character_noun = character_data.character_nouns[character_nouns_index]
+    physical_attr = character_data.physical_attributes[physical_attr_index].word(
+        language, character_noun.get_attribute(language, "gender")
+    )
+    personality_attr = character_data.personality_attributes[
+        personality_attr_index
+    ].word(language, character_noun.get_attribute(language, "gender"))
+    return (
+        physical_attr,
+        personality_attr,
+        character_noun.get_attribute(language, "word"),
+    )

myth-hash-0.1.0/myth_hash/core/words.py

@@ -0,0 +1,117 @@
+class NominativAdjective:
+    def __init__(self, word_id: int, words: dict) -> None:
+        """
+        Constructor for the NominativAdjective class.
+
+        :param word_id: ID of the adjective
+        :param words: A dictionary that contains the words in different languages and genders
+        """
+        self.word_id = word_id
+        self.validate_words(words)
+        self.words = words
+
+    def __str__(self) -> str:
+        return str(
+            self.words.get("en", {}).get("neutral", "No neutral English word available")
+        )
+
+    def __repr__(self) -> str:
+        return f"Adjective: {self.word_id} - {self.words}"
+
+    @staticmethod
+    def validate_words(words: dict):
+        """
+        Validates the structure of the words dictionary. The dictionary should contain languages as keys
+        and dictionaries as values, with the inner dictionaries having genders as keys and words as values.
+
+        :param words: Dictionary to validate
+        :raises ValueError: If the dictionary structure is invalid
+        """
+        for language, genders in words.items():
+            if not isinstance(genders, dict):
+                raise ValueError(
+                    f"The value for language '{language}' must be a dictionary."
+                )
+            for gender in genders:
+                if gender not in ["masculine", "feminine", "neutral"]:
+                    raise ValueError(
+                        f"Invalid gender '{gender}' for language '{language}'."
+                    )
+
+    def word(self, language: str, gender: str = "neutral") -> str:
+        """
+        Returns the word in the specified language and gender.
+
+        :param language: The language of the word
+        :param gender: The gender of the word. Options are "masculine", "feminine", and "neutral".
+                       If no gender is specified, the neutral word is returned.
+        :return: The word in the specified language and gender
+        """
+        try:
+            return str(self.words[language][gender])
+        except KeyError as exc:
+            raise ValueError(
+                f"No word found for the language '{language}' and gender '{gender}'."
+            ) from exc
+
+    def set_word(self, language: str, gender: str, word: str) -> None:
+        self.words[language][gender] = word
+
+    def as_json(self) -> dict:
+        """
+        Returns a JSON-compatible dictionary that contains the attributes of the adjective.
+
+        :return: A dictionary that contains the attributes of the adjective
+        """
+        return {"id": self.word_id, "words": self.words}
+
+
+class CharacterNoun:
+    def __init__(self, character_id: int, data: dict) -> None:
+        """
+        Constructor for the CharacterNoun class.
+
+        :param character_id: ID of the noun
+        :param data: A dictionary containing the word and gender information in different languages
+        """
+        self.character_id = character_id
+        self.data = data
+
+    def __str__(self) -> str:
+        return self.get_attribute("en", "word")
+
+    def __repr__(self) -> str:
+        return f"CharacterNoun: {self.character_id} - {self.data}"
+
+    def get_attribute(self, language: str, attribute: str) -> str:
+        """
+        Returns the specified attribute in the specified language.
+
+        :param language: The language of the attribute
+        :param attribute: The attribute to get. Options are 'word' and 'gender'.
+        :return: The attribute in the specified language
+        """
+        try:
+            return str(self.data[language][attribute])
+        except KeyError as exc:
+            raise ValueError(
+                f"No {attribute} found for the language '{language}'."
+            ) from exc
+
+    def as_json(self) -> dict:
+        """
+        Returns a JSON-compatible dictionary that contains the attributes of the noun.
+
+        :return: A dictionary that contains the attributes of the noun
+        """
+        return {"character_id": self.character_id, "data": self.data}
+
+    @staticmethod
+    def from_json(json: dict) -> "CharacterNoun":
+        """
+        Returns a CharacterNoun object from a JSON-compatible dictionary.
+
+        :param json: A JSON-compatible dictionary that contains the attributes of the noun
+        :return: A CharacterNoun object
+        """
+        return CharacterNoun(json["character_id"], json["data"])