batutils 2.0.0__py3-none-any.whl

batutils/tpu/structs/sentience/_builder.py

@@ -0,0 +1,87 @@
+__all__ = [
+    'SentientObject',
+]
+
+
+class _SentientClassBuilder(type):
+    """This is a sneaky Python black magic way to be able to collect certain
+    methods of classes and add some meta data to the via decorated during the
+    classes initialization.
+    """
+    def __new__(mcs, clsname, bases, dct):
+        the_class = super(_SentientClassBuilder, mcs).__new__(mcs, clsname, bases, dct)
+        my_map = {}
+        for name, attr in dct.items():
+            if hasattr(attr, '__call__'):
+                sentience = getattr(attr, '__sentience__', None)
+                if sentience is not None and isinstance(sentience, dict):
+                    my_map[name] = sentience
+
+        current_map = getattr(the_class, '__sentient_method_map__', None) or {}
+        current_map[clsname] = my_map
+        setattr(the_class, '__sentient_method_map__', current_map)
+        return the_class
+
+
+class SentientObject(object, metaclass=_SentientClassBuilder):
+    """Having a class extend this instead of the normal python object allows
+    you to mark some of it's methods via the sentient decorator and give them
+    some meta-data. The names of those methods along with the metadata (using
+    kwargs in the decorator) will be collected during the classes
+    initialization (on first import) and added to the __sentient_method_map__
+    dict. The sentient_methods() class method will return that map as such:
+    {
+        'method_name_1': {
+            'meta_data_1': 'meta_value_1',
+            'meta_data_2': 'meta_value_2'
+        },
+        'method_name_2': {
+            'meta_data_1': 'meta_value_1',
+            'meta_data_2': 'meta_value_2'
+        }
+    } ... etc.
+
+    The point is simply to be able to flag certain methods in code with a
+    simple decorator (as oppose to hardcoding some list) and then retrieve
+    that list for whatever reason e.g. quickly and simply "exposing" (or
+    advertising really) some methods to other code systematically (i.e.
+    instant automatic API).
+
+
+    """
+    __sentient_method_map__ = {}
+
+    @classmethod
+    def sentient_methods(cls, inherited=True):
+        """Returns the map of "sentient" methods and their meta data.
+
+        :return: A dict with "sentient" method names as keys and a dict of
+        their meta data as value.
+        :rtype: dict
+        """
+        buff = cls.__sentient_method_map__[cls.__name__]
+        if inherited:
+            for basecls in cls.__bases__:
+                if issubclass(basecls, SentientObject):
+                    buff.update(basecls.sentient_methods())
+        return buff
+
+    @staticmethod
+    def sentient(**kwargs):
+        """Adds the given keywords to a new attribute of the decorated
+        function, thus marking it for the SentientClassBuilder and storing
+        the meta data.
+
+        This triggers the SentientClassBuilder to add the method's name and
+        meta data to the __sentient_method_map__ when the class (not object)
+        is created.
+
+        :param kwargs: The meta data to store
+        :type kwargs: dict
+        :return: The original function with the meta data added to it
+        :rtype: function
+        """
+        def inner(function):
+            setattr(function, '__sentience__', kwargs)
+            return function
+        return inner

batutils/tpu/structs/serializers/__init__.py

@@ -0,0 +1,3 @@
+from ._universal import *
+from ._jsonsafe import *
+from ._json import *

batutils/tpu/structs/serializers/_json.py

@@ -0,0 +1,12 @@
+__all__ = [
+    'JsonSerializer',
+]
+
+from ._jsonsafe import *
+from typing import *
+import json
+
+
+class JsonSerializer(JsonSafeSerializer):
+    def serialize(self, obj: Any, indent: int = 4, sort_keys: bool = True) -> str:
+        return json.dumps(super().serialize(obj), indent=indent, sort_keys=sort_keys)

batutils/tpu/structs/serializers/_jsonsafe.py

