vortexpy 4.0.25__tar.gz → 4.0.28__tar.gz

{vortexpy-4.0.25 → vortexpy-4.0.28}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2016 
+Copyright (c) 2016-2026 Flying Ion Pty Ltd
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,3 +19,4 @@ 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.
+

vortexpy-4.0.28/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: vortexpy
+Version: 4.0.28
+Summary: Flying Ion's observable, routable, data serialisation and transport code.
+Author-email: Flying Ion Pty Ltd <contact@flyingion.com>
+License: MIT License
+        
+        Copyright (c) 2016-2026 Flying Ion Pty Ltd
+        
+        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://flyingion.com
+Project-URL: Repository, https://gitlab.com/flyingion/vortexpy
+Project-URL: Issues, https://gitlab.com/flyingion/vortexpy/-/issues
+Keywords: vortex,observable,http,compressed,flying-ion
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Description-Content-Type: text/markdown
+Requires-Dist: SQLAlchemy>=2.0
+Requires-Dist: GeoAlchemy2
+Requires-Dist: txwebsocket>=1.1.0
+Requires-Dist: autobahn[twisted]
+Requires-Dist: vcversioner
+Requires-Dist: six
+Requires-Dist: pytz
+Requires-Dist: reactivex>=4.0.4
+Requires-Dist: ddt>=1.6.0
+Requires-Dist: psutil
+Requires-Dist: txhttputil>=1.2.0
+
+# VortexPY
+
+Flying Ion's observable, routable, data serialisation and transport code.
+
+See [README_PERMISSIONS.md](README_PERMISSIONS.md) for the two-level permission
+system (endpoint guards + access control context) introduced in v5.0.
+
+Why PY at the end? To be consistent with VortexJS, which is the Browser side package.
+See https://gitlab.com/flyingion/vortexjs
+
+Requirements:
+* Python 3.5
+* Twisted 16+
+* SQLAlchemy 1, 1.1
+
+The "vortex" is designed to transport "Payloads" from a web browser (VortexJS) to a
+twisted web server (VortexPY). There is also a python client for python client to python server
+communication.
+
+### Vortex, The Observable Part
+
+Vortex was designed to allow the Python server to send updates to the browser with out
+the browser having to create HTTP request polls.
+
+This is achieved by the browser/client sending one or more payloads to the server as a
+HTTP POST, the server then uses this connection to send payloads back to the client.
+
+This HTTP POST connection remains active, Until the client needs
+to send more Payloads to the server. To do this, the client simply starts a new HTTP POST
+request to the server, the server will then close the old request and begin sending 
+Payloads down the respose path of the new request.
+
+Python classes = Vortex
+
+### Transport
+
+Transport occurs over a HTTP(S) layer.
+
+Experimental classes are present to transport data to/from subprocess pipes, this
+worked, except the subprocess didn't die and the idea was abandoned
+(It was a Celery worker).
+
+Because of this effort, it's much easier to add other transport mechanisms.
+
+Python classes = VortexResource (Receive), VortexConnection (Send)
+
+### Payloads
+A "Payload" is a class that stores some routing information, a result and a list of
+"Tuples".
+
+The routing information is a dict / json object which looks like this
+{key:"anything.type.of.data.list"}
+(See Routable for more info)
+
+The tuples attribute stores the data, typically this is a list of Tuple (see Tuples)
+objects, however, it can be any data structure that JSON can serialise,
+plus Date()/datetime.
+
+The Payload class is responsible for serialising and compressing it's data down to a 
+"Vortex Msg", ready for transport. Compression is done with zlib, this imrpovement sees
+data reduced to 10% of the original size.
+
+There is custom code that handles converting the structure to JSON objects for json.dumps
+so support can be (carefully) added for other data types such as bytes.
+
+Python classes = Payload
+
+### Tuples
+
+Not to be confused with the built in Python tuple syntax (1, 2, 3), Tuples are registered
+classes with registered attributes.
+
+Vortex Tuples are important in the design as classes that inherit the vortex Tuple
+class will reconstructed as the proper classes at the other end in python. They will have
+onlt the fields registerd as TupleFields populated when they are reconstructed.
+
+This is especially useful when using the SQLAlchemy ORM, as the Tuple code recognises
+column definitions as TupleFields. 
+
+You can just assign session.query(MyTable).all() to payload.tuples, and the vortex will 
+know how to serialise.
+
+From here you can send it do the browser, where the browser may edit some attributes of
+the tuples, then send it back to the python server to update the database. 
+(More on this in Handlers)
+
+Python classes = Tuple, TupleField
+
+### Routable
+
+When a vortex receives a payload, it is sent to the PayloadIO
+
+The PayloadIO, then passes it on to each PayloadEndpoint that has registered with it.
+
+Payload routing ends with PayloadEndpoints, These endpoints are constructed with another
+filter dict/json like object, and a callback.
+
+When PayloadIO tells a PaylaodEndpoint that
+a new Payload has arrived, the PayloadEndpoint checks the Payload.filt against it's own 
+filt.
+
+If the PayloadEndpoints filt is a subset of the Payload.filt, the PayloadEndpoint then
+calls it's callable and passes it the Payload.
+
+PayloadEndpoints register them selves with PayloadIO on construction.
+PayloadIO keeps a list of weak refs to the PayloadEndpoints.
+
+
+
+
+Payloads contain a "filt" attribute, which is a json like dict/object.
+
+
+Python classes = PayloadEndpoint, PayloadIO
+
+### Handlers
+
+Handlers are the provided classes that handle data from the PayloadEndpoints.
+
+* ModelHandler : Simply specify the payload filter and implement the "buildModel" method.
+* OrmCrudHandler : This handler used to Create, Update, Retrieve and Delete SQLAlchemy data.
+                  It can handle an array of tuples, of different types, and has various
+                  hooks allowing the data to be customised before being stored or retreived.
+* AsyncModelHandler : Experimental handler that will likely be deleted.
+
+
+#Change Log
+
+#### 0.3.0
+
+Implemented PY side WebSockets
+
+## License
+
+Copyright (c) 2016-2026 [Flying Ion Pty Ltd](https://flyingion.com). Released under the [MIT License](LICENSE).

{vortexpy-4.0.25 → vortexpy-4.0.28}/README.md

@@ -1,9 +1,12 @@
 # VortexPY
 
-Synerty's observable, routable, data serialisation and transport code.
+Flying Ion's observable, routable, data serialisation and transport code.
+
+See [README_PERMISSIONS.md](README_PERMISSIONS.md) for the two-level permission
+system (endpoint guards + access control context) introduced in v5.0.
 
 Why PY at the end? To be consistent with VortexJS, which is the Browser side package.
-See https://github.com/Synerty/vortexjs
+See https://gitlab.com/flyingion/vortexjs
 
 Requirements:
 * Python 3.5
@@ -126,3 +129,7 @@ Handlers are the provided classes that handle data from the PayloadEndpoints.
 #### 0.3.0
 
 Implemented PY side WebSockets
+
+## License
+
+Copyright (c) 2016-2026 [Flying Ion Pty Ltd](https://flyingion.com). Released under the [MIT License](LICENSE).

vortexpy-4.0.28/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=61.2"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vortexpy"
+version = "4.0.28"
+license = {file = "LICENSE"}
+authors = [{name = "Flying Ion Pty Ltd", email = "contact@flyingion.com"}]
+description = "Flying Ion's observable, routable, data serialisation and transport code."
+readme = "README.md"
+keywords = [
+    "vortex",
+    "observable",
+    "http",
+    "compressed",
+    "flying-ion",
+]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "SQLAlchemy >= 2.0",
+    "GeoAlchemy2",
+    "txwebsocket>=1.1.0",
+    "autobahn[twisted]",
+    "vcversioner",
+    "six",
+    "pytz",
+    "reactivex>=4.0.4",
+    "ddt >=1.6.0",
+    "psutil",
+    "txhttputil>=1.2.0",
+]
+
+[project.urls]
+Homepage = "https://flyingion.com"
+Repository = "https://gitlab.com/flyingion/vortexpy"
+Issues = "https://gitlab.com/flyingion/vortexpy/-/issues"
+
+[tool.setuptools]
+include-package-data = false
+license-files = []
+
+[tool.setuptools.packages.find]
+exclude = ["test"]
+namespaces = false
+
+[project.entry-points."mypy.plugins"]
+vortex_defer = "vortex.mypy_plugin:plugin"

{vortexpy-4.0.25 → vortexpy-4.0.28}/vortex/DataWrapTuple.py

@@ -1,11 +1,11 @@
-"""
- * Created by Synerty Pty Ltd
- *
- * This software is open source, the MIT license applies.
- *
- * Website : http://www.synerty.com
- * Support : support@synerty.com
-"""
+# Copyright (c) 2016-2026 Flying Ion Pty Ltd
+#
+# This software is open source; the MIT license applies.
+# See LICENSE for the full license text.
+#
+# Website : https://flyingion.com
+# Support : contact@flyingion.com
+
 from .Tuple import Tuple, TupleField, addTupleType
 
 

{vortexpy-4.0.25 → vortexpy-4.0.28}/vortex/DeferUtil.py

@@ -1,5 +1,15 @@
+# Copyright (c) 2016-2026 Flying Ion Pty Ltd
+#
+# This software is open source; the MIT license applies.
+# See LICENSE for the full license text.
+#
+# Website : https://flyingion.com
+# Support : contact@flyingion.com
+
 import inspect
 import logging
+from collections.abc import Callable
+from typing import ParamSpec, TypeVar
 
 import twisted
 from twisted.internet import reactor
@@ -13,6 +23,9 @@ from twisted.internet.threads import deferToThread
 
 logger = logging.getLogger(__name__)
 
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
 
 def callMethodLater(func):
     def wrapper(*args, **kwargs):
@@ -136,19 +149,21 @@ class YieldInDeferToThreadException(Exception):
 
 
 def deferToThreadWrapWithLogger(
-    logger, consumeError=False, checkMainThread=True
-):
+    loggerArg: logging.Logger,
+    consumeError: bool = False,
+    checkMainThread: bool = True,
+) -> Callable[[Callable[_P, _R]], Callable[_P, Deferred[_R]]]:
     """Defer To Thread Wrap With Logger
 
     This method is a decorator used to send blocking methods to threads easily.
 
-    :param logger: An instance from logging.getLogger(..)
+    :param loggerArg: An instance from logging.getLogger(..)
     :param consumeError: Should errors occuring in the thread be consumed or errback'd
     :param checkMainThread: Don't use this parameter, it's only needed during reactor
                 startup when the reactors thread isn't properly set and the check
                 fails.
 
-    :return: A deferred.
+    :return: A decorator that makes the wrapped callable return a Deferred.
 
     Usage: ::
 
@@ -161,7 +176,7 @@ def deferToThreadWrapWithLogger(
 
     """
     assert isinstance(
-        logger, logging.Logger
+        loggerArg, logging.Logger
     ), """Usage:
     import logging
     logger = logging.getLogger(__name__)
@@ -170,10 +185,10 @@ def deferToThreadWrapWithLogger(
         pass
     """
 
