batutils 2.0.0__py3-none-any.whl

batutils/tpu/string/_string.py

@@ -0,0 +1,160 @@
+__all__ = [
+    'str_norm',
+    'str_norm_eq',
+    'maxlen',
+    'slugify',
+    'dequote',
+]
+
+"""String Related Type Utilities
+
+Utilities for manipulating strings, i.e. the input AND output of functions here
+should both only be strings (str and/or unicode).
+
+These should be pretty basic though, e.g. HTML stuff or formatting stuff etc.
+should probably live somewhere else.
+
+This should NOT contain functions that:
+
+ - ...take in a string and output something else, e.g. convert or cast a
+   string to some other object type (that's "casting").
+ - ...take in some other object type and output a string, e.g. to renders
+   stuff readable (that's "formatting").
+"""
+from batutils.tpu.casting import decode_bytes
+from batutils.tpu.structs import *
+
+_SLUG_SPACER = re.compile(r'[\s_\-:;,.]+')
+_SLUGGER = re.compile(r'[^a-z0-9\-]+')
+
+
+def str_norm(string: Union[str, bytes], default='') -> str:
+    """Normalize a string, i.e. ensure that it is indeed a string (if possible)
+    and strip leading and trailing whitespaces and make it lowercase.
+
+    Returns a default value if the string is a None or if an exception is
+    encountered while trying to turn a non-string into a string via the str()
+    method.
+
+    :param string:
+    :type string:
+    :param default:
+    :type default: any
+    :return:
+    :rtype:
+    """
+    if isinstance(string, bytes):
+        try:
+            string = decode_bytes(string)
+        except Exception:
+            return default
+
+    if not isinstance(string, str):
+        if string is None:
+            return default
+        try:
+            string = str(string)
+        except Exception:
+            return default
+    return string.strip().lower()
+
+
+def str_norm_eq(string, another_string):
+    """Checks if two strings are the same if normalized (i.e. stripped of
+    leading and trailing whitespaces and made lowercase).
+
+    Returns False if one or both can't be turned into a string.
+
+    :param string:
+    :type string:
+    :param another_string:
+    :type another_string:
+    :return:
+    :rtype: bool
+    """
+    string = str_norm(string, default=None)
+    another_string = str_norm(another_string, default=None)
+    if string is not None and another_string is not None:
+        return string == another_string
+    return False
+
+
+def maxlen(string: str, max_length: int) -> str:
+    """Trims the back of a string if it exceeds a certain length.
+
+    If the given parameter is not a string, it'll be returned unchanged.
+
+    :param string:
+    :type string: str, unicode or any
+    :param max_length:
+    :type max_length: int
+    :return:
+    :rtype: str, unicode or any
+    """
+    if string and isinstance(string, str) and len(string) > max_length:
+        string = string[:max_length]
+    return string
+
+
+def slugify(string):
+    """Returns a "slug" version of a string (replacing any whitespaces
+    and separators with - and removing any character that is not a-z or 0-9)
+
+    :param string:
+    :type string:
+    :return:
+    :rtype:
+    """
+    string = str_norm(string)
+    string = _SLUG_SPACER.sub('-', string)
+    return _SLUGGER.sub('', string)
+
+
+def dequote(string: str, symbol_list: Optional[Union[str, List[str]]] = None) -> str:
+    """Removes single or double quote pairs (or any custom given quotation
+    character symbold) from a string if it is encompassed.
+    in those.
+
+    Example:
+
+    >>> dequote('"foo"')
+    'foo'
+    >>> dequote("'bar and another bar'")
+    'bar and another bar'
+
+    By default only single `'` or double quotes `"` are removed but you can pass
+    in a different character symbol or a list of symbols to act as quotes.
+
+    >>> dequote('$foo$', '$')
+    'foo'
+    >>> dequote('%bar and another bar%', ['%', '$', '"'])
+    'bar and another bar'
+
+    The string must start and end with the same type of quote in order for it
+    to be removed. In all other cases the same string will be returned unchanged
+    (even if the value isn't an actual string').
+
+    >>> dequote('"foo')
+    '"foo'
+    >>> dequote('%bar and another bar$', ['%', '$', '"'])
+    '%bar and another bar$'
+    >>> dequote(None)
+    None
+    >>> dequote(42)
+    42
+
+    :param string: String to remove surrounding quotes from
+    :type string: str | unicode
+    :param symbol_list: A list of symbols that should act as quotes (optional)
+    :type symbol_list: None | list | tuple | set | str | unicode
+    :return: The string input without surrounding quotes or whatever was passed
+             in unchanged.
+    :rtype: str | unicode
+    """
+    if string and isinstance(string, str):
+        symbol_list = symbol_list or ('"', "'")
+        if not isinstance(symbol_list, (list, tuple, set)):
+            symbol_list = [symbol_list]
+        if string[0] == string[-1] and string[0] in symbol_list:
+            return string[1:-1]
+    return string

