pyfcstm 0.0.1__py3-none-any.whl

pyfcstm/utils/jinja2.py

@@ -0,0 +1,121 @@
+"""
+This module provides utilities for enhancing Jinja2 environments with Python builtins and additional settings.
+
+It includes functions to add Python built-in functions to Jinja2 environments as filters, tests, and globals,
+as well as adding environment variables and custom text processing functions.
+"""
+
+import builtins
+import inspect
+import os
+import textwrap
+
+import jinja2
+
+from .text import normalize, to_identifier
+
+
+def add_builtins_to_env(env: jinja2.Environment) -> jinja2.Environment:
+    """
+    Mount Python built-in functions to a Jinja2 environment.
+
+    This function adds Python's built-in functions to the specified Jinja2 environment
+    as filters, tests, or global functions based on their characteristics.
+
+    :param env: A Jinja2 Environment instance
+    :type env: jinja2.Environment
+
+    :return: The Jinja2 Environment with Python builtins mounted
+    :rtype: jinja2.Environment
+
+    Example::
+
+        >>> env = jinja2.Environment()
+        >>> env = add_builtins_to_env(env)
+        >>> # Now Python builtins like len, str, etc. are available in templates
+    """
+    # Existing built-in filters, tests and global functions in Jinja2
+    existing_filters = set(env.filters.keys())
+    existing_tests = set(env.tests.keys())
+    existing_globals = set(env.globals.keys())
+
+    # Get all Python built-in functions
+    builtin_items = [(name, obj) for name, obj in inspect.getmembers(builtins)
+                     if not name.startswith('_')]  # Exclude internal functions starting with underscore
+
+    # Categorize functions for appropriate mounting positions
+    for name, func in builtin_items:
+        # Skip non-function objects
+        if not callable(func):
+            continue
+
+        # Determine if the function is suitable as a filter
+        is_filter_candidate = (
+            # Filters typically accept one main argument and may have other optional parameters
+                inspect.isfunction(func) or inspect.isbuiltin(func)
+        )
+
+        # Determine if the function is suitable as a tester
+        is_test_candidate = (
+            # Test functions typically return boolean values, like isinstance, issubclass, etc.
+                name.startswith('is') or
+                name in ('all', 'any', 'callable', 'hasattr')
+        )
+
+        # Mount as a filter (if suitable and no conflict)
+        filter_name = name
+        if is_filter_candidate and filter_name not in existing_filters:
+            env.filters[filter_name] = func
+        env.filters['str'] = str
+        env.filters['set'] = set
+        env.filters['dict'] = dict
+        env.filters['keys'] = lambda x: x.keys()
+        env.filters['values'] = lambda x: x.values()
+        env.filters['enumerate'] = enumerate
+        env.filters['reversed'] = reversed
+        env.filters['filter'] = lambda x, y: filter(y, x)
+
+        # Mount as a tester (if suitable and no conflict)
+        test_name = name
+        if name.startswith('is'):
+            # For functions starting with 'is', the prefix can be removed as the tester name
+            test_name = name[2:].lower()
+        if is_test_candidate and test_name not in existing_tests:
+            env.tests[test_name] = func
+
+        # Mount as a global function (if no conflict)
+        if name not in existing_globals:
+            env.globals[name] = func
+
+    return env
+
+
+def add_settings_for_env(env: jinja2.Environment) -> jinja2.Environment:
+    """
+    Add additional settings and functions to a Jinja2 environment.
+
+    This function enhances a Jinja2 environment by:
+    1. Adding Python built-in functions
+    2. Adding custom text processing filters
+    3. Adding environment variables as global variables
+
+    :param env: The Jinja2 environment to enhance
+    :type env: jinja2.Environment
+
+    :return: The enhanced Jinja2 environment
+    :rtype: jinja2.Environment
+
+    Example::
+
+        >>> env = jinja2.Environment()
+        >>> env = add_settings_for_env(env)
+        >>> # Now the environment has additional filters and globals
+    """
+    env = add_builtins_to_env(env)
+    env.filters['normalize'] = normalize
+    env.filters['to_identifier'] = to_identifier
+    env.globals['indent'] = textwrap.indent
+    for key, value in os.environ.items():
+        if key not in env.globals:
+            env.globals[key] = value
+    return env

pyfcstm/utils/json.py