-    def wrapper(funcToWrap) -> Deferred:
+    def wrapper(funcToWrap: Callable[_P, _R]) -> Callable[_P, Deferred[_R]]:
         def checkForInlineCallbackYield(result):
             if inspect.isgenerator(result):
-                logger.error(
+                loggerArg.error(
                     "Module Name %s, Class Name %s, Function Name %s"
                     " has a yield in it. IT SHOULD NOT.",
                     funcToWrap.__module__,
@@ -183,9 +198,9 @@ def deferToThreadWrapWithLogger(
                 raise YieldInDeferToThreadException()
             return result
 
-        def func(*args, **kwargs):
+        def func(*args: _P.args, **kwargs: _P.kwargs) -> Deferred[_R]:
             if not twisted.python.threadable.isInIOThread() and checkMainThread:
-                logger.error(
+                loggerArg.error(
                     "Module Name %s, Class Name %s, Function Name %s"
                     " is being deferred from a thread. IT SHOULD NOT.",
                     funcToWrap.__module__,
@@ -196,9 +211,9 @@ def deferToThreadWrapWithLogger(
                     "Deferring to a thread can only be done from the main thread"
                 )
 
-            d = deferToThread(funcToWrap, *args, **kwargs)
+            d: Deferred[_R] = deferToThread(funcToWrap, *args, **kwargs)
             d.addCallback(checkForInlineCallbackYield)
-            d.addErrback(vortexLogFailure, logger, consumeError=consumeError)
+            d.addErrback(vortexLogFailure, loggerArg, consumeError=consumeError)
             return d
 
         return func

{vortexpy-4.0.25 → vortexpy-4.0.28}/vortex/Jsonable.py

@@ -1,11 +1,10 @@
-"""
- * Created by Synerty Pty Ltd
- *
- * This software is open source, the MIT license applies.
- *
- * Website : http://www.synerty.com
- * Support : support@synerty.com
-"""
+# Copyright (c) 2016-2026 Flying Ion Pty Ltd
+#
+# This software is open source; the MIT license applies.
+# See LICENSE for the full license text.
+#
+# Website : https://flyingion.com
+# Support : contact@flyingion.com
 
 import logging
 import traceback

{vortexpy-4.0.25 → vortexpy-4.0.28}/vortex/Payload.py

@@ -1,11 +1,11 @@
-"""
- * Created by Synerty Pty Ltd
- *
- * This software is open source, the MIT license applies.
- *
- * Website : http://www.synerty.com
- * Support : support@synerty.com
-"""
+# Copyright (c) 2016-2026 Flying Ion Pty Ltd
+#
+# This software is open source; the MIT license applies.
+# See LICENSE for the full license text.
+#
+# Website : https://flyingion.com
+# Support : contact@flyingion.com
+
 import logging
 import zlib
 from base64 import b64encode, b64decode

{vortexpy-4.0.25 → vortexpy-4.0.28}/vortex/PayloadEndpoint.py

@@ -1,11 +1,11 @@
-"""
- * Created by Synerty Pty Ltd
- *
- * This software is open source, the MIT license applies.
- *
- * Website : http://www.synerty.com
- * Support : support@synerty.com
-"""
+# Copyright (c) 2016-2026 Flying Ion Pty Ltd
+#
+# This software is open source; the MIT license applies.
+# See LICENSE for the full license text.
+#
+# Website : https://flyingion.com
+# Support : contact@flyingion.com
+
 import inspect
 import logging
 import types
@@ -13,9 +13,21 @@ import weakref
 from copy import copy
 from typing import Callable, Optional, Dict, Union
 
+from twisted.internet.defer import inlineCallbacks, maybeDeferred
+
 from vortex.PayloadEnvelope import PayloadEnvelope
 from vortex.PayloadIO import PayloadIO
 from vortex.VortexABC import SendVortexMsgResponseCallable
+from vortex.VortexAccessControlContextABC import (
+    NO_AUTH_ACCESS_CONTROL_CONTEXT,
+    VortexAccessControlContextABC,
+)
+from vortex.VortexEndpointPermission import EndpointPermissionsType as PermissionsType
+from vortex.VortexSession import (
+    _callableLabel,
+    checkAccessControlContextSignature,
+    checkNoHttpSessionInSignature,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -27,7 +39,7 @@ logger = logging.getLogger(__name__)
 #         # PayloadEnvelope,  # payloadEnvelope
 #         # str,  # vortexUuid
 #         # str,  # vortexName
-#         # Any,  # httpSession
+#         # Any,  # vortexSession
 #         # SendVortexMsgResponseCallable  # sendResponse
 #     ],
 #     Optional[Deferred]  # Return
@@ -43,19 +55,46 @@ class PayloadEndpoint:
 
     PERMITTER = None
 
+    #: Deprecation warning emitted when no requiredPermissions are set.
+    _NO_PERMISSIONS_WARNING = (
+        "PayloadEndpoint filt=%s has no requiredPermissions set. "
+        "In a future release, endpoints without explicit permissions "
+        "will raise a RegistrationError."
+    )
+
     def __init__(
         self,
         filt: Dict,
         callable_,
         acceptOnlyFromVortex: Optional[Union[str, tuple]] = None,
         ignoreFromVortex: Optional[Union[str, tuple]] = None,
+        requiredPermissions: Optional[PermissionsType] = None,
     ) -> None:
         """
         :param filt: The filter to match against payloads
         :param callable_: This will be called and passed the payload if it matches
         :param acceptOnlyFromVortex: Accept payloads only from this vortex,
             The vortex can be str or tuple of str, or None to accept from any.
+        :param requiredPermissions: Frozenset of
+            :class:`~vortex.VortexPermission.VortexPermission` class objects that
+            the caller's session must hold.  Pass an empty frozenset to
+            explicitly declare "no permissions required".  Omitting the
+            parameter (``None``) emits a deprecation warning.
         """
+        self._requiredPermissions: Optional[PermissionsType] = requiredPermissions
+
+        if requiredPermissions is None:
+            logger.warning(self._NO_PERMISSIONS_WARNING, filt)
+
+        callableDesc = (
+            f"PayloadEndpoint filt={filt} callback={_callableLabel(callable_)}"
+        )
+        self._callableAcceptsAccessControlContext = checkAccessControlContextSignature(
+            callable_,
+            callableDescription=callableDesc,
+        )
+        checkNoHttpSessionInSignature(callable_, callableDesc)
+
         self._acceptOnlyFromVortex = acceptOnlyFromVortex
         if isinstance(self._acceptOnlyFromVortex, str):
             self._acceptOnlyFromVortex = (self._acceptOnlyFromVortex,)
@@ -79,8 +118,8 @@ class PayloadEndpoint:
                         self._callable = callable_
                         self._callable._endpointWeakClass = self
 
-                    def __call__(self, payload):
-                        self._callable(payload)
+                    def __call__(self, **kwargs):
+                        self._callable(**kwargs)
 
                 w = W(callable_)
 
@@ -129,10 +168,7 @@ class PayloadEndpoint:
             return False
 
         # Filter for the backend vortexes.
-        if (
-            self._acceptOnlyFromVortex
-            and vortexName not in self._acceptOnlyFromVortex
-        ):
+        if self._acceptOnlyFromVortex and vortexName not in self._acceptOnlyFromVortex:
             return False
 
         def removeUnhashable(filt):
@@ -162,33 +198,83 @@ class PayloadEndpoint:
 
         return set(ourFilt).issubset(theirFilt)
 
+    @inlineCallbacks
     def process(
         self,
         payloadEnvelope: PayloadEnvelope,
         vortexUuid: str,
         vortexName: str,
-        httpSession,
+        vortexSession,
         sendResponse: SendVortexMsgResponseCallable,
     ):
+        from vortex.VortexFactory import VortexFactory
 
         if not self.check(payloadEnvelope, vortexName):
             return
 
-        if self.PERMITTER and not self.PERMITTER.check(
-            payloadEnvelope, httpSession
-        ):
+        if self.PERMITTER and not self.PERMITTER.check(payloadEnvelope, vortexSession):
             logger.debug("Permission failed for %s", payloadEnvelope.filt)
             return
 
+        # Level 1: Endpoint permission check
+        auth = VortexFactory.getAuthenticator()
+        if self._requiredPermissions:
+            if not auth:
+                logger.error(
+                    "Permission check for filt=%s cannot be enforced:"
+                    " no authenticator is registered."
+                    " Call VortexFactory.registerAuthenticator(). Request denied.",
+                    payloadEnvelope.filt,
+                )
+                return
+            if not vortexSession:
+                logger.error(
+                    "Permission check for filt=%s cannot be enforced:"
+                    " no VortexSession found. Request denied.",
+                    payloadEnvelope.filt,
+                )
+                return
+            endpointPermissions = yield maybeDeferred(
+                auth.getEndpointPermissions, vortexSession
+            )
+            if not self._requiredPermissions.issubset(endpointPermissions):
+                logger.warning(
+                    "Permission denied for endpoint filt=%s",
+                    payloadEnvelope.filt,
+                )
+                return
+
+        # Level 2: Get access control context, but only if the callback uses it.
+        # Default to the sentinel so handlers always receive a non-None value
+        # with a clear error on attribute access when auth is unavailable.
+        accessControlContext = NO_AUTH_ACCESS_CONTROL_CONTEXT
+        if self._callableAcceptsAccessControlContext and auth and vortexSession:
+            raw_ctx = yield maybeDeferred(
+                auth.getAccessControlContext, vortexSession, vortexName, vortexUuid
+            )
+            if not isinstance(raw_ctx, VortexAccessControlContextABC):
+                logger.error(
+                    "Authenticator.getAccessControlContext() returned %r (type %s);"
+                    " expected a VortexAccessControlContextABC subclass."
+                    " accessControlContext will be the no-auth sentinel.",
+                    raw_ctx,
+                    type(raw_ctx).__name__,
+                )
+            else:
+                accessControlContext = raw_ctx
+
         callable_ = self._wref()
         if callable_:
-            return callable_(
+            kwargs = dict(
                 payloadEnvelope=payloadEnvelope,
                 vortexUuid=vortexUuid,
                 vortexName=vortexName,
-                httpSession=httpSession,
                 sendResponse=sendResponse,
+                vortexSession=vortexSession,
             )
+            if self._callableAcceptsAccessControlContext:
+                kwargs["accessControlContext"] = accessControlContext
+            return callable_(**kwargs)
         else:
             PayloadIO().remove(self)