batutils/tpu/structs/__init__.py

@@ -0,0 +1 @@
+from batutils.tpu.structs._base import *

batutils/tpu/structs/_base.py

@@ -0,0 +1,3 @@
+from batutils.structs import *
+
+import datetime

batutils/tpu/structs/empty/__init__.py

@@ -0,0 +1 @@
+from batutils.tpu.structs.empty._empty import *

batutils/tpu/structs/empty/_empty.py

@@ -0,0 +1,387 @@
+__all__ = [
+    'Empty',
+    'EmptyDict',
+    'if_empty',
+]
+
+import collections
+
+
+class _Empty(object):
+    """
+    This is essentially just a glorified None that tries not to break any code
+    that makes certain wild assumptions.
+
+    The typical use case here would be to return Empty instead of None as a
+    default value for something not found so you don't have to check again and
+    again if you got a "None" before calling an attribute so as to not raise
+    an AttributeError as long as you don't care if the results of whatever
+    you're doing don't make sense until later.
+
+    Totally made up use case example:
+
+    character = get_character(123)
+    if character:
+        if hasattr(character, 'user'):
+            user = character.user
+            if user:
+                if hasattr(user, 'email'):
+                    email = user.email
+                    if email:
+                        if isinstance(email, (str, unicode)):
+                            if email.startswith('_'):
+                                raise ValueError('Emails can not start with underscores')
+
+    Totally made up example using Empty as default values for failed lookups:
+
+    if get_character(123).user.email.startswith('_'):
+        raise ValueError('Emails can not start with underscores')
+
+    Here get_character returns Empty when it failed to find a character so the
+    attribute 'user' of Empty will also return Empty.
+
+    Ditto for the 'email' attribute of 'user'.
+
+    The 'startswith' of 'email' will also be Empty and that will call the
+    Empty.__call__('_') which ALSO return Empty and then finally the if
+    statement will call Empty.__nonzero__() which returns False.
+
+    So we can super quickly make sure the email doesn't start with an
+    underscore IF that's the only thing we care about and don't mind if any
+    of the stuff in that chain failed or wasn't found.
+
+    After all, we can always check later explicitly for the validity of any
+    and/or all of these attributes.
+
+    Another super simple use case (and probably more likely) would be to use this for quick "throwaway" lookups:
+
+    E.g. printing the domain of the email address of the example above:
+
+    print 'Email:', character.user.email[character.user.email.index('@')+1:]
+
+    If everything was found here, we'll get:
+    "Email: ccpgames.com"
+
+    If not, we'll get:
+    "Email: Empty"
+
+    Could also do this:
+    print 'Email:', character.user.email[character.user.email.index('@')+1:] or '-'
+    "Email: -"
+    """
+    ___inst = None
+
+    def __new__(cls, *args, **kwargs):
+        if cls.___inst is None:
+            cls.___inst = super(_Empty, cls).__new__(cls, *args, **kwargs)
+        return cls.___inst
+
+    def __cmp__(self, other):
+        if other is Empty:
+            return 0
+        return -1
+
+    def __lt__(self, other):
+        return False
+
+    def __gt__(self, other):
+        return False
+
+    def __le__(self, other):
+        if other is Empty:
+            return True
+        return False
+
+    def __ge__(self, other):
+        if other is Empty:
+            return True
+        return False
+
+    def __eq__(self, other):
+        if other is Empty:
+            return True
+        return False
+
+    def __ne__(self, other):
+        if other is Empty:
+            return False
+        return True
+
+    def __nonzero__(self):
+        return False
+
+    def __getattr__(self, name):
+        return Empty
+
+    def __setattr__(self, name, value):
+        pass
+
+    def __delattr__(self, name):
+        pass
+
+    def __instancecheck__(self, instance):
+        return False
+
+    def __subclasscheck__(self, subclass):
+        return False
+
+    def __str__(self):
+        return 'Empty'
+
+    def __unicode__(self):
+        return u'Empty'
+
+    def __repr__(self):
+        return '<Empty>'
+
+    def __call__(self, *args, **kwargs):
+        return Empty
+
+    def __len__(self):
+        return 0
+
+    def __getitem__(self, key):
+        return Empty
+
+    def __contains__(self, item):
+        return False
+
+    def __missing__(self, key):
+        return Empty
+
+    def __int__(self):
+        return 0
+
+    def __float__(self):
+        return 0.0
+
+    def __complex__(self):
+        return complex(0, 0)
+
+    def __oct__(self):
+        return 00
+
+    def __hex__(self):
+        return 0x0
+
+    def __index__(self):
+        return 0
+
+    def __trunc__(self):
+        return 0
+
+    def __format__(self, formatstr):
+        return 'Empty'
+
+    def __pos__(self):
+        return Empty
+
+    def __neg__(self):
+        return Empty
+
+    def __abs__(self):
+        return Empty
+
+    def __invert__(self):
+        return Empty
+
+    def __round__(self, n):
+        return Empty
+
+    def __floor__(self):
+        return Empty
+
+    def __ceil__(self):
+        return Empty
+
+    def __copy__(self):
+        return Empty
+
+    def __deepcopy__(self):
+        return Empty
+
+    def __add__(self, other):
+        return Empty
+
+    def __radd__(self, other):
+        return Empty
+
+    def __sub__(self, other):
+        return Empty
+
+    def __rsub__(self, other):
+        return Empty
+
+    def __mul__(self, other):
+        return Empty
+
+    def __rmul__(self, other):
+        return Empty
+
+    def __floordiv__(self, other):
+        return Empty
+
+    def __rfloordiv__(self, other):
+        return Empty
+
+    def __div__(self, other):
+        return Empty
+
+    def __rdiv__(self, other):
+        return Empty
+
+    def __truediv__(self, other):
+        return Empty
+
+    def __rtruediv__(self, other):
+        return Empty
+
+    def __mod__(self, other):
+        return Empty
+
+    def __rmod__(self, other):
+        return Empty
+
+    def __divmod__(self, other):
+        return Empty
+
+    def __rdivmod__(self, other):
+        return Empty
+
+    def __pow__(self):
+        return Empty
+
+    def __rpow__(self):
+        return Empty
+
+    def __lshift__(self, other):
+        return Empty
+
+    def __rlshift__(self, other):
+        return Empty
+
+    def __rshift__(self, other):
+        return Empty
+
+    def __rrshift__(self, other):
+        return Empty
+
+    def __and__(self, other):
+        return Empty
+
+    def __rand__(self, other):
+        return Empty
+
+    def __or__(self, other):
+        return Empty
+
+    def __ror__(self, other):
+        return Empty
+
+    def __xor__(self, other):
+        return Empty
+
+    def __rxor__(self, other):
+        return Empty
+
+    def __hash__(self):
+        return object.__hash__(self)
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        raise StopIteration()
+
+
+Empty = _Empty()
+
+
+class EmptyDict(collections.defaultdict):
+    def __init__(self, *args, **kwargs):
+        """A defaultdict who's default values are an Empty and that can be
+        accessed via attributes as well as normal dict methods.
+
+        Useful for wrapping around nested dicts who's keys you can't be sure of
+        and when you don't want to have to code too defensively.
+        """
+        super(EmptyDict, self).__init__(lambda x: Empty, *args, **kwargs)
+
+    def __getattribute__(self, name):
+        if hasattr(collections.defaultdict, name):
+            return collections.defaultdict.__getattribute__(self, name)
+        if collections.defaultdict.__contains__(self, name):
+            data = collections.defaultdict.__getitem__(self, name)
+            if isinstance(data, dict):
+                return EmptyDict(**data)
+            elif data is None:
+                return Empty
+            else:
+                return data
+        return Empty
+
+    def __getitem__(self, item):
+        if collections.defaultdict.__contains__(self, item):
+            data = collections.defaultdict.__getitem__(self, item)
+            if isinstance(data, dict):
+                return EmptyDict(**data)
+            elif data is None:
+                return Empty
+            else:
+                return data
+        return Empty
+
+    def __missing__(self, key):
+        return Empty
+
+    def __repr__(self):
+        return dict.__repr__(self)
+
+
+def if_empty(value, return_if_empty=None):
+    """Returns the value of the `return_if_empty` parameter (`None` by default)
+    if the given `value` parameter is either an `Empty`.
+
+    The point of this is to quickly default some value that may be an Empty OR
+    some other value that evaluates as False into the correct type (e.g. before
+    passing a possible `Empty` on to code that may bug out with an `Empty` but
+    expect something like a `None` or a 0 or an empty string) without bothering
+    with more cumbersome type checks.
+
+    This can usually be done with a simple `or` fallback like so:
+
+        >>> bar = Empty
+        >>> foo = bar or None
+        >>> assert foo is None  # GOOD: We wanted a None by default
+
+    This ensures that if `bar` is an `Empty`, `foo` will be a
+    `None` by default, however, if the expected real value of `bar` can be
+    something that evaluates to `False` in an `or` check (eg. `None`, `False`,
+    `0`, `0.0`, `""`, etc. this check will also always overwrite such real
+    values with a `None`:
+
+        >>> bar = 0
+        >>> foo = if_empty(bar, None)
+        >>> assert foo is None  # GOOD
+
+    So we can guard agains this while skipping overly complex checks (that would
+    negated the utility of the `Empty` stuff) like so:
+
+        >>> bar = Empty
+        >>> foo = if_empty(bar, None)
+        >>> assert foo is None  # GOOD: Default None if no value is set
+        >>> bar = 0
+        >>> foo = if_empty(bar, None)
+        >>> assert foo == 0  # GOOD: Value of 0 is cool
+
+    :param value: Value to check if is an `Empty`
+    :type value: Any
+    :param return_if_empty: Value to return (as default) if the `value` is empty
+    :type return_if_empty: Any
+    :return: The `return_if_empty` param if `value` is an `Empty`, otherwise,
+             the `value` unchanged
+    :rtype: Any
+    """
+    if value is Empty:
+        return return_if_empty
+    return value