@@ -0,0 +1,125 @@
+"""
+This module provides a base interface for JSON serialization and deserialization operations.
+It defines an abstract base class IJsonOp that implements common JSON/YAML file I/O operations
+and requires concrete classes to implement the actual serialization logic.
+
+The module supports both JSON and YAML formats for data persistence, with methods for reading
+from and writing to files in either format.
+"""
+
+import json
+from pprint import pformat
+
+import yaml
+
+
+class IJsonOp:
+    """
+    An interface class that provides JSON serialization/deserialization capabilities.
+
+    This class defines a common interface for objects that need to be serialized to
+    and deserialized from JSON/YAML formats. Concrete classes must implement the
+    _to_json() and _from_json() methods.
+
+    Example:
+        >>> class MyData(IJsonOp):
+        ...     def _to_json(self):
+        ...         return {"data": self.data}
+        ...
+        ...     @classmethod
+        ...     def _from_json(cls, data):
+        ...         return cls(data["data"])
+    """
+
+    def _to_json(self):
+        """
+        Convert the object to a JSON-serializable format.
+
+        :raises NotImplementedError: This method must be implemented by concrete classes.
+        """
+        raise NotImplementedError
+
+    @classmethod
+    def _from_json(cls, data):
+        """
+        Create an instance of the class from JSON-formatted data.
+
+        :param data: The JSON data to deserialize
+        :raises NotImplementedError: This method must be implemented by concrete classes.
+        """
+        raise NotImplementedError
+
+    @property
+    def json(self):
+        """
+        Get the JSON representation of the object.
+
+        :return: JSON-serializable representation of the object
+        :rtype: dict
+        """
+        return self._to_json()
+
+    def to_json(self, json_file):
+        """
+        Save the object to a JSON file.
+
+        :param json_file: Path to the output JSON file
+        :type json_file: str
+        """
+        data = self._to_json()
+        with open(json_file, 'w') as f:
+            json.dump(data, f, indent=4, ensure_ascii=False)
+
+    def to_yaml(self, yaml_file):
+        """
+        Save the object to a YAML file.
+
+        :param yaml_file: Path to the output YAML file
+        :type yaml_file: str
+        """
+        data = self._to_json()
+        with open(yaml_file, 'w') as f:
+            yaml.safe_dump(data, f)
+
+    @classmethod
+    def from_json(cls, data):
+        """
+        Create an instance from JSON data.
+
+        :param data: JSON-formatted data
+        :type data: dict
+        :return: An instance of the class
+        :rtype: IJsonOp
+        :raises TypeError: If the created object is not an instance of the class
+        """
+        obj = cls._from_json(data)
+        if not isinstance(obj, cls):
+            raise TypeError(f'{cls!r} type expected, but {type(obj)!r} found in data:\n'
+                            f'{pformat(data)}')
+        return obj
+
+    @classmethod
+    def read_json(cls, json_file):
+        """
+        Create an instance by reading from a JSON file.
+
+        :param json_file: Path to the input JSON file
+        :type json_file: str
+        :return: An instance of the class
+        :rtype: IJsonOp
+        """
+        with open(json_file, 'r') as f:
+            return cls.from_json(json.load(f))
+
+    @classmethod
+    def read_yaml(cls, yaml_file):
+        """
+        Create an instance by reading from a YAML file.
+
+        :param yaml_file: Path to the input YAML file
+        :type yaml_file: str
+        :return: An instance of the class
+        :rtype: IJsonOp
+        """
+        with open(yaml_file, 'r') as f:
+            return cls.from_json(yaml.safe_load(f))

pyfcstm/utils/text.py

