Pyjoyment 0.1.0__py3-none-any.whl

Pyjo/Asset/__init__.py

@@ -0,0 +1,200 @@
+"""
+Pyjo.Asset - HTTP content storage base class
+============================================
+::
+
+    from Pyjo.Asset import Asset
+
+    class MyAsset(Asset):
+        def add_chunk(self, chunk): ...
+        def contains(self, string): ...
+        def get_chunk(self, offset, max=None): ...
+        def move_to(self, to): ...
+        @property
+        def mtime(self): ...
+        @property
+        def size(self): ...
+        def slurp(self): ...
+        def to_file(self): ...
+
+    # Or import the module, as in Google Python Style Guide
+
+    import Pyjo.Asset
+
+    class MyAsset(Pyjo.Asset.object):
+        def add_chunk(self, chunk): ...
+        def contains(self, string): ...
+        def get_chunk(self, offset, max=None): ...
+        def move_to(self, to): ...
+        @property
+        def mtime(self): ...
+        @property
+        def size(self): ...
+        def slurp(self): ...
+        def to_file(self): ...
+
+:mod:`Pyjo.Asset` is an abstract base class for HTTP content storage
+backends, like :mod:`Pyjo.Asset.File` and :mod:`Pyjo.Asset.Memory`.
+
+Events
+------
+
+:mod:`Pyjo.Asset` inherits all events from :mod:`Pyjo.EventEmitter`.
+
+See also
+--------
+
+:mod:`Pyjoyment`, https://mojolicious.org.
+
+Ported from `Mojo::Asset <https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojo/Asset.pm>`_
+of Mojolicious 9.49.
+"""
+
+import Pyjo.EventEmitter
+
+import builtins
+
+from typing import Self
+
+
+type Anything = builtins.object
+
+
+class Pyjo_Asset(Pyjo.EventEmitter.object):
+    """
+    :mod:`Pyjo.Asset` inherits all methods from :mod:`Pyjo.EventEmitter` and
+    implements the following new ones.
+    """
+
+    def __init__(self, *, end_range: int | None = None, start_range: int = 0) -> None:
+        """::
+
+            asset = Pyjo.Asset.new()
+            asset = Pyjo.Asset.new(start_range=3, end_range=8)
+
+        Construct a new :mod:`Pyjo.Asset` object.
+        """
+        super().__init__()
+
+        self.end_range = end_range
+        """::
+
+            end = asset.end_range
+            asset.end_range = 8
+
+        Pretend file ends earlier.
+        """
+
+        self.start_range = start_range
+        """::
+
+            start = asset.start_range
+            asset.start_range = 3
+
+        Pretend file starts later.
+        """
+
+    def add_chunk(self, chunk: bytes) -> 'Pyjo_Asset':
+        """::
+
+            asset = asset.add_chunk(b'foo bar baz')
+
+        Add chunk of data to asset. Meant to be overloaded in a subclass.
+        """
+        raise NotImplementedError('Method "add_chunk" not implemented by subclass')
+
+    def contains(self, string: bytes) -> int:
+        """::
+
+            position = asset.contains(b'bar')
+
+        Check if asset contains a specific string. Meant to be overloaded in a
+        subclass.
+        """
+        raise NotImplementedError('Method "contains" not implemented by subclass')
+
+    def get_chunk(self, offset: int, max: int | None = None) -> bytes:
+        """::
+
+            chunk = asset.get_chunk(offset)
+            chunk = asset.get_chunk(offset, max)
+
+        Get chunk of data starting from a specific position, defaults to a
+        maximum chunk size of ``131072`` bytes (128KiB). Meant to be overloaded
+        in a subclass.
+        """
+        raise NotImplementedError('Method "get_chunk" not implemented by subclass')
+
+    @property
+    def is_file(self) -> bool:
+        """::
+
+            boolean = asset.is_file
+
+        False, this is not a :mod:`Pyjo.Asset.File` object.
+        """
+        return False
+
+    @property
+    def is_range(self) -> bool:
+        """::
+
+            boolean = asset.is_range
+
+        Check if asset has a :attr:`start_range` or :attr:`end_range`.
+        """
+        return bool(self.end_range or self.start_range)
+
+    def move_to(self, to: Anything) -> Self:
+        """::
+
+            asset = asset.move_to('/home/sri/foo.txt')
+
+        Move asset data into a specific file. Meant to be overloaded in a
+        subclass.
+        """
+        raise NotImplementedError('Method "move_to" not implemented by subclass')
+
+    @property
+    def mtime(self) -> float:
+        """::
+
+            mtime = asset.mtime
+
+        Modification time of asset. Meant to be overloaded in a subclass.
+        """
+        raise NotImplementedError('Method "mtime" not implemented by subclass')
+
+    @property
+    def size(self) -> int:
+        """::
+
+            size = asset.size
+
+        Size of asset data in bytes. Meant to be overloaded in a subclass.
+        """
+        raise NotImplementedError('Method "size" not implemented by subclass')
+
+    def slurp(self) -> bytes:
+        """::
+
+            content = asset.slurp()
+
+        Read all asset data at once. Meant to be overloaded in a subclass.
+        """
+        raise NotImplementedError('Method "slurp" not implemented by subclass')
+
+    def to_file(self) -> 'Pyjo_Asset':
+        """::
+
+            file = asset.to_file()
+
+        Convert asset to :mod:`Pyjo.Asset.File` object. Meant to be overloaded
+        in a subclass.
+        """
+        raise NotImplementedError('Method "to_file" not implemented by subclass')
+
+
+new = Pyjo_Asset.new
+object = Pyjo_Asset
+Asset = Pyjo_Asset

