ApiLogicServer 14.3.14__py3-none-any.whl → 14.3.20__py3-none-any.whl

api_logic_server_cli/prototypes/manager/system/genai/examples/genai_demo/genai_demo_docs_logic/database/alembic/readme.md

@@ -0,0 +1,18 @@
+The diagram below illustrates a simple path for enacting changes to the data model, and using [Alembic](https://alembic.sqlalchemy.org/en/latest/index.html) to automate the database changes:
+
+1. Update `database/models.py` (e.g., add columns, tables)
+2. Use alembic to compute the revisions
+```bash
+cd database
+alembic revision --autogenerate -m "Added Tables and Columns"
+```
+3. Edit the revision file to signify your understanding (see below)
+4. Activate the change
+```bash
+alembic upgrade head 
+```
+
+![alembic example](https://github.com/ApiLogicServer/Docs/blob/main/docs/images/database/alembic/alembic-overview.png?raw=true)
+
+
+Then, run `rebuild-from-model`.  For more information, see [Database Design Changes](https://apilogicserver.github.io/Docs/Database-Changes/).

api_logic_server_cli/prototypes/manager/system/genai/examples/genai_demo/genai_demo_docs_logic/database/alembic/script.py.mako

@@ -0,0 +1,24 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade():
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade():
+    ${downgrades if downgrades else "pass"}

api_logic_server_cli/prototypes/manager/system/genai/examples/genai_demo/genai_demo_docs_logic/database/alembic/versions/readme.md

@@ -0,0 +1 @@
+Python scripts for database migrations, for use by alembic.

api_logic_server_cli/prototypes/manager/system/genai/examples/genai_demo/genai_demo_docs_logic/database/alembic.ini

@@ -0,0 +1,103 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts
+script_location = alembic
+
+# template used to generate migration files
+# file_template = %%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+# defaults to the current working directory.
+# ApiLogicServer - structure is <project>/database
+prepend_sys_path = ../
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the python-dateutil library that can be
+# installed by adding `alembic[tz]` to the pip requirements
+# string value is passed to dateutil.tz.gettz()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the
+# "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to alembic/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "version_path_separator" below.
+# version_locations = %(here)s/bar:%(here)s/bat:alembic/versions
+
+# version path separator; As mentioned above, this is the character used to split
+# version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
+# If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
+# Valid values for version_path_separator are:
+#
+# version_path_separator = :
+# version_path_separator = ;
+# version_path_separator = space
+version_path_separator = os  # Use os.pathsep. Default configuration used for new projects.
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+# sqlalchemy.url = driver://user:pass@localhost/dbname -- set by ApiLogicServer 
+sqlalchemy.url = sqlite:////Users/val/dev/ApiLogicServer/ApiLogicServer-dev/build_and_test/ApiLogicServer/genai_demo/database/db.sqlite
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

api_logic_server_cli/prototypes/manager/system/genai/examples/genai_demo/genai_demo_docs_logic/database/bind_dbs.py

@@ -0,0 +1,21 @@
+from safrs import SAFRSAPI
+import logging as logging  # additional per-database imports
+
+app_logger = logging.getLogger("api_logic_server_app")
+
+'''
+For multi-database support, this is called by Config/server_setup to
+* create the SQLAlchemy binds for each database
+  * NB: must do all binds in 1 call (not 1 call per db): https://www.youtube.com/watch?v=SB5BfYYpXjE
+'''
+
+
+def bind_dbs(flask_app):
+    """ called by api_logic_server_run to open/bind each additional database"""
+
+    flask_app.config.update(SQLALCHEMY_BINDS = {
+      'authentication': flask_app.config['SQLALCHEMY_DATABASE_URI_AUTHENTICATION'],
+      'landing_page' : flask_app.config['SQLALCHEMY_DATABASE_URI_LANDING']
+    })  # make multiple databases available to SQLAlchemy
+
+    return

api_logic_server_cli/prototypes/manager/system/genai/examples/genai_demo/genai_demo_docs_logic/database/customize_models.py

@@ -0,0 +1,19 @@
+from database import models
+from safrs import jsonapi_attr
+from sqlalchemy.orm import relationship, remote, foreign
+import logging
+
+app_logger = logging.getLogger(__name__)
+
+from database.database_discovery.auto_discovery import discover_models
+discover_models()
+
+"""
+If you wish to drive models from the database schema,
+you can use this file to customize your schema (add relationships, derived attributes),
+and preserve customizations over iterations (regenerations of models.py).
+
+Called from models.py (classes describing schema, per introspection).
+
+Your Code Goes Here
+"""

api_logic_server_cli/prototypes/manager/system/genai/examples/genai_demo/genai_demo_docs_logic/database/database_discovery/authentication_models.py

@@ -0,0 +1,183 @@
+# coding: utf-8
+from sqlalchemy import Column, ForeignKey, Integer, String, Text
+from sqlalchemy.orm import relationship
+from sqlalchemy.ext.declarative import declarative_base
+from flask import abort
+from safrs import jsonapi_rpc
+from flask_jwt_extended import get_jwt_identity
+from flask_jwt_extended import create_refresh_token
+from flask_jwt_extended import create_access_token
+
+########################################################################################################################
+# Classes describing database for SqlAlchemy ORM, initially created by schema introspection.
+#
+# Alter this file per your database maintenance policy
+#    See https://apilogicserver.github.io/Docs/Project-Rebuild/#rebuilding
+#
+# Created:  June 07, 2024 13:20:13
+# Database: sqlite:////Users/val/dev/ApiLogicServer/ApiLogicServer-dev/servers/ApiLogicProject/database/authentication_db.sqlite
+# Dialect:  sqlite
+#
+# mypy: ignore-errors
+########################################################################################################################
+ 
+from database.system.SAFRSBaseX import SAFRSBaseX
+from flask_login import UserMixin
+import safrs, flask_sqlalchemy
+from safrs import jsonapi_attr
+from flask_sqlalchemy import SQLAlchemy
+from sqlalchemy.orm import relationship
+from sqlalchemy.orm import Mapped
+from sqlalchemy.sql.sqltypes import NullType
+from typing import List
+
+db = SQLAlchemy() 
+Baseauthentication = declarative_base()  # type: flask_sqlalchemy.model.DefaultMeta
+metadata = Baseauthentication.metadata
+
+#NullType = db.String  # datatype fixup
+#TIMESTAMP= db.TIMESTAMP
+
+from sqlalchemy.dialects.sqlite import *
+
+
+
+class Role(SAFRSBaseX, Baseauthentication, db.Model, UserMixin):  # type: ignore
+    __tablename__ = 'Role'
+    _s_collection_name = 'authentication-Role'  # type: ignore
+    __bind_key__ = 'authentication'
+
+    name = Column(String(64), primary_key=True)
+    allow_client_generated_ids = True
+
+    # parent relationships (access parent)
+
+    # child relationships (access children)
+    UserRoleList : Mapped[List["UserRole"]] = relationship(back_populates="Role")
+
+    @jsonapi_attr
+    def _check_sum_(self):  # type: ignore [no-redef]
+        return None if isinstance(self, flask_sqlalchemy.model.DefaultMeta) \
+            else self._check_sum_property if hasattr(self,"_check_sum_property") \
+                else None  # property does not exist during initialization
+
+    @_check_sum_.setter
+    def _check_sum_(self, value):  # type: ignore [no-redef]
+        self._check_sum_property = value
+
+    S_CheckSum = _check_sum_
+
+
+class User(SAFRSBaseX, Baseauthentication, db.Model, UserMixin):  # type: ignore
+    __tablename__ = 'User'
+    _s_collection_name = 'authentication-User'  # type: ignore
+    __bind_key__ = 'authentication'
+
+    name = Column(String(128))
+    client_id = Column(Integer)
+    id = Column(String(64), primary_key=True, unique=True)
+    username = Column(String(128))
+    password_hash = Column(String(200))
+    region = Column(String(32))
+    allow_client_generated_ids = True
+
+    # parent relationships (access parent)
+
+    # child relationships (access children)
+    ApiList : Mapped[List["Api"]] = relationship(back_populates="owner")
+    UserRoleList : Mapped[List["UserRole"]] = relationship(back_populates="user")
+    
+    # authentication-provider extension - password check
+    def check_password(self, password=None):
+        # print(password)
+        return password == self.password_hash
+    
+    # authentication-provider extension - login endpoint (e.g., for swagger)
+
+    @classmethod
+    @jsonapi_rpc(valid_jsonapi=False)
+    def login(cls, *args, **kwargs):
+        """
+            description: Login - Generate a JWT access token
+            args:
+                username: user
+                password: password
+        """
+        username = kwargs.get("username", None)
+        password = kwargs.get("password", None)
+
+        user = cls.query.filter_by(id=username).one_or_none()
+        if not user or not user.check_password(password):
+            abort(401, "Wrong username or password")
+
+        access_token = create_access_token(identity=user)
+        return { "access_token" : access_token}
+
+    @jsonapi_attr
+    def _check_sum_(self):  # type: ignore [no-redef]
+        return None if isinstance(self, flask_sqlalchemy.model.DefaultMeta) \
+            else self._check_sum_property if hasattr(self,"_check_sum_property") \
+                else None  # property does not exist during initialization
+
+    @_check_sum_.setter
+    def _check_sum_(self, value):  # type: ignore [no-redef]
+        self._check_sum_property = value
+
+    S_CheckSum = _check_sum_
+
+
+class Api(SAFRSBaseX, Baseauthentication, db.Model, UserMixin):  # type: ignore
+    __tablename__ = 'Apis'
+    _s_collection_name = 'authentication-Api'  # type: ignore
+    __bind_key__ = 'authentication'
+
+    id = Column(Integer, primary_key=True)
+    name = Column(String(32))
+    connection_string = Column(String(64))
+    owner_id = Column(ForeignKey('User.id'))
+
+    # parent relationships (access parent)
+    owner : Mapped["User"] = relationship(back_populates=("ApiList"))
+
+    # child relationships (access children)
+
+    @jsonapi_attr
+    def _check_sum_(self):  # type: ignore [no-redef]
+        return None if isinstance(self, flask_sqlalchemy.model.DefaultMeta) \
+            else self._check_sum_property if hasattr(self,"_check_sum_property") \
+                else None  # property does not exist during initialization
+
+    @_check_sum_.setter
+    def _check_sum_(self, value):  # type: ignore [no-redef]
+        self._check_sum_property = value
+
+    S_CheckSum = _check_sum_
+
+
+class UserRole(SAFRSBaseX, Baseauthentication, db.Model, UserMixin):  # type: ignore
+    __tablename__ = 'UserRole'
+    _s_collection_name = 'authentication-UserRole'  # type: ignore
+    __bind_key__ = 'authentication'
+
+    user_id = Column(ForeignKey('User.id'), primary_key=True)
+    notes = Column(Text)
+    role_name = Column(ForeignKey('Role.name'), primary_key=True)
+    allow_client_generated_ids = True
+
+    # parent relationships (access parent)
+    Role : Mapped["Role"] = relationship(back_populates=("UserRoleList"))
+    user : Mapped["User"] = relationship(back_populates=("UserRoleList"))
+
+    # child relationships (access children)
+
+    @jsonapi_attr
+    def _check_sum_(self):  # type: ignore [no-redef]
+        return None if isinstance(self, flask_sqlalchemy.model.DefaultMeta) \
+            else self._check_sum_property if hasattr(self,"_check_sum_property") \
+                else None  # property does not exist during initialization
+
+    @_check_sum_.setter
+    def _check_sum_(self, value):  # type: ignore [no-redef]
+        self._check_sum_property = value
+
+    S_CheckSum = _check_sum_

api_logic_server_cli/prototypes/manager/system/genai/examples/genai_demo/genai_demo_docs_logic/database/database_discovery/auto_discovery.py

@@ -0,0 +1,27 @@
+import importlib
+from pathlib import Path
+import logging
+
+app_logger = logging.getLogger(__name__)
+
+def discover_models():
+    """
+    Discover models in the discovery directory
+    """
+    import os
+    models = []
+    models_path = Path(__file__).parent
+    for root, dirs, files in os.walk(models_path):
+        for file in files:
+            if file.endswith(".py"):
+                spec = importlib.util.spec_from_file_location("module.name", models_path.joinpath(file))
+                if file.endswith("auto_discovery.py"):
+                    pass
+                elif file.endswith('authentication_models.py'):  #tp - avoid double import??
+                    pass
+                else:
+                    models.append(file)
+                    each_model = importlib.util.module_from_spec(spec)
+                    spec.loader.exec_module(each_model)  # runs "bare" module code (e.g., initialization)
+    app_logger.info(f"..discovered models: {models}")
+    return

api_logic_server_cli/prototypes/manager/system/genai/examples/genai_demo/genai_demo_docs_logic/database/db_debug/db_debug.py

@@ -0,0 +1,90 @@
+import sqlalchemy
+from sqlalchemy import create_engine, inspect, MetaData
+from sqlalchemy.orm import Session
+import os, sys
+import oracledb
+import traceback
+from pathlib import Path
+
+running_at = Path(__file__)
+project_dir = running_at.parent.parent.parent
+sys.path.append(str(project_dir))
+os.chdir(str(project_dir))  # so admin app can find images, code
+
+import database.models as models
+
+# *******************************************
+# Use this to inspect SQLAlchemy2 connection
+# *******************************************
+
+def print_meta(meta):
+    print("\n\nmeta.sorted_tables (meta = models.metadata.sorted_tables)\n")
+    for each_table in meta.sorted_tables:
+        print(f'\n{each_table.key}')
+        for each_column in each_table.columns:
+            print(f'\t{each_column.name}')
+
+db_loc = str(project_dir.joinpath('database/db.sqlite'))
+db_url = "sqlite:////Users/val/dev/servers/ApiLogicProject/database/db.sqlite"
+db_url = f"sqlite:///{db_loc}"
+# db_url = "sqlite:////Users/val/dev/servers/ApiLogicProject/database/nw-gold.sqlite"
+from config.config import Config
+db_url = Config.SQLALCHEMY_DATABASE_URI
+if '..' in db_url:  # e.g., f"sqlite:///../database/db.sqlite"
+    db_url = db_url.replace('../', '')
+
+if 'oracle' in db_url:
+    oracle_thick = False
+    if oracle_thick:
+        import oracledb
+        oracledb.init_oracle_client()
+
+print(f'\ndb_debug 10.03.23\nAttempting connect with:\n{db_url}\n')
+
+e = sqlalchemy.create_engine(db_url)
+try:
+    inspector = inspect(e)
+except:
+    traceback.print_exc()
+    print(f'\nConnection failed with:\n{db_url}\nfrom cwd: {os.getcwd()}\n')
+    exit(0)
+conn = e.connect()
+
+with Session(e) as session:
+    print(f'session: {session}')
+    
+    print(f'Tables\n{inspector.get_table_names()}\n')
+    print(f'Views\n{inspector.get_view_names()}')
+
+    # metadata = MetaData(bind=e)
+    metadata = MetaData()  # SQLAlchemy2
+    meta = models.metadata  # tables should show list of db tables
+    print_meta(meta)
+    print("\n\n")
+
+    is_northwind = False
+    if is_northwind:
+        """
+        Caution - disable / delete this code if your database is not Northwind
+
+        Caution - use of debugger may result in "no app context"
+        https://stackoverflow.com/questions/34122949/working-outside-of-application-context-flask
+        """
+        order_id = 10643
+        order : models.Order = session.query(models.Order).filter(models.Order.Id == order_id).one()
+        # hover to view code completion...
+        print(f'Order: {order.Id}, AmountTotal: {order.AmountTotal}, ready: {order.Ready}, Required: {order.RequiredDate}, Customer: {order.CustomerId}, Balance: {order.Customer.Balance}\n\n')
+        order.AmountTotal
+
+        departments = session.query(models.Department).all()
+        for each_dept in departments:
+            print(f'\nDept: {each_dept}')
+            for each_works_for_emp in each_dept.EmployeeList1:
+                print(f'...each_works_for_emp: {each_works_for_emp}')
+            print("")
+            for each_on_loan_emp in each_dept.EmployeeList:
+                print(f'...each_on_loan_emp: {each_on_loan_emp}')
+            print("")
+            for each_sub_dept in each_dept.DepartmentList:
+                print(f'...each_sub_dept: {each_sub_dept}')
+

api_logic_server_cli/prototypes/manager/system/genai/examples/genai_demo/genai_demo_docs_logic/database/models.py

@@ -0,0 +1,123 @@
+# coding: utf-8
+from sqlalchemy import DECIMAL, DateTime  # API Logic Server GenAI assist
+from sqlalchemy import Column, DECIMAL, DateTime, ForeignKey, Integer, String
+from sqlalchemy.orm import relationship
+from sqlalchemy.ext.declarative import declarative_base
+
+########################################################################################################################
+# Classes describing database for SqlAlchemy ORM, initially created by schema introspection.
+#
+# Alter this file per your database maintenance policy
+#    See https://apilogicserver.github.io/Docs/Project-Rebuild/#rebuilding
+#
+# Created:  March 14, 2025 20:10:45
+# Database: sqlite:////Users/val/dev/ApiLogicServer/ApiLogicServer-dev/build_and_test/ApiLogicServer/genai_demo/database/db.sqlite
+# Dialect:  sqlite
+#
+# mypy: ignore-errors
+########################################################################################################################
+ 
+from database.system.SAFRSBaseX import SAFRSBaseX, TestBase
+from flask_login import UserMixin
+import safrs, flask_sqlalchemy, os
+from safrs import jsonapi_attr
+from flask_sqlalchemy import SQLAlchemy
+from sqlalchemy.orm import relationship
+from sqlalchemy.orm import Mapped
+from sqlalchemy.sql.sqltypes import NullType
+from typing import List
+
+db = SQLAlchemy() 
+Base = declarative_base()  # type: flask_sqlalchemy.model.DefaultMeta
+metadata = Base.metadata
+
+#NullType = db.String  # datatype fixup
+#TIMESTAMP= db.TIMESTAMP
+
+from sqlalchemy.dialects.sqlite import *
+
+if os.getenv('APILOGICPROJECT_NO_FLASK') is None or os.getenv('APILOGICPROJECT_NO_FLASK') == 'None':
+    Base = SAFRSBaseX   # enables rules to be used outside of Flask, e.g., test data loading
+else:
+    Base = TestBase     # ensure proper types, so rules work for data loading
+    print('*** Models.py Using TestBase ***')
+
+
+
+class Customer(Base):  # type: ignore
+    """
+    description: Represents a customer entity with unique name, credit limit, and balance.
+    """
+    __tablename__ = 'customer'
+    _s_collection_name = 'Customer'  # type: ignore
+
+    id = Column(Integer, primary_key=True)
+    name = Column(String(255), unique=True)
+    credit_limit : DECIMAL = Column(DECIMAL)
+    balance : DECIMAL = Column(DECIMAL)
+
+    # parent relationships (access parent)
+
+    # child relationships (access children)
+    OrderList : Mapped[List["Order"]] = relationship(back_populates="customer")
+
+
+
+class Product(Base):  # type: ignore
+    """
+    description: Represents a product entity with unique name and unit price.
+    """
+    __tablename__ = 'product'
+    _s_collection_name = 'Product'  # type: ignore
+
+    id = Column(Integer, primary_key=True)
+    name = Column(String(255), unique=True)
+    unit_price : DECIMAL = Column(DECIMAL)
+
+    # parent relationships (access parent)
+
+    # child relationships (access children)
+    ItemList : Mapped[List["Item"]] = relationship(back_populates="product")
+
+
+
+class Order(Base):  # type: ignore
+    """
+    description: Represents an order entity linked to a customer with a note field.
+    """
+    __tablename__ = 'order'
+    _s_collection_name = 'Order'  # type: ignore
+
+    id = Column(Integer, primary_key=True)
+    customer_id = Column(ForeignKey('customer.id'))
+    date_shipped = Column(DateTime)
+    amount_total : DECIMAL = Column(DECIMAL)
+    notes = Column(String(255))
+
+    # parent relationships (access parent)
+    customer : Mapped["Customer"] = relationship(back_populates=("OrderList"))
+
+    # child relationships (access children)
+    ItemList : Mapped[List["Item"]] = relationship(back_populates="order")
+
+
+
+class Item(Base):  # type: ignore
+    """
+    description: Represents an item within an order, linked to a product with mandatory quantity.
+    """
+    __tablename__ = 'item'
+    _s_collection_name = 'Item'  # type: ignore
+
+    id = Column(Integer, primary_key=True)
+    order_id = Column(ForeignKey('order.id'))
+    product_id = Column(ForeignKey('product.id'))
+    quantity = Column(Integer, nullable=False)
+    unit_price : DECIMAL = Column(DECIMAL)
+    amount : DECIMAL = Column(DECIMAL)
+
+    # parent relationships (access parent)
+    order : Mapped["Order"] = relationship(back_populates=("ItemList"))
+    product : Mapped["Product"] = relationship(back_populates=("ItemList"))
+
+    # child relationships (access children)