@@ -0,0 +1,91 @@
+"""
+String normalization utilities for converting arbitrary strings to valid identifiers.
+
+This module provides functions to normalize strings into valid identifier formats
+that can be used in programming contexts. It handles special characters, spaces,
+and ensures compliance with identifier naming rules.
+"""
+
+from unidecode import unidecode
+
+
+def normalize(input_string):
+    """
+    Normalize a string to a valid identifier format.
+
+    This is a convenience wrapper around to_identifier() with strict_mode set to False.
+
+    :param input_string: The string to be normalized
+    :type input_string: str
+
+    :return: A normalized identifier string
+    :rtype: str
+
+    Example::
+
+        >>> normalize("Hello World!")
+        'Hello_World'
+        >>> normalize("123 Test")
+        '123_Test'
+    """
+    return to_identifier(input_string, strict_mode=False)
+
+
+def to_identifier(input_string, strict_mode: bool = True):
+    """
+    Convert any string to a valid identifier format [0-9a-zA-Z_]+
+
+    Rules:
+    1. Preserve all letters and numbers
+    2. Convert spaces and special characters to underscores
+    3. If strict_mode is True, ensure the first character is not a number (as identifiers typically cannot start with a number)
+    4. If strict_mode is True, handle empty strings and None inputs
+    5. Handle consecutive special characters to avoid multiple consecutive underscores
+
+    :param input_string: The string to be converted
+    :type input_string: str
+    :param strict_mode: When True, applies additional rules to ensure identifier validity across most languages.
+                        When False, allows empty strings and identifiers starting with numbers
+    :type strict_mode: bool, optional
+
+    :return: A valid identifier string
+    :rtype: str
+
+    Example::
+
+        >>> to_identifier("Hello World!", strict_mode=True)
+        'Hello_World'
+        >>> to_identifier("123 Test", strict_mode=True)
+        '_123_Test'
+        >>> to_identifier("", strict_mode=True)
+        '_empty'
+    """
+    input_string = unidecode(input_string)
+    # Initialize result string
+    result = ""
+
+    # Process each character
+    prev_is_underscore = False
+    for char in input_string:
+        if char.isalnum():  # If it's a letter or number
+            result += char
+            prev_is_underscore = False
+        else:  # If it's another character
+            if not prev_is_underscore:  # Avoid consecutive underscores
+                result += "_"
+                prev_is_underscore = True
+
+    # Remove trailing underscore if present
+    result = result.rstrip("_")
+
+    # Apply strict mode rules if enabled
+    if strict_mode:
+        # Ensure it's not an empty string
+        if not result:
+            return "_empty"
+
+        # Ensure the first character is not a digit
+        if result and result[0].isdigit():
+            result = "_" + result
+
+    return result

pyfcstm/utils/validate.py

@@ -0,0 +1,102 @@
+"""
+This module provides a validation framework for model validation in Python.
+It includes base classes and exceptions for implementing validation rules and handling validation errors.
+The framework supports collecting multiple validation errors and provides a clean interface for validation.
+
+Usage:
+    >>> class MyModel(IValidatable):
+    ...     def _my_validator_function(self):
+    ...         ...
+    ...
+    ...     __validators__ = [my_validator_function]
+    ...
+    ...     def __init__(self, data):
+    ...         self.data = data
+"""
+
+import os
+from typing import List
+
+from hbutils.string import plural_word
+
+
+class ValidationError(Exception):
+    """
+    Base exception class for validation errors.
+
+    This exception should be raised when a single validation rule fails.
+    """
+    pass
+
+
+class ModelValidationError(Exception):
+    """
+    Exception class for aggregating multiple validation errors.
+
+    This exception contains a list of ValidationError instances and formats them
+    into a readable error message.
+
+    :param errors: List of validation errors that occurred
+    :type errors: List[ValidationError]
+
+    :ivar errors: Stored validation errors
+    :type errors: List[ValidationError]
+    """
+
+    def __init__(self, errors: List[ValidationError]):
+        super().__init__(
+            f"Model validation error, {plural_word(len(errors), 'error')} in total:{os.linesep}"
+            f"{os.linesep.join(map(lambda x: f'{x[0]}. {x[1]}', enumerate(map(repr, errors), start=1)))}",
+        )
+        self.errors = errors
+
+
+class IValidatable:
+    """
+    Interface class for implementing validatable objects.
+
+    Classes inheriting from IValidatable should define their validation rules
+    in the __validators__ class variable as a list of validator functions.
+    Each validator function should take the instance as parameter and raise
+    ValidationError if validation fails.
+
+    :cvar __validators__: List of validator functions to be applied
+    :type __validators__: List[callable]
+
+    Usage:
+        >>> class MyModel(IValidatable):
+        ...     def _my_validator_function(self):
+        ...         ...
+        ...
+        ...     __validators__ = [my_validator_function]
+        ...     
+        >>> model = MyModel()
+        >>> model.validate()  # Raises ModelValidationError if validation fails
+    """
+
+    __validators__ = []
+
+    def _validate_for_errors(self) -> List[ValidationError]:
+        """
+        Execute all validators and collect validation errors.
+
+        :return: List of validation errors that occurred
+        :rtype: List[ValidationError]
+        """
+        errors = []
+        for validator in self.__validators__:
+            try:
+                validator(self)
+            except ValidationError as err:
+                errors.append(err)
+        return errors
+
+    def validate(self):
+        """
+        Validate the object using all registered validators.
+
+        :raises ModelValidationError: If any validation errors occur
+        """
+        errors = self._validate_for_errors()
+        if errors:
+            raise ModelValidationError(errors)

pyfcstm-0.0.1.dist-info/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.