@@ -0,0 +1,69 @@
+__all__ = [
+    'JsonSafeSerializer',
+]
+
+from ._universal import *
+from batutils._common._decode import decode_bytes
+
+
+class JsonSafeSerializer(UniversalSerializer):
+    """
+    A version of the UniversalSerializer that serializes types from the datetime
+    and decimal modules into JSON safe types.
+    """
+
+    def _serialize_maps(self, obj):
+        """We need to ensure that all keys are strings, otherwise "sort_keys" in json dumping will fail.
+        """
+        d = {}
+        for k, v in obj.items():
+            k = str(k)  # Keys need to be strings in JSON
+            if k in self.skip_keys or v in self.skip_values:
+                continue
+            if self.skip_private and k.startswith('_'):
+                continue
+            if self.skip_nones and v is None:
+                continue
+            val = self._serialize_any(v)
+            if self.skip_empties and isinstance(val, self._emptyables) and not val:
+                continue
+            d[k] = val
+        return d
+
+    def _serialize_bytes(self, obj):
+        return decode_bytes(obj)
+
+    def _serialize_decimal(self, obj):
+        """
+        :type obj: decimal.Decimal
+        :rtype: str
+        """
+        return '%s' % obj.normalize()
+
+    def _serialize_datetime(self, obj):
+        """
+        :type obj: datetime.date
+        :rtype: str
+        """
+        return obj.isoformat()
+
+    def _serialize_time(self, obj):
+        """
+        :type obj: datetime.time
+        :rtype: str
+        """
+        return obj.isoformat()
+
+    def _serialize_date(self, obj):
+        """
+        :type obj: datetime.date
+        :rtype: str
+        """
+        return obj.isoformat()
+
+    def _serialize_timedelta(self, obj):
+        """
+        :type obj: datetime.timedelta
+        :rtype: float
+        """
+        return obj.total_seconds()

batutils/tpu/structs/serializers/_universal.py