batutils/tpu/structs/enumex/__init__.py

@@ -0,0 +1 @@
+from ._enumextra import *

batutils/tpu/structs/enumex/_enumextra.py

@@ -0,0 +1,25 @@
+__all__ = [
+    'EnumEx',
+]
+
+import enum
+from typing import *
+
+_T_ENUM = TypeVar('_T_ENUM', bound='EnumEx')
+
+_NOT_SUPPLIED = object()
+
+
+class EnumEx(enum.Enum):
+    @classmethod
+    def from_any(cls: Type[_T_ENUM], value: Any,
+                 default: Union[_T_ENUM, None] = _NOT_SUPPLIED) -> _T_ENUM:
+        """Casts any sensible value to an Enum of this type.
+
+        :param value: The value to cast to an Enum
+        :param default: Default value to return on failed eval if any. Defaults
+                        to _NOT_SUPPLIED and makes this method raise an
+                        exception on failure
+        """
+        from batutils.tpu.casting import enum_eval
+        return enum_eval(value, cls, default=default, raise_on_fail=(default is _NOT_SUPPLIED))

batutils/tpu/structs/fluid/__init__.py

@@ -0,0 +1 @@
+from ._attrfluid import *

batutils/tpu/structs/fluid/_attrfluid.py

@@ -0,0 +1,77 @@
+__all__ = [
+    'AttributeFluidObject',
+]
+
+import logging
+_default_log = logging.getLogger(__name__)
+
+
+class AttributeFluidObject(object):
+    _log_missing_attributes = False
+    _log_level = logging.WARNING
+    _logger = _default_log
+    _default_value = None
+
+    def __new__(cls, *args, **kwargs):
+        # This makes sure we don't log anything set in the __init__ methods
+        # as missing until AFTER calling AttributeFluidObject's super init.
+        instance = super(AttributeFluidObject, cls).__new__(cls)
+
+        object.__setattr__(instance, '_log_missing_attributes', False)
+        return instance
+
+    def __init__(self, **kwargs):
+        """Base class for "Attribute-Fluid" object, i.e. objects that
+        self-correct instead of raising an attribute error when an attribute
+        called is missing (whether it's set or get), i.e. create within itself
+        any missing attribute on the fly.
+
+        Useful for making error tolerant objects, e.g. when external resources
+        (that aren't guaranteed to be stable) are used to act on the object. A
+        good example would be a Class that read configuration values from a
+        file where you don't want the code to break even if the file has borked
+        values.
+
+        The class has three class variables that determine how to handle
+        missing attributes specifically:
+
+            - _log_missing_attributes: If True, the object will log any missing
+              attribute call (for the first time). This will be logged to the
+              tpu.bases logger. Default is False.
+            - _logger: The logger to log to (if _log_missing_attributes is
+              True). Default is the 'tpu.bases'.
+            - _log_level: The log level to log missing attributes as (if
+              _log_missing_attributes is True). Default is logging.WARNING.
+            - _default_value: The default value to give to missing attributes
+              created. Default is None.
+
+        IMPORTANT: If logging missing attributes, make sure you call:
+        `super(self.__class__, self).__init__(**kwargs)` in your classes
+        `__init__` method AFTER setting all expected attributes (generally at
+        the bottom of the __init__ method). Otherwise missing attributes will
+        not get logged AND is you call the super's __init__ before initializing
+        all self.whatever attributes, those attributes in the init that you set
+        after calling the super will get logged as missing, which is both
+        incorrect and annoying :).
+
+        :param kwargs: Any keywords that will be set as attributes of the
+                       object.
+        :type kwargs: dict[any,any]
+        """
+        object.__setattr__(self, '_log_missing_attributes', self.__class__._log_missing_attributes)
+        if kwargs:
+            for k, v in kwargs.items():
+                if not k.startswith('_'):
+                    setattr(self, k, v)
+
+    def __getattr__(self, item):
+        if self._log_missing_attributes:
+            self._logger.log(self._log_level, u'Attribute "%s" of Class "%s" does not exist! Setting it to default value=%r', item, self.__class__.__name__, self._default_value)
+        object.__setattr__(self, item, self._default_value)
+        return self._default_value
+
+    def __setattr__(self, name, value):
+        if self._log_missing_attributes:
+            if not hasattr(self, name):
+                self._logger.log(self._log_level, u'Attribute "%s" of Class "%s" does not exist but is now set to %r!', name, self.__class__.__name__, value)
+        object.__setattr__(self, name, value)

batutils/tpu/structs/sentience/__init__.py

@@ -0,0 +1 @@
+from ._builder import *