underscorepy 0.6.0__tar.gz → 0.6.3__tar.gz

{underscorepy-0.6.0 → underscorepy-0.6.3}/MANIFEST.in

@@ -1,2 +1,2 @@
 recursive-include _ *
-include *.rst
+include *.md

{underscorepy-0.6.0/underscorepy.egg-info → underscorepy-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: underscorepy
-Version: 0.6.0
+Version: 0.6.3
 Summary: _.py library
 Home-page: https://shaw.cx/_.py
 Author: Matthew Shaw
@@ -12,9 +12,12 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Programming Language :: Python :: 3.7
 License-File: LICENSE
+Requires-Dist: tornado
 
 
 underscore.py
 -------------
 
 This is a framework for me that has morphed overtime. Some "features" are broken because I have not needed them for my own projects for quite some time. Eventually those bugs will be resolved.
+
+For anyone confused by Python files like `_/databases/__databases__.py` I wrote a custom import loader that looks for `__dirname__.py` files before `__init__.py` because I find it easier to track the files that way. Very experimental, and probably fragile, but maybe I'll submit a PEP for it someday.

underscorepy-0.6.3/README.md

@@ -0,0 +1,7 @@
+
+underscore.py
+-------------
+
+This is a framework for me that has morphed overtime. Some "features" are broken because I have not needed them for my own projects for quite some time. Eventually those bugs will be resolved.
+
+For anyone confused by Python files like `_/databases/__databases__.py` I wrote a custom import loader that looks for `__dirname__.py` files before `__init__.py` because I find it easier to track the files that way. Very experimental, and probably fragile, but maybe I'll submit a PEP for it someday.

{underscorepy-0.6.0 → underscorepy-0.6.3}/_/__init__.py

@@ -6,30 +6,27 @@
 # Matthew Shaw <mshaw.cx@gmail.com>
 #
 
-import asyncio
+import importlib
 import os
+import sys
 
 root = os.path.dirname(__file__)
 root = os.path.join(root, '..')
 root = os.path.abspath(root)
 
-stop = asyncio.Event()
-
-# a generic error class for throwing exceptions
-class error(Exception):
-    def __init__(self, fmt, *args):
-        self.message = fmt % args
-
-    def __str__(self):
-        return self.message
-
 from .utils import *
 
 from . import version
 from . import settings
 from . import auth
-from . import components
 from . import handlers
-from . import websockets
+from . import components
 
 from .application import Application
+
+# placeholder for comonents
+caches    = Container()
+databases = Container()
+logins    = Container()
+records   = Container()
+supports  = Container()

{underscorepy-0.6.0 → underscorepy-0.6.3}/_/application.py

@@ -22,7 +22,7 @@ import _
 class Application(tornado.web.Application):
     @classmethod
     def main(cls, ns=None):
-        self = cls()
+        _.application = self = cls()
         try:
             asyncio.run(self.__async_main(ns))
         except _.error as e:
@@ -31,14 +31,21 @@ class Application(tornado.web.Application):
             logging.error('%s', e)
 
     async def __async_main(self, ns):
+        self._records_patterns = []
+        self._login_patterns   = []
+
+        self.patterns = []
+        self.settings = {}
+
         self.loop = asyncio.get_event_loop()
+        self._stop_event = asyncio.Event()
 
         signal.signal(signal.SIGINT,  self.__signalHandler)
         signal.signal(signal.SIGTERM, self.__signalHandler)
 
-        app = self.__class__.__name__.lower()
+        name = self.__class__.__name__.lower()
         try:
-            await _.settings.load(self, ns=ns, app=app)
+            await _.settings.load(ns=ns, name=name)
             await self.logging()
         except _.error as e:
             if _.args.debug:
@@ -46,17 +53,8 @@ class Application(tornado.web.Application):
             logging.error('%s', e)
             self.stop()
 
-        if not _.stop.is_set():
-            for name,component in _.login.items():
-                try:
-                    await _.wait(component.args(name))
-                except _.error as e:
-                    logging.error('%s', e)
-                    self.stop()
-                    break
-
-        if not _.stop.is_set():
-            for name,component in _.support.items():
+        if not self._stop_event.is_set():
+            for name,component in _.logins.items():
                 try:
                     await _.wait(component.args(name))
                 except _.error as e:
@@ -64,32 +62,33 @@ class Application(tornado.web.Application):
                     self.stop()
                     break
 
-        if not _.stop.is_set():
+        if not self._stop_event.is_set():
             try:
                 await self.__async_init()
             except _.error as e:
                 logging.error('%s', e)
 
-        for name,component in _.database.items():
+        for name,component in _.caches.items():
             await component.close()
 
-        for name,component in _.cache.items():
+        for name,component in _.databases.items():
             await component.close()
 
     async def __async_init(self, **kwds):
-        self.patterns   = []
-        self.login_urls = []
-
         # check if a sessions cache was specified
-        _.sessions = _.config.get(_.app, 'sessions', fallback=None)
+        _.sessions = _.config.get(_.name, 'sessions', fallback=None)
         if _.sessions:
             logging.debug('Sessions cache: %s', _.sessions)
             try:
-                _.sessions = _.cache[_.sessions]
+                _.sessions = _.caches[_.sessions]
             except KeyError:
                 raise _.error('Unknown sessions cache instance: %s', _.sessions)
 
-        # call the child applications entry point
+        self.settings['static_path']   = _.paths('static')
+        self.settings['template_path'] = _.paths('templates')
+        self.settings['debug']         = _.args.debug
+
+        # call the underscore application's entry point
         try:
             await _.wait(self.initialize())
         except NotImplementedError:
@@ -98,28 +97,34 @@ class Application(tornado.web.Application):
         if 'cookie_secret' not in self.settings:
             self.settings['cookie_secret'] = await self.cookie_secret()
 
-        for instance,cls in _.login.items():
-            self.login_urls.append((f'/login/{instance}', cls))
+        patterns = list(self._records_patterns)
 
-        if self.login_urls:
-            self.patterns = self.login_urls + self.patterns
-            self.patterns = [
-                ( r'/login',  _.handlers.LoginPage ),
-                ( r'/logout', _.handlers.Logout    ),
-                ] + self.patterns
+        if self._login_patterns:
+            self._login_patterns += [
+                ( r'/login',  _.logins.LoginPage ),
+                ( r'/logout', _.logins.Logout    ),
+                ]
             self.settings['login_url'] = '/login'
+        patterns += self._login_patterns
+        patterns += self.patterns
 
-        self.patterns.append(
+        patterns.append(
             ( r'/(favicon.ico)', tornado.web.StaticFileHandler, {'path':''}),
             )
 
-        await self.__listen()
-        await _.stop.wait()
+        if _.args.debug:
+            for (pattern,cls,*params) in patterns:
+                handler = f'{cls.__module__}.{cls.__name__}'
+                logging.debug('%-32s %s %s', pattern, handler, params[0] if params else '')
+
+        await self.__listen(patterns)
+        await self._stop_event.wait()
+        await _.wait(self.on_stop())
 
-    async def __listen(self, **kwds):
+    async def __listen(self, patterns, **kwds):
         # call the Tornado Application init here to give children a chance
         # to initialize patterns and settings
-        super(Application, self).__init__(self.patterns, **self.settings)
+        super().__init__(patterns, **self.settings)
 
         if 'xheaders' not in kwds:
             kwds['xheaders'] = True
@@ -131,6 +136,16 @@ class Application(tornado.web.Application):
 
         logging.info('Listening on %s:%d', _.args.address, _.args.port)
 
+    def _record_handler(self, name, cls):
+        self._records_patterns.append(
+            (f'/{name}/{cls._name}(?:/(.*))?', cls)
+            )
+
+    def _login_handler(self, name, cls):
+        self._login_patterns.append(
+            (f'/{name}/{cls._name}', cls)
+            )
+
     async def initialize(self):
         'underscore apps should override this function'
         raise NotImplementedError
@@ -139,8 +154,8 @@ class Application(tornado.web.Application):
         'underscore apps can override or extend this function'
 
         # add the handlers to the logger
-        if _.config.getboolean(_.app, 'logging', fallback=False):
-            full_path = _.paths(f'{_.app}.log')
+        if _.config.getboolean(_.name, 'logging', fallback=False):
+            full_path = _.paths(f'{_.name}.log')
             file_logger = logging.FileHandler(full_path)
             file_logger.setLevel(logging.DEBUG if _.args.debug else logging.INFO)
             file_logger.setFormatter(
@@ -158,9 +173,14 @@ class Application(tornado.web.Application):
             return await _.wait(_.sessions.cookie_secret())
 
     async def on_login(self, handler, user, *args, **kwds):
-        'underscore apps should override this function'
+        'underscore apps should override this function if a login is specified'
         raise NotImplementedError
 
+    def task(self, fn, *args, **kwds):
+        async def _task():
+            await _.wait(fn(*args, **kwds))
+        return asyncio.create_task(_task())
+
     def periodic(self, _timeout, fn, *args, **kwds):
         'run a function or coroutine on a recurring basis'
         async def _periodic():
@@ -168,7 +188,7 @@ class Application(tornado.web.Application):
                 # bail if the stop event is set
                 # otherwise run the function after the timeout occurs
                 try:
-                    await asyncio.wait_for(_.stop.wait(), timeout=_timeout)
+                    await asyncio.wait_for(self._stop_event.wait(), timeout=_timeout)
                     break
                 except asyncio.TimeoutError as e:
                     pass
@@ -180,17 +200,19 @@ class Application(tornado.web.Application):
 
     def stop(self):
         logging.debug('Setting stop event')
-        _.stop.set()
+        self._stop_event.set()
+
+    def on_stop(self):
+        pass
 
     def __signalHandler(self, signum, frame):
         'handle signals in a thread-safe way'
         signame = signal.Signals(signum).name
         handler = getattr(self, f'on_{signame.lower()}', None)
         if handler:
-            stop = handler(signum, frame)
-            if stop:
+            if handler(signum, frame):
                 return
-        logging.info('Terminating %s on %s signal', _.app, signame)
+        logging.info('Terminating %s on %s signal', _.name, signame)
         self.loop.call_soon_threadsafe(self.stop)
 
     # demonstrate a specific signal handler

underscorepy-0.6.3/_/auth.py

@@ -0,0 +1,105 @@
+#
+# (c) 2015-2023 Matthew Shaw
+#
+# Authors
+# =======
+# Matthew Shaw <mshaw.cx@gmail.com>
+#
+
+import base64
+import binascii
+import functools
+import hashlib
+import urllib.parse
+
+import _
+
+
+# based on tornado.web.authenticated
+def _next(handler):
+    if handler.request.method in ("GET","HEAD"):
+        url = handler.get_login_url()
+        if "?" not in url:
+            if urllib.parse.urlsplit(url).scheme:
+                next_url = handler.request.full_url()
+            else:
+                next_url = handler.request.uri
+            url += "?" + urllib.parse.urlencode(dict(next=next_url))
+        handler.redirect(url)
+    else:
+        raise _.HTTPError(403)
+
+
+# generic decorator to callback to a function
+# return true to allow the method to be called
+# return false to block the method
+def filter(filter_func):
+    def _filter(method):
+        @functools.wraps(method)
+        def wrapper(self, *args, **kwds):
+            if filter_func(self):
+                return method(self, *args, **kwds)
+            _next(self)
+        return wrapper
+    return _filter
+
+
+# same as above but pass the current_user session to the function
+# blocks when no session is associated with the request
+# return true to allow the method to be called
+# return false to block the method
+def filter_user(filter_func):
+    def _filter_user(method):
+        @functools.wraps(method)
+        def wrapper(self, *args, **kwds):
+            if self.current_user:
+                if filter_func(self.current_user):
+                    return method(self, *args, **kwds)
+            _next(self)
+        return wrapper
+    return _filter_user
+
+
+# inteded to be used by underscore apps to check that any user is logged in
+current_user = filter_user(lambda current_user: True)
+
+# intended to be over-ridden before components are loaded for more fine-grain
+# control over access to component handlers
+protected    = filter_user(lambda current_user: True)
+
+
+# implement old school user/name password prompt
+# useful for command-line tools to pass as part of the URL
+def basic(realm='Authentication'):
+    def basic_auth(method):
+        @functools.wraps(method)
+        async def wrapper(self, *args, **kwds):
+            auth = self.request.headers.get('Authorization', '')
+            if auth.startswith('Basic '):
+                auth = binascii.a2b_base64(auth[6:]).decode('utf-8')
+                username,password = auth.split(':', 1)
+                component = _.config.get(_.name, 'basic', fallback=None)
+                if not component:
+                    raise _.HTTPError(500, 'No component specified for basic auth')
+                try:
+                    login = _.logins[component]
+                except KeyError:
+                    raise _.HTTPError(500, 'Invalid component specified for basic auth')
+                success = await login.check(username, password)
+                if success:
+                    return method(self, *args, **kwds)
+            self.set_status(401)
+            self.set_header('WWW-Authenticate', f'Basic realm={realm}')
+            self.finish()
+        return wrapper
+    return basic_auth
+
+
+def simple_hash(value):
+    value = value.encode('utf-8')
+    for i in range(99999):
+        value = hashlib.sha512(value).digest()
+    return base64.b64encode(value).decode('ascii')
+
+
+__all__ = _.all()

{underscorepy-0.6.0 → underscorepy-0.6.3}/_/caches/__init__.py

@@ -13,11 +13,19 @@ class Cache:
     @classmethod
     async def _(cls, name, **kwds):
         # create a dynamic child class with kwds from the ini file
-        subclass = type(cls.__name__, (cls,), kwds)
-        #await subclass.init(name)
-        self = subclass()
-        await self.init(**kwds)
-        _.cache[name] = self
+        try:
+            members = dict(_.config['sessions'])
+        except KeyError:
+            members = {}
+
+        members['expires']  = int(members.get('expires',  24))
+        members['interval'] = int(members.get('interval', 60))
+        members.update(kwds)
+
+        # instantiate the derived class
+        self = type(cls.__name__, (cls,), _.prefix(members))()
+        _.caches[name] = self
+        await self.init(name, **kwds)
 
     async def init(self, **kwds):
         pass
@@ -36,3 +44,7 @@ class Cache:
 
     async def load_session(self, session_id):
         raise NotImplementedError
+
+
+class Handler(_.handlers.Protected):
+    pass

underscorepy-0.6.3/_/caches/dbcache.py

@@ -0,0 +1,117 @@
+#
+# (c) 2015-2023 Matthew Shaw
+#
+# Authors
+# =======
+# Matthew Shaw <mshaw.cx@gmail.com>
+#
+
+import base64
+import json
+import logging
+import os
+
+import _
+
+
+class DbCache(_.caches.Cache):
+    _config  = 'config'
+    _key_col = 'key'
+    _key     = 'cookie'
+    _val_col = 'value'
+
+    _table      = 'sessions'
+    _session_id = 'session_id'
+
+    async def init(self, name, database=None, table=None, **kwds):
+        if not hasattr(_.application, 'is_session_expired'):
+            raise _.error('Application does not have is_session_expired function defined')
+
+        if database is None:
+            if 1 == len(_.databases):
+                database = list(_.databases.keys())[0]
+            else:
+                raise _.error('dbcache requires a database to be specified')
+        self.db = _.databases[database]
+
+        schema = self.db.schema('config')
+        table = schema.table(self._config)
+        table.column(self._key_col).primary_key()
+        table.column(self._val_col)
+        await schema.apply()
+
+        schema = self.db.schema('sessions')
+        table = schema.table(self._table)
+        table.column(self._session_id).primary_key()
+        for col,dbtype in kwds.items():
+            table.column(col).type(dbtype)
+        await schema.apply()
+
+        # interval comes from the [sessions] section of the ini
+        _.application.periodic(self._interval, self.clear_stale_sessions)
+
+        members = dict(
+            name       = name,
+            db         = self.db,
+            table      = self._table,
+            session_id = self._session_id,
+            )
+        subclass = type(name, (DbCacheSessions,), _.prefix(members))
+        _.application._record_handler('sessions', subclass)
+
+    async def cookie_secret(self):
+        secret = await self.db.find_one(self._config, self._key_col, self._key)
+        if secret:
+            secret = secret['value']
+        else:
+            secret = base64.b64encode(os.urandom(32))
+            record = {
+                self._key_col : self._key,
+                self._val_col : secret,
+            }
+            await self.db.upsert(self._config, record)
+        return secret
+
+    async def save_session(self, session):
+        super().save_session(session)
+        await self.db.upsert(self._table, session)
+
+    async def load_session(self, session_id):
+        record = await self.db.find_one(self._table, self._session_id, session_id)
+        if not record:
+            return None
+        if await _.wait(_.application.is_session_expired(record, self._expires)):
+            return None
+        return record
+
+    async def clear_stale_sessions(self):
+        for record in await self.db.find(self._table):
+            if await _.wait(_.application.is_session_expired(record, self._expires)):
+                logging.debug('Removing expired session: %s', record[self._session_id])
+                await self.db.delete(self._table, self._session_id, record[self._session_id])
+
+
+class DbCacheSessions(_.handlers.Protected):
+    @_.auth.protected
+    async def get(self, session_id=None):
+        if session_id:
+            record = await self._db.find_one(self._table, self._session_id, session_id)
+            self.write(record)
+        else:
+            records = await self._db.find(self._table)
+            data = []
+            for record in records:
+                data.append(dict(record))
+            self.write({'data':data})
+
+    @_.auth.protected
+    async def delete(self, session_id=None):
+        self.set_status(204)
+        if session_id:
+            await self._db.delete(self._table, self._session_id, session_id)
+
+            callback = getattr(_.application, f'on_{self._name}_delete', None)
+            if callback is None:
+                callback = getattr(_.application, 'on_dbcache_delete', None)
+            if callback:
+                await _.wait(callback(self._name, record))

underscorepy-0.6.3/_/caches/memory.py

@@ -0,0 +1,71 @@
+#
+# (c) 2015-2023 Matthew Shaw
+#
+# Authors
+# =======
+# Matthew Shaw <mshaw.cx@gmail.com>
+#
+
+import os
+import json
+
+import _
+
+
+class Memory(_.caches.Cache):
+    async def init(self, name, **kwds):
+        if not hasattr(_.application, 'is_session_expired'):
+            raise _.error('Application does not have is_session_expired function defined')
+
+        self.mem = {}
+
+        members = dict(
+            name = name,
+            mem  = self.mem,
+            )
+        subclass = type(name, (MemorySessions,), _.prefix(members))
+        _.application._record_handler('sessions', subclass)
+
+    def cookie_secret(self):
+        return os.urandom(32)
+
+    def save_session(self, session):
+        session_id = super().save_session(session)
+        self.mem[session_id] = json.dumps(session)
+
+    async def load_session(self, session_id):
+        session = self.mem.get(session_id, None)
+        if not session:
+            return None
+        if await _.wait(_.application.is_session_expired(session, self.expires)):
+            return None
+        return json.loads(session)
+
+
+
+class MemorySessions(_.handlers.Protected):
+    @_.auth.protected
+    async def get(self, session_id=None):
+        if session_id:
+            session = self._mem[session_id]
+            if not session:
+                raise _.HTTPError(404)
+            session = json.loads(session)
+            self.write(session)
+        else:
+            data = []
+            for session_id in self._mem:
+                session = self._mem[session_id]
+                data.append(json.loads(session))
+            self.write({'data':data})
+
+    @_.auth.protected
+    async def delete(self, session_id=None):
+        self.set_status(204)
+        if session_id:
+            del self._mem[session_id]
+            callback = getattr(_.application, f'on_{self._name}_delete', None)
+            if callback is None:
+                callback = getattr(_.application, 'on_memory_delete', None)
+            if callback:
+                await _.wait(callback(self._name, session_id))