@@ -0,0 +1,318 @@
+__all__ = [
+    'UniversalSerializer',
+]
+
+from batutils.tpu.structs._base import *
+
+
+class UniversalSerializer(object):
+    _emptyables = (list, tuple, set, dict, str, bytes)
+
+    def __init__(self, skip_keys=None, skip_values=None, skip_private=True, skip_nones=False, skip_empties=False,
+                 max_depth=0):
+        """Serializes any python object or type recursively.
+
+        What this means in practical terms is that anything this function is given
+        will be guaranteed to be of and/or only contain the following python types:
+            - int
+            - float
+            - str
+            - bytes
+            - decimal.Decimal
+            - datetime.date
+            - datetime.datetime
+            - datetime.time
+            - datetime.timedelta
+            - None
+            - list
+            - tuple
+            - set
+            - dict
+
+        The main purpose/use-case for this is to take any arbitrary classes and/or
+        data structures (e.g. from various third party APIs) and turn them into
+        simple/common python primary types for safer manipulation and/or use.
+
+        This minimizes the amount of "defensive" coding needed to handle external
+        return values who's structures are wholly or partially unknown or might
+        change without notice. Turning an object into a discrete set of types means
+        that checking for attributes and values becomes easier and less likely to
+        raise annoying exceptions that need handling like AttributeError,
+        ValueError, KeyError and such.
+
+        An example would be turning an object into a dict to ensure that calling
+        obj.get('is_foo', False) simply yields True or False without any additional
+        safety measures or exception handling and such.
+
+        Another example would be to turn an object into a dict guaranteed to have
+        all it's properties and recursive structures for dumping out in logs or
+        encoding into other formats like JSON (although you'd have to handle the
+        serialization of values from the datetime and decimal modules specially for
+        that).
+
+        These python types are returned as-is:
+            - int
+            - float
+            - str
+            - bytes
+            - decimal.Decimal
+            - datetime.date
+            - datetime.datetime
+            - datetime.time
+            - datetime.timedelta
+            - None
+
+        These types are returned back (as either lists or dicts) after recursively
+        serializing their values and/or properties:
+            - list
+            - tuple
+            - set
+            - dict
+
+        Any other type (e.g. anything inheriting from object) that has a __dict__
+        property will be serialized recursively to a dict by using their __dict__.
+
+        Other types without a __dict__ property will yield the string:
+            - '__WHAT__::%s' % type(obj)
+
+        Reference loops will be serialized as the string
+            - '__LOOP__::%s::%s' % (type(obj), id(obj))
+
+
+        :param skip_keys: List of key names to skip from dict and object.__dict__
+                          serialization
+        :type skip_keys: list | tuple | set
+        :param skip_values: List of values to skip from dict and object.__dict__
+                            serialization
+        :type skip_values: list | tuple | set
+        :param skip_private: Should private keys (i.e. who's name starts with an
+                             underscore) be skipped? Default is True.
+        :type skip_private: bool
+        :param skip_nones: Should values of None be skipped from dict and
+                           object.__dict__ serialization? Default is False.
+        :type skip_nones: bool
+        :param skip_empties: Should empty lists, tuples, sets, dicts, strings and
+                             bytes be skipped from dict and object.__dict__
+                             serialization? Default is False.
+        :type skip_empties: bool
+        :param max_depth: Maximum recursion depth (Default is 0 for infinite)
+        :type max_depth: int
+
+        """
+        self.skip_keys = list(skip_keys or [])
+        self.skip_values = list(skip_values or [])
+
+        self.skip_private = skip_private
+        self.skip_nones = skip_nones
+        self.skip_empties = skip_empties
+        self.max_depth = max_depth
+
+        self._breadcrumbs = []
+
+        self.serialize_map = {
+            int: self._serialize_int,
+            float: self._serialize_float,
+            str: self._serialize_str,
+            bytes: self._serialize_bytes,
+
+            Decimal: self._serialize_decimal,
+
+            datetime.time: self._serialize_time,
+            datetime.date: self._serialize_date,
+            datetime.datetime: self._serialize_datetime,
+            datetime.timedelta: self._serialize_timedelta,
+
+            list: self._serialize_list,
+            tuple: self._serialize_tuple,
+            set: self._serialize_set,
+            dict: self._serialize_dict,
+        }
+
+    def serialize(self, obj):
+        self._breadcrumbs = []  # Just in case!
+        return self._serialize_any(obj)
+
+    def _serialize_any(self, obj):
+        try:
+            if obj in self._breadcrumbs:
+                return self._serialize_loop(obj)
+
+            if obj is None:
+                return self._serialize_none(obj)
+
+            if self.max_depth and len(self._breadcrumbs) > self.max_depth:
+                return self._serialize_max_depth(obj)
+
+            t = type(obj)
+            serializer = self.serialize_map.get(t, self._serialize_other)
+            if serializer:
+                self._breadcrumbs.append(obj)
+                value = serializer(obj)
+                self._breadcrumbs.pop()
+                return value
+
+        except Exception as ex:
+            return self._serialize_error(obj, '%s' % ex)
+
+        return None
+
+    def _serialize_int(self, obj):
+        """
+        :type obj: int
+        :rtype: int
+        """
+        return obj
+
+    def _serialize_float(self, obj):
+        """
+        :type obj: float
+        :rtype: float
+        """
+        return obj
+
+    def _serialize_str(self, obj):
+        """
+        :type obj: str
+        :rtype: str
+        """
+        return obj
+
+    def _serialize_bytes(self, obj):
+        """
+        :type obj: bytes
+        :rtype: bytes
+        """
+        return obj
+
+    def _serialize_decimal(self, obj):
+        """
+        :type obj: decimal.Decimal
+        :rtype: decimal.Decimal
+        """
+        return obj
+
+    def _serialize_datetime(self, obj):
+        """
+        :type obj: datetime.datetime
+        :rtype: datetime.datetime
+        """
+        return obj
+
+    def _serialize_time(self, obj):
+        """
+        :type obj: datetime.time
+        :rtype: datetime.time
+        """
+        return obj
+
+    def _serialize_date(self, obj):
+        """
+        :type obj: datetime.date
+        :rtype: datetime.date
+        """
+        return obj
+
+    def _serialize_timedelta(self, obj):
+        """
+        :type obj: datetime.timedelta
+        :rtype: datetime.timedelta
+        """
+        return obj
+
+    def _serialize_list(self, obj):
+        """
+        :type obj: list
+        :rtype: list
+        """
+        return self._serialize_iters(obj)
+
+    def _serialize_tuple(self, obj):
+        """
+        :type obj: tuple
+        :rtype: list
+        """
+        return self._serialize_iters(obj)
+
+    def _serialize_set(self, obj):
+        """
+        :type obj: set
+        :rtype: list
+        """
+        return self._serialize_iters(obj)
+
+    def _serialize_iters(self, obj):
+        """
+        :type obj: list | tuple | set
+        :rtype: list
+        """
+        return [self._serialize_any(i) for i in obj]
+
+    def _serialize_maps(self, obj):
+        """
+        :type obj: dict
+        :rtype: dict
+        """
+        d = {}
+        for k, v in obj.items():
+            if k in self.skip_keys or v in self.skip_values:
+                continue
+            if self.skip_private and isinstance(k, str) and k.startswith('_'):
+                continue
+            if self.skip_nones and v is None:
+                continue
+            val = self._serialize_any(v)
+            if self.skip_empties and isinstance(val, self._emptyables) and not val:
+                continue
+            d[k] = val
+        return d
+
+    def _serialize_dict(self, obj):
+        """
+        :type obj: dict
+        :rtype: dict
+        """
+        return self._serialize_maps(obj)
+
+    def _serialize_object(self, obj):
+        """
+        :type obj: object
+        :rtype: dict
+        """
+        return self._serialize_maps(obj.__dict__)
+
+    def _serialize_other(self, obj):
+
+        # OVERRIDE CUSTOM SERIALIZING HERE!
+
+        # If no special serializers are found, just serialize the __dict__ of an object!
+        if hasattr(obj, '__dict__'):
+            return self._serialize_object(obj)
+        return self._serialize_derived(obj)
+
+    def _serialize_none(self, obj):
+        """
+        :type obj: None
+        :rtype: None
+        """
+        return None
+
+    def _serialize_loop(self, obj):
+        return '__LOOP__::%s::%s' % (type(obj), id(obj))
+
+    def _serialize_derived(self, obj):
+        for t, func in self.serialize_map.items():
+            # Check if the object extends any of our known types and use that
+            if isinstance(obj, t):
+                return func(obj)
+
+        # If all else fails, return unknown serialization
+        return self._serialize_unknown(obj)
+
+    def _serialize_error(self, obj, error):
+        return '__ERROR__::%s::%s' % (type(obj), error)
+
+    def _serialize_unknown(self, obj):
+        return '__UNKNOWN__::%s' % type(obj)
+
+    def _serialize_max_depth(self, obj):
+        return '__MAX_DEPTH__::%s::%s' % (type(obj), id(obj))