Pyjo/Base.py

@@ -0,0 +1,215 @@
+r"""
+Pyjo.Base - Minimal base class for Pyjo projects
+================================================
+::
+
+    from Pyjo.Base import Base
+
+    from dataclasses import dataclass
+
+    @dataclass
+    class Cat(Base):
+        name: str = 'Nyan'
+        age: int = 4
+
+    mew = Cat(name='Longcat')
+    print(mew.age)
+
+    # Or import the module, as in Google Python Style Guide
+
+    import Pyjo.Base
+
+    from dataclasses import dataclass, field
+
+    @dataclass
+    class Cat(Pyjo.Base.object):
+        name: str = 'Nyan'
+        age: int = 4
+        weight: int = 4
+
+    @dataclass
+    class Tiger(Cat):
+        friend: Cat = field(default_factory=Cat)
+        stripes: int = 42
+
+    mew = Cat.new(name='Longcat')
+    print(mew.age)
+    print(mew.set(age=3, weight=5).age)
+
+    rawr = Tiger.new(stripes=38, weight=250)
+    print(rawr.tap(lambda rawr: rawr.friend.set(name='Tacgnol')).weight)
+
+:mod:`Pyjo.Base` is a simple base class for :mod:`Pyjo` projects with fluent
+interfaces.
+
+The attributes of an object are the attributes of Python. A dataclass, as
+above, or ``__init__`` gives them their default values, and a property builds
+a default value the first time it is read, as a callback of ``has`` does in
+Mojolicious. ::
+
+    class Lion(Cat):
+        @property
+        def pride(self):
+            if not hasattr(self, '_pride'):
+                self._pride = [Cat.new(), Cat.new()]
+            return self._pride
+
+Constructors
+------------
+
+The constructor of a class and :meth:`~Pyjo_Base.new` make the same object, and
+both are correct. :meth:`~Pyjo_Base.new` is the constructor of Mojolicious,
+which the documentation uses, after ``import`` of the module. Each module has
+its class under the name of the module too, as ``Path`` of :mod:`Pyjo.Path`,
+for the constructor of Python, after ``from ... import`` of the class. ::
+
+    import Pyjo.Path
+
+    path = Pyjo.Path.new('/foo/bar')
+
+    # Or import the class
+
+    from Pyjo.Path import Path
+
+    path = Path('/foo/bar')
+
+The synopsis of each module shows its first example in both forms.
+
+Fluent interfaces
+-----------------
+
+Fluent interfaces are a way to design object-oriented APIs around method
+chaining to create domain-specific languages, with the goal of making the
+readability of the source code close to written prose. ::
+
+    @dataclass
+    class Duck(Pyjo.Base.object):
+        name: str | None = None
+
+        def quack(self):
+            print(f'{self.name}: Quack!')
+
+:mod:`Pyjo.Base` will help you with this by having :meth:`~Pyjo_Base.set`
+return its invocant (``self``) when it is used to assign new attribute values. ::
+
+    Duck.new().set(name='Donald').quack()
+
+In this case :meth:`~Pyjo_Base.set` is called on the object created by
+``Duck.new()``. It assigns a new attribute value and then returns the ``Duck``
+object, so the ``quack`` method can be called on it afterwards. These method
+chains can continue until one of the methods called does not return the
+``Duck`` object.
+
+See also
+--------
+
+:mod:`Pyjoyment`, https://mojolicious.org.
+
+Ported from `Mojo::Base <https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojo/Base.pm>`_
+of Mojolicious 9.49.
+
+Classes
+-------
+"""
+
+from collections.abc import Callable
+from typing import Any, Self
+
+
+# Left out from Mojolicious: the flags of import, -strict, -base, -role, -signatures and -async_await, as Python has
+# them on its own, and has, as the attributes of Python take its place
+
+
+class Pyjo_Base:
+    """
+    :mod:`Pyjo.Base` implements the following methods.
+    """
+
+    # Not in Mojolicious: no __dict__ of its own, so that a subclass with __slots__ has none either
+    __slots__ = ()
+
+    # Left out from Mojolicious: attr, as the attributes of Python, the properties and weakref.proxy take its place
+
+    @classmethod
+    def new(cls, *args: Any, **kwargs: Any) -> Self:
+        """::
+
+            obj = SubClass.new()
+            obj = SubClass.new(name='value')
+            obj = SubClass.new(**{'name': 'value'})
+
+        This base class provides a basic constructor, which passes its
+        arguments to the constructor of the class: the attribute values are
+        keyword arguments.
+        """
+        return cls(*args, **kwargs)
+
+    # Not in Mojolicious: the expression form of an assignment, as the accessors of Mojo chain when they set a value
+    def set(self, **kwargs: Any) -> Self:
+        """::
+
+            obj = obj.set(name='value')
+            obj = obj.set(name='value', other='value')
+
+        Assign attribute values and return the object, so that a chain of
+        method calls can continue. ::
+
+            # Longer version
+            obj.name = 'value'
+        """
+        for k, v in sorted(kwargs.items()):
+            setattr(self, k, v)
+        return self
+
+    def tap(self, cb: Callable[..., Any] | str, *args: Any, **kwargs: Any) -> Self:
+        """::
+
+            obj = obj.tap(lambda obj: ...)
+            obj = obj.tap('some_method')
+            obj = obj.tap('some_method', *args, **kwargs)
+
+        Tap into a method chain to perform operations on an object within the
+        chain (also known as a K combinator or Kestrel). The object will be
+        the first argument passed to the callback. The callback's return value
+        will be ignored; instead, the object (the callback's first argument)
+        will be the return value. In this way, arbitrary code can be used
+        within (i.e., spliced or tapped into) a chained set of object method
+        calls. A name of an attribute that is not a method is read, which
+        builds the default value of a property. ::
+
+            # Longer version
+            obj = obj.tap(lambda obj: obj.some_method(*args))
+
+            # Inject side effects into a method chain
+            obj.set(foo='A').tap(lambda obj: print(obj.foo)).set(foo='B')
+        """
+        tap(self, cb, *args, **kwargs)
+        return self
+
+    # Left out from Mojolicious: with_roles, as Pyjoyment has no roles
+
+
+# Not in Mojolicious: a function of its own, for the classes that are not Pyjo.Base, as a list and a string
+def tap(obj: Any, cb: Callable[..., Any] | str, *args: Any, **kwargs: Any) -> None:
+    """::
+
+        tap(obj, lambda obj: ...)
+        tap(obj, 'some_method', *args, **kwargs)
+
+    Call the callback with the object, or its method of the name with the
+    arguments, or read its attribute of the name, as :meth:`Pyjo_Base.tap` and
+    the ``tap`` of the classes that are not :mod:`Pyjo.Base` do.
+    """
+    if callable(cb):
+        cb(obj, *args, **kwargs)
+        return
+    value = getattr(obj, cb)
+    if callable(value):
+        value(*args, **kwargs)
+    elif args or kwargs:
+        raise TypeError(f'{cb!r} of {type(obj).__name__} is not callable')
+
+
+new = Pyjo_Base.new
+object = Pyjo_Base
+Base = Pyjo_Base

