Merge pull request #12 from swelcker/0.1.5

0.1.5

.gitattributes

@@ -1,7 +1,7 @@
-dist/* linguist-vendored
-docs/* linguist-vendored
-docs_dist_site/* linguist-vendored
+dist/* linguist-documentation
+docs/* linguist-documentation
+docs_dist_site/* linguist-documentation
 msaSDK/msastatic/* linguist-vendored
 *.html linguist-detectable=false
 *.js linguist-detectable=false
-*.css linguist-detectable=false
+*.css linguist-detectable=false

.gitignore

@@ -4,3 +4,4 @@
 /msaSDK.egg-info/
 /msaSDK/msa_sdk.json
 /msaSDK/msa_sdk.sqlite_db
+

LICENCE

@@ -1,6 +1,7 @@
 The MIT License (MIT)
 
-Copyright (c) 2018 Sebastián Ramírez
+Copyright (c) 2022 Stefan Welcker for the msaSDK
+
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -28,28 +28,21 @@
 - **Build connected distributed applications faster**: Ready for [Dapr](https://dapr.io/).
 - **Consistency**: With sometimes 10s or 100s of Micro Services, the SDK helps to easy version control and provides a stable Dapr Basis.
 - **High performance**: Based on [FastAPI](https://fastapi.tiangolo.com/zh/). Enjoy all the benefits.
-- **High efficiency**: Perfect code type hints. Higher code reusability.
-- **Support asynchronous and synchronous hybrid writing**: `ORM`  is based on`SQLModel` & `Sqlalchemy`. Freely customize
-  database type. Asynchronous mode. Strong scalability.
-- **Front-end separation**: The front-end is rendered by `Amis`, the back-end interface is automatically generated
-  by `msaSDK - Admin`. The interface is reusable.
-- **Strong scalability**: The background page supports `Amis` pages and ordinary `html` pages. Easily customize the
-  interface freely.
-- **Automatic api documentation**: Automatically generate Interface documentation by `FastAPI`. Easily debug and share
-  interfaces.
 - **Integrated Scheduler**: Define Scheduler Tasks with natural language timings and dependencies.
-- **Dashboard UI**: Admin and Optional Auth enabled Dashboard with CRUD Forms.
+- **Integrated Dashboard UI**: Admin and Optional Auth enabled Dashboard with CRUD Forms.
 - **Integrated CRUD**: Generates CRUD Router and Admin Dashboard Forms based on SQLModel and SQLAlchemy.
 - **Integrated Abstract Filesystem**: Agnostic Abstract Filesystem API which allows to use S3, GCS, Azure Datalake, your local FS, Youtube etc.
-- **Added justpy WEB UI**: Integrated justpy UI Web Framework to MSAAPI, which allows simple adding of roots to justpy webpages functions.
+- **Integrated justpy WEB UI**: Integrated justpy UI Web Framework to MSAAPI, which allows simple adding of routes to justpy webpages functions.
+- **Integrated Dict with Storage Backend**: Use Dict's with backend storage like redis.
+- **Integrated Signals**: Use and handle Signals and Tasks.
 
-## Dependencies
+## Main Dependencies
 
 - [FastAPI](https://fastapi.tiangolo.com/)
 - [SQLModel](https://sqlmodel.tiangolo.com/)
   combined with  [SQLAlchemy](https://www.sqlalchemy.org/) and [Pydantic](https://pydantic-docs.helpmanual.io/), with all
   their features .
-- [Amis](https://baidu.gitee.io/amis): Vue Frontend
+
 
 ### Usage example is in the app module \_\_init\_\_.py
 
@@ -178,4 +171,15 @@ We can now test and view our documentation using:
 
 Build static Site:
 
-    mkdocs build
+    mkdocs build
+
+
+## Build and Publish
+
+Build:  
+
+    python setup.py sdist
+
+Publish to pypi:
+
+    twine upload dist/*

docs/examples/example_app.md

@@ -1,7 +1,161 @@
-Example Usage of MSAApp
-Copyright (c) 2022 - U2D.ai / S.Welcker
+## Example Usage of MSAApp
+
+??? note "MSAApp Service Definition Settings"
+    ```python
+    # MSAServiceDefinition
+
+    name: str = "msaSDK Service"
+    """Service Name, also used as Title."""
+    version: str = "0.0.0"
+    """Version of the Service."""
+    host: str = "127.0.0.1"
+    """Host/IP which the service runs on."""
+    port: int = 8090
+    """Port which the service binds to."""
+    tags: List[str] = []
+    """Optional Metadata: Use this to carry some variables through the service instance."""
+    allow_origins: List[str] = ["*"]
+    """CORSMiddleware. List[str]. List of allowed origins (as strings) or all of them with the wildcard ``*`` ."""
+    allow_credentials: bool = True
+    """CORSMiddleware. Bool. Allow (True) Credentials (Authorization headers, Cookies, etc)."""
+    allow_methods: List[str] = ["*"]
+    """CORSMiddleware. List[str]. Specific HTTP methods (POST, PUT) or all of them with the wildcard ``*`` ."""
+    allow_headers: List[str] = ["*"]
+    """CORSMiddleware. List[str]. Specific HTTP headers or all of them with the wildcard ``*`` ."""
+    healthdefinition: MSAHealthDefinition = MSAHealthDefinition()
+    """Healthdefinition Instance."""
+    uvloop: bool = True
+    """Use UVLoop instead of asyncio loop."""
+    sysrouter: bool = True
+    """Enable the System Routes defined by router.system module (/sysinfo, /sysgpuinfo, /syserror, ...)."""
+    servicerouter: bool = True
+    """Enable the Service Routes defined by the MSAApp (/scheduler, /status, /defintion, /settings, /schema, /info, ...)."""
+    starception: bool = True
+    """Enable Starception Middleware."""
+    validationception: bool = True
+    """Enable Validation Exception Handler."""
+    httpception: bool = True
+    """Enable the HTTP Exception Handler, which provides HTML Error Pages instead of JSONResponse."""
+    httpception_exclude: List[int] = [307, ]
+    """List of HTTP Exception Codes which are excluded and just forwarded by the HTTP Exception Handler."""
+    cors: bool = True
+    """Enable CORS Middleware."""
+    httpsredirect: bool = False
+    """Enable HTTPS Redirect Middleware."""
+    gzip: bool = False
+    """Enable GZIP Middleware."""
+    session: bool = False
+    """Enable Session Middleware."""
+    csrf: bool = True
+    """Enable CSRF Forms Protection Middleware."""
+    msgpack: bool = False
+    """Enable Messagepack Negotiation Middleware."""
+    instrument: bool = True
+    """Enable Prometheus Instrumentation for the instance."""
+    static: bool = True
+    """Enable the internal Static Folder (``msastatic``) and Mount to instance."""
+    pages: bool = True
+    """Enable the Pages Routes (/profiler, /testpage), if site is Off also (/, /monitor, /monitor_inline)."""
+    graphql: bool = False
+    """Enable initiation of Strawberry GraphQLRouter (/graphql)."""
+    context: bool = False
+    """Enable Context Middleware."""
+    pagination: bool = False
+    """Enable FastAPI Pagination."""
+    profiler: bool = False
+    """Enable Profiler Middleware."""
+    profiler_output_type: str = "html"  # text or html
+    """Set the Profiler Output Type, should be html or text, html is needed if you want to use the profiler on the Admin Site."""
+    profiler_single_calls: bool = True
+    """Enable to Track each Request by the Profiler."""
+    profiler_url: str = "/profiler"
+    """Set the URL to reach the profiler result html, /profiler."""
+    templates: bool = True
+    """Enable the internal Templates and mount the directory."""
+    templates_dir: List[str] = ["msatemplates", "msatemplates/errors"]
+    """Set the List of Directories for the MSAUITemplate Engine to look for the requested template."""
+    timing: bool = False
+    """Enables Timing Middleware, reports timing data at the granularity of individual endpoint calls."""
+    limiter: bool = False
+    """Enables Rate Limiter (slowapi)."""
+    scheduler: bool = True
+    "Enables MSA Scheduler Engine."
+    scheduler_debug: bool = False
+    "Enables MSA Scheduler debug messages."
+    abstract_fs: bool = True
+    """Enables internal Abstract Filesystem."""
+    abstract_fs_url: str = "."
+    """Set's Filesystem URL"""
+    json_db: bool = True
+    """Enables internal NoSQl/TinyDB DB."""
+    json_db_memory_only: bool = False
+    """JSON DB only in memory, don't store to file/db url"""
+    json_db_url: str = "./msa_sdk.json"
+    """Set's DB URL, compatibility with async and SQLModel/SQLAlchemy is required."""
+    sqlite_db: bool = True
+    """Enables internal Asynchron SQLite DB."""
+    sqlite_db_debug: bool = False
+    """Enables internal DB Debug output."""
+    sqlite_db_crud: bool = True
+    """Enables CRUD API creation of the provided SQLModels."""
+    sqlite_db_meta_drop: bool = False
+    """If True, all existing Data and Schemas in internal DB get's deleted at Startup."""
+    sqlite_db_meta_create: bool = True
+    """Enables internal DB Metadata creation from defined SQLModels at Startup."""
+    sqlite_db_url: str = "sqlite+aiosqlite:///msa_sdk.sqlite_db?check_same_thread=True"
+    """Set's DB URL, compatibility with async and SQLModel/SQLAlchemy is required."""
+    ui_justpy: bool = True
+    """Enables internal justpy mounting."""
+    ui_justpy_demos: bool = True
+    """Enables justpy demos"""
+    site: bool = True
+    """Enables internal Admin Site Dashboard."""
+    site_auth: bool = False
+    """Extends internal Admin Dashboard with Auth."""
+    site_title: str = "Admin"
+    """Set's internal Admin Dashboard Titel."""
+    site_copyright: str = "Copyright © 2022 by u2d.ai"
+    """Set's internal Admin Dashboard copyright information."""
+    site_icon: str = "/msastatic/img/favicon.png"
+    """Set's internal Admin Dashboard Favicon."""
+    site_url: str = ""
+    """Set's internal Admin Dashboard Site URL, normally empty."""
+    root_path: str = "/admin"
+    """Set's internal Admin Dashboard Root Path, normally ``/admin``."""
+    language: str = ""  # 'zh_CN','en_US'
+    """Set's internal Admin Dashboard language (``zh_CN`` or ``en_US``=default if empty)."""
+
+
+    ```
+
+## Minimal Example
+```python
+
+from msaSDK.models.service import get_msa_app_settings
+from msaSDK.service import MSAApp
+
+
+settings = get_msa_app_settings()
+settings.title = "Your Microservice Titel"
+settings.version = "0.0.1"
+settings.debug = True
+
+app = MSAApp(settings=settings)
+
+app.logger.info("Initialized " + settings.title + " " + settings.version)
+
+
+@app.get("/my_service_url")
+def my_service():
+    return {"message": "hello world"}
+
+if __name__ == '__main__':
+    pass
 ```
-Example Usage of MSAApp
+
+
+## With CRUD/SQLModels and Scheduler
+```python
 from typing import Optional, List
 
 from sqlmodel import SQLModel
@@ -68,3 +222,8 @@ async def shutdown():
 if __name__ == '__main__':
     pass
 ```
+
+## System and Service API routes (Optional)
+Turning on the MSAApp settings ``sysrouter``and ``servicerouter``then you also get the following routes:
+
+![Scheduler API Router](../images/msa_example_app_servicesystem_api.png)

docs/examples/example_crud.md

@@ -0,0 +1,54 @@
+Required MSAApp Service Definition (Settings):
+
+    sqlite_db_crud: bool = True
+
+### Example Usage of MSAApp.utils.crud
+
+```python
+
+from typing import Optional, List
+
+from sqlmodel import SQLModel
+
+from msaSDK.admin.utils.fields import Field
+from msaSDK.models.service import get_msa_app_settings
+from msaSDK.service import MSAApp
+
+class TestArticle(SQLModel, table=True):
+    __table_args__ = {'extend_existing': True}
+    id: Optional[int] = Field(default=None, primary_key=True, nullable=False)
+    title: str = Field(title='ArticleTitle', max_length=200)
+    description: Optional[str] = Field(default='', title='ArticleDescription', max_length=400)
+    status: bool = Field(None, title='status')
+    content: str = Field(title='ArticleContent')
+
+
+class TestCategory(SQLModel, table=True):
+    __table_args__ = {'extend_existing': True}
+    id: Optional[int] = Field(default=None, primary_key=True, nullable=False)
+    title: str = Field(title='ArticleTitle', max_length=200)
+    description: Optional[str] = Field(default='', title='ArticleDescription', max_length=400)
+    status: bool = Field(None, title='status')
+    content: str = Field(title='ArticleContent')
+
+
+get_msa_app_settings.cache_clear()
+settings = get_msa_app_settings()
+settings.title = "u2d.ai - MSA/SDK MVP"
+settings.version = "0.0.1"
+settings.debug = True
+
+app = MSAApp(settings=settings, auto_mount_site=True,
+             sql_models=[TestArticle, TestCategory],
+             contact={"name": "msaSDK", "url": "http://u2d.ai", "email": "[email protected]"},
+             license_info={"name": "MIT", "url": "https://opensource.org/licenses/MIT", })
+
+app.logger.info("Initialized " + settings.title + " " + settings.version)
+
+
+if __name__ == '__main__':
+    pass
+```
+
+### Here the API routes you get from this:
+![CRUD API Router](../images/msa_example_crud.png)