batutils/tpu/structs/singleton/__init__.py

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

batutils/tpu/structs/singleton/_singleton.py

@@ -0,0 +1,35 @@
+__all__ = [
+    'Singleton',
+]
+
+from threading import Lock
+
+
+class Singleton(type):
+    """
+    Use:
+    from tpu import singleton
+
+    class MyClass(BaseClass, metaclass=singleton.Singleton):
+        ...
+
+    """
+    __instances = {'lock': Lock()}
+
+    def __call__(cls, *args, **kwargs):
+        with cls.__instances['lock']:
+            if cls not in cls.__instances:
+                cls.__instances[cls] = super(Singleton, cls).__call__(*args, **kwargs)
+                setattr(cls.__instances[cls], '_singleton_reload', Singleton.wrapper(cls))
+            return cls.__instances[cls]
+
+    @staticmethod
+    def wrapper(cls):
+        def _singleton_reload():
+            try:
+                with cls.__instances['lock']:
+                    del cls.__instances[cls]
+            except KeyError:
+                pass
+            return cls()
+        return _singleton_reload

batutils-2.0.0.dist-info/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Thordur Matthiasson
+Copyright (c) 2013-2024 CCP Games
+
+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.

batutils-2.0.0.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.1
+Name: batutils
+Version: 2.0.0
+Summary: Team Batcave's utilities for date and/or time objects and values and messing with types and so much more.
+Author-email: Thordur Matthiasson <doddi79@gmail.com>, John Aldis <johnaldis@ccpgames.com>
+License: MIT License
+        
+        Copyright (c) 2024 Thordur Matthiasson
+        Copyright (c) 2013-2024 CCP Games
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/doddi79/batutils
+Project-URL: Documentation, https://github.com/doddi79/batutils/blob/main/README.md
+Project-URL: Repository, https://github.com/doddi79/batutils.git
+Project-URL: Issues, https://github.com/doddi79/batutils/issues
+Project-URL: Changelog, https://github.com/doddi79/batutils/blob/main/CHANGELOG.md
+Keywords: datetimeutils,datetime,typeutils,type,singleton,date,time,timespan,tools,batcave,utils
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# Team Batcave Python Toolkit
+
+The `batutils` is a fork of the `batutils` package in order to continue its 
+development and maintenance beyond Team Batcave's lifespan.  
+
+It is a smooshup of a few Python packages from the CCP Tools Team of old (Team 
+Batcave).
+
+Our two most commonly used internal packages, called `datetimeutils` and 
+`typeutils` were too _generically_ named for Pypi.org and since they were 
+both used in something like 80-90% of our other projects, it made sense to 
+just smoosh them together in one module, and thus, the `batutils` package 
+was born.
+
+Here's the README of the [Date Time Utils](batutils/dtu/README.md) submodule.
+
+Here's the README of the [Type Utils](batutils/tpu/README.md) submodule.
+
+
+### Changes from `ccptools`
+
+The `legacyapi` submodule has been removed.
+
+
+## Date-Time Utils
+
+The old `datetimeutils` package is now included here as the `dtu` submodule.
+
+```python
+from batutils import dtu
+```
+
+## Structs
+
+Importing `*` from the `structs` submodule will import all of the most 
+commonly used imports in our projects:
+```python
+from typing import *  # For type annotation
+
+import abc  # For interfaces (Abstract Base Classes)
+import dataclasses  # For dataclass structs
+import decimal  # Used whenever we're handling money
+import enum  # Also used for struct creation
+import logging  # Used pretty much everywhere
+import re  # Used surprisingly frequently
+import time  # Very commonly used
+```
+
+Note that datetime is not included in this. That's because tt'll also import 
+the aliases from the Datetime Utils (`batutils.dtu.structs.aliases`) 
+package instead:
+
+```python
+Date = datetime.date
+Time = datetime.time
+Datetime = datetime.datetime
+TimeDelta = datetime.timedelta
+TzInfo = datetime.tzinfo
+TimeZone = datetime.timezone
+```
+
+Furthermore, it'll also include a few of the most commonly used utility 
+classes from the Type Utils submodule:
+
+- The `Singleton` Meta Class 
+- The `Empty` and `EmptyDict` classes as well as the `if_empty` method
+- The `EnumEx` base class for Enums with the `from_any` class method
+
+So in most cases we can cover something like 90% of any imports we tend to 
+need in every Python file with a single line:
+
+```python
+from batutils.structs import *
+```