Pyjo/Cache.py

@@ -0,0 +1,119 @@
+"""
+Pyjo.Cache - Naive in-memory cache
+==================================
+::
+
+    from Pyjo.Cache import Cache
+
+    cache = Cache(max_keys=50)
+    cache.set('foo', 'bar')
+    foo = cache.get('foo')
+
+    # Or import the module, as in Google Python Style Guide
+
+    import Pyjo.Cache
+
+    cache = Pyjo.Cache.new(max_keys=50)
+    cache.set('foo', 'bar')
+    foo = cache.get('foo')
+
+:mod:`Pyjo.Cache` is a naive in-memory cache with size limits.
+
+See also
+--------
+
+:mod:`Pyjoyment`, https://mojolicious.org.
+
+Ported from `Mojo::Cache <https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojo/Cache.pm>`_
+of Mojolicious 9.49.
+"""
+
+import Pyjo.Base
+
+import builtins
+
+from collections.abc import Hashable
+from typing import Self
+
+
+type Anything = builtins.object
+
+
+class Pyjo_Cache[K: Hashable, V](Pyjo.Base.object):
+    """
+    :mod:`Pyjo.Cache` inherits all methods from :mod:`Pyjo.Base` and
+    implements the following new ones.
+    """
+
+    def __init__(self, max_keys: int = 100) -> None:
+        """::
+
+            cache = Pyjo.Cache.new()
+            cache = Pyjo.Cache.new(max_keys=50)
+
+        Construct a new :mod:`Pyjo.Cache` object.
+        """
+        self.max_keys = max_keys
+        """::
+
+            max = cache.max_keys
+            cache.max_keys = 50
+
+        Maximum number of cache keys, defaults to ``100``. Setting the value to
+        ``0`` will disable caching.
+        """
+
+        # The order of the keys of a dict is the queue of Mojo
+        self._cache: dict[K, V] = {}
+
+    # Not in Mojolicious: the protocol of a container
+    def __contains__(self, key: Anything) -> bool:
+        """::
+
+            boolean = 'foo' in cache
+
+        Check if a value is cached.
+        """
+        return key in self._cache
+
+    # Not in Mojolicious: the protocol of a container
+    def __len__(self) -> int:
+        """::
+
+            count = len(cache)
+
+        Number of cached values.
+        """
+        return len(self._cache)
+
+    def get(self, key: K) -> V | None:
+        """::
+
+            value = cache.get('foo')
+
+        Get cached value.
+        """
+        return self._cache.get(key)
+
+    # The set() of Pyjo.Base sets attributes, the set() of Mojo caches a value
+    def set(self, key: K, value: V) -> Self:  # pyright: ignore[reportIncompatibleMethodOverride]
+        """::
+
+            cache = cache.set('foo', 'bar')
+
+        Set cached value.
+        """
+        if (max := self.max_keys) <= 0:
+            return self
+
+        cache = self._cache
+        while len(cache) >= max:
+            del cache[next(iter(cache))]
+        cache[key] = value
+
+        return self
+
+
+new = Pyjo_Cache.new
+object = Pyjo_Cache
+Cache = Pyjo_Cache