Merge pull request #8 from FasterSpeeding/task/more-docs

More documentation

README.md

@@ -1 +1,16 @@
-hikari-sake
+# Sake
+
+A distributed asynchronous cache interface (plus several implementations) designed for use with Hikari.
+
+# Instillation
+
+You can install Sake from PyPI using the following command.
+
+```
+python -m pip install hikari-sake -U
+```
+
+# Quick Usage.
+
+For usage see the the [documentation](https://fasterspeeding.github.io/Sake/) and
+[examples](https://github.com/FasterSpeeding/Sake/tree/master/examples) .

dev-requirements.txt

@@ -6,5 +6,5 @@ isort==5.6.4
 mock==4.0.2
 
 # Py.test stuff.
-pytest==6.1.1
+pytest==6.1.2
 pytest-asyncio==0.14.0

requirements.txt

@@ -1,2 +1,3 @@
 aioredis==1.3.1
 hikari~=2.0.0.dev93
+hikari-yoyo~=0.0.2

sake/__init__.py

@@ -1,12 +1,55 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# BSD 3-Clause License
+#
+# Copyright (c) 2020, Faster Speeding
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+#
+# * Neither the name of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""A distributed asynchronous cache standard designed to be hikari with Hikari.
+
+For the interfaces defined by this standard see `sake.traits`
+
+For standard implementation(s) see:
+
+* Redis: `sake.redis`
+"""
 from __future__ import annotations
 
 __all__: typing.Final[typing.Sequence[str]] = [
+    # errors.py
+    "errors",
+    "BackendError",
     "CannotDelete",
     "EntryNotFound",
-    "errors",
     "InvalidDataFound",
     "SakeException",
+    # traits.py
     "traits",
+    # redis.py
     "redis",
     "RedisCache",
 ]

sake/about.py

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# BSD 3-Clause License
+#
+# Copyright (c) 2020, Faster Speeding
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+#
+# * Neither the name of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""Package metadata."""
+
+__author__ = "Faster Speeding"
+__ci__ = ""
+__copyright__ = "© 2020 Faster Speeding"
+__coverage__ = ""
+__docs__ = "https://fasterspeeding.github.io/Sake/"
+__email__ = "[email protected]"
+__issue_tracker__ = "https://github.com/FasterSpeeding/Sake/issues"
+__license__ = "BSD"
+__url__ = "https://github.com/FasterSpeeding/Sake"
+__version__ = "0.0.1"
+__git_sha1__ = "HEAD"

sake/errors.py

@@ -1,6 +1,44 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# BSD 3-Clause License
+#
+# Copyright (c) 2020, Faster Speeding
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+#
+# * Neither the name of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""The standard error bases which Sake implementations will be raising.
+
+!!! note
+    These supplement python's builtin exceptions but do not replace them.
+"""
+
 from __future__ import annotations
 
 __all__: typing.Final[typing.Sequence[str]] = [
+    "BackendError",
     "CannotDelete",
     "EntryNotFound",
     "InvalidDataFound",
@@ -11,12 +49,23 @@
 
 
 class SakeException(Exception):
-    """A base exception for the expected exceptions raised by Sake implementations."""
+    """A base exception for the expected exceptions raised by Sake implementations.
+
+    Parameters
+    ----------
+    message : str
+        The exception's message.
+    base : typing.Optional[BaseException]
+        The exception which caused this exception if applicable else `builtins.None`.
+    """
 
     __slots__: typing.Sequence[str] = ("base_exception", "message")
 
     message: str
+    """The exception's message, this may be an empty string if there is no message."""
+
     base: typing.Optional[BaseException]
+    """The exception which caused this exception if applicable else `builtins.None`."""
 
     def __init__(self, message: str, *, exception: typing.Optional[BaseException] = None) -> None:
         self.message = message
@@ -26,13 +75,41 @@ def __repr__(self) -> str:
         return f"{type.__name__}({self.message!r})"
 
 
-class CannotDelete(SakeException, ValueError):
+class BackendError(SakeException, ValueError):
+    """A error raised when communicating with the backend fails
+
+    This may be a sign of underlying network or database issues.
+    """
+
+    __slots__: typing.Sequence[str] = ()
+
+
+class CannotDelete(SakeException, ValueError):  # TODO: implement and document cascading handling?
+    """An error raised in response to an attempt to delete an entry which can't be deleted.
+
+    This most likely reason for this to be raised would be due to an attempt to
+    deleted a entry that's being kept alive by references without specifying to
+    cascade references in a referential database.
+    """
+
     __slots__: typing.Sequence[str] = ()
 
 
 class InvalidDataFound(SakeException, LookupError):
+    """An error raised when the retrieved data is in an unexpected format.
+
+    This may indicate that you are running different versions of a Sake
+    implementation with the same database.
+    """
+
     __slots__: typing.Sequence[str] = ()
 
 
 class EntryNotFound(SakeException, LookupError):
+    """An error raised in response to an attempt to get an entry which doesn't exist.
+
+    !!! note
+        This shouldn't ever be raised by a delete method or iter method.
+    """
+
     __slots__: typing.Sequence[str] = ()