underscorepy 0.5.1__tar.gz → 0.6.2__tar.gz

underscorepy-0.6.2/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2023 Matthew Shaw
+
+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.
+

underscorepy-0.6.2/MANIFEST.in

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

underscorepy-0.6.2/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.1
+Name: underscorepy
+Version: 0.6.2
+Summary: _.py library
+Home-page: https://shaw.cx/_.py
+Author: Matthew Shaw
+Author-email: mshaw.cx@gmail.com
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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.2/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.2/_/__init__.py

@@ -0,0 +1,32 @@
+#
+# (c) 2015-2023 Matthew Shaw
+#
+# Authors
+# =======
+# Matthew Shaw <mshaw.cx@gmail.com>
+#
+
+import importlib
+import os
+import sys
+
+root = os.path.dirname(__file__)
+root = os.path.join(root, '..')
+root = os.path.abspath(root)
+
+from .utils import *
+
+from . import version
+from . import settings
+from . import auth
+from . import handlers
+from . import components
+
+from .application import Application
+
+# placeholder for comonents
+caches    = Container()
+databases = Container()
+logins    = Container()
+records   = Container()
+supports  = Container()

underscorepy-0.6.2/_/application.py

@@ -0,0 +1,221 @@
+#
+# (c) 2015-2023 Matthew Shaw
+#
+# Authors
+# =======
+# Matthew Shaw <mshaw.cx@gmail.com>
+#
+
+import asyncio
+import logging
+import os
+import signal
+import socket
+import sys
+import traceback
+
+import tornado.web
+
+import _
+
+
+class Application(tornado.web.Application):
+    @classmethod
+    def main(cls, ns=None):
+        _.application = self = cls()
+        try:
+            asyncio.run(self.__async_main(ns))
+        except _.error as e:
+            if _.args.debug:
+                traceback.print_tb(e.__traceback__)
+            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)
+
+        name = self.__class__.__name__.lower()
+        try:
+            await _.settings.load(ns=ns, name=name)
+            await self.logging()
+        except _.error as e:
+            if _.args.debug:
+                traceback.print_tb(e.__traceback__)
+            logging.error('%s', e)
+            self.stop()
+
+        if not self._stop_event.is_set():
+            for name,component in _.logins.items():
+                try:
+                    await _.wait(component.args(name))
+                except _.error as e:
+                    logging.error('%s', e)
+                    self.stop()
+                    break
+
+        if not self._stop_event.is_set():
+            try:
+                await self.__async_init()
+            except _.error as e:
+                logging.error('%s', e)
+
+        for name,component in _.caches.items():
+            await component.close()
+
+        for name,component in _.databases.items():
+            await component.close()
+
+    async def __async_init(self, **kwds):
+        # check if a sessions cache was specified
+        _.sessions = _.config.get(_.name, 'sessions', fallback=None)
+        if _.sessions:
+            logging.debug('Sessions cache: %s', _.sessions)
+            try:
+                _.sessions = _.caches[_.sessions]
+            except KeyError:
+                raise _.error('Unknown sessions cache instance: %s', _.sessions)
+
+        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:
+            logging.warning('No "initialize" function defined')
+
+        if 'cookie_secret' not in self.settings:
+            self.settings['cookie_secret'] = await self.cookie_secret()
+
+        patterns = list(self._records_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
+
+        patterns.append(
+            ( r'/(favicon.ico)', tornado.web.StaticFileHandler, {'path':''}),
+            )
+
+        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, patterns, **kwds):
+        # call the Tornado Application init here to give children a chance
+        # to initialize patterns and settings
+        super().__init__(patterns, **self.settings)
+
+        if 'xheaders' not in kwds:
+            kwds['xheaders'] = True
+
+        try:
+            self.listen(_.args.port, _.args.address, **kwds)
+        except Exception as e:
+            raise _.error('%s', e) from None
+
+        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
+
+    async def logging(self):
+        'underscore apps can override or extend this function'
+
+        # add the handlers to the logger
+        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(
+                logging.Formatter(
+                    fmt = '%(asctime)s %(levelname)-8s %(message)s',
+                    datefmt = '%Y-%m-%d %H:%M:%S',
+                    )
+                )
+            root_logger = logging.getLogger()
+            root_logger.addHandler(file_logger)
+
+    async def cookie_secret(self):
+        'underscore apps can override this function'
+        if _.sessions is not None:
+            return await _.wait(_.sessions.cookie_secret())
+
+    async def on_login(self, handler, user, *args, **kwds):
+        '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():
+            while True:
+                # bail if the stop event is set
+                # otherwise run the function after the timeout occurs
+                try:
+                    await asyncio.wait_for(self._stop_event.wait(), timeout=_timeout)
+                    break
+                except asyncio.TimeoutError as e:
+                    pass
+                try:
+                    result = await _.wait(fn(*args, **kwds))
+                except Exception as e:
+                    logging.exception(e)
+        return asyncio.create_task(_periodic())
+
+    def stop(self):
+        logging.debug('Setting stop event')
+        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:
+            if handler(signum, frame):
+                return
+        logging.info('Terminating %s on %s signal', _.name, signame)
+        self.loop.call_soon_threadsafe(self.stop)
+
+    # demonstrate a specific signal handler
+    # and print newline after ^C on terminals
+    def on_sigint(self, signum, frame):
+        print()

underscorepy-0.6.2/_/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.2/_/caches/__init__.py

@@ -0,0 +1,50 @@
+#
+# (c) 2015-2023 Matthew Shaw
+#
+# Authors
+# =======
+# Matthew Shaw <mshaw.cx@gmail.com>
+#
+
+import _
+
+
+class Cache:
+    @classmethod
+    async def _(cls, name, **kwds):
+        # create a dynamic child class with kwds from the ini file
+        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
+
+    async def close(self):
+        pass
+
+    async def cookie_secret(self):
+        raise NotImplementedError
+
+    def save_session(self, session):
+        try:
+            return session['session_id']
+        except KeyError:
+            raise _.error('No session_id defined in session')
+
+    async def load_session(self, session_id):
+        raise NotImplementedError
+
+
+class Handler(_.handlers.Protected):
+    pass

underscorepy-0.6.2/_/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.2/_/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))