10.01.05: Default Interpreter for VS Code, allocation fix, F5 note, #als

Author: valhuber

README.md

@@ -242,6 +242,8 @@ There are a few articles that provide some orientation to API Logic Server:
 
 ### Change Log
 
+01/07/2024 - 10.01.05: Default Interpreter for VS Code, Allocation fix, F5 note, #als signposts
+
 01/03/2024 - 10.01.00: Quoted col names, Default Interpreter for VS Code
 
 12/21/2023 - 10.00.01: Fix < Python 3.11

api_logic_server_cli/api_logic_server.py

@@ -12,10 +12,10 @@
 Called from api_logic_server_cli.py, by instantiating the ProjectRun object.
 '''
 
-__version__ = "10.01.04"
+__version__ = "10.01.05"
 recent_changes = \
     f'\n\nRecent Changes:\n' +\
-    "\t01/07/2024 - 10.01.04: Default Interpreter for VS Code, allocation fix, F5 note \n"\
+    "\t01/07/2024 - 10.01.05: Default Interpreter for VS Code, allocation fix, F5 note, #als \n"\
     "\t01/03/2024 - 10.01.00: Quoted col names \n"\
     "\t12/21/2023 - 10.00.01: Fix < Python 3.11 \n"\
     "\t12/19/2023 - 10.00.00: Kafka pub/sub, Fix MySQL CHAR/String, list/hash/set types \n"\
@@ -341,23 +341,22 @@ def copy_md(project: 'ProjectRun', from_doc_file: str, to_project_file: str = "R
 
 
 
-def create_nw_tutorial(project_name, api_logic_server_dir_str):
-    """ copy tutorial from docs, and link to it from readme.md 
-
-    1. prototype/nw/readme.md is the short preamble to "go see tutorial"
-
-    2. append the standard readme
+def create_nw_tutorial_and_readme(project: 'ProjectRun'):
+    """ append standard readme to nw readme, and copy Tutorial from docs
     
     Alert: 2 copies of the Tutorial:
     * ~/dev/ApiLogicServer/api_logic_server_cli/prototypes/nw/Tutorial.md
     * ~/dev/Org-ApiLogicServer/Docs/docs/Tutorial.md
-    * cli version is master -->
+    * docs version is master -->
     * cp api_logic_server_cli/project_prototype_nw/Tutorial.md ../Org-ApiLogicServer/Docs/docs/Tutorial.md
     """
 
-    project_readme_file_path = project_name + '/readme.md'  # brief 'go read tutorial' - add std readme
-    standard_readme_file_path = str(Path(api_logic_server_dir_str).\
-        joinpath('prototypes/base').joinpath("readme.md"))
+    copy_md(project = project,
+            from_doc_file="Tutorial.md",
+            to_project_file='Tutorial.md')
+
+    project_readme_file_path = project.project_directory + '/readme.md'  # brief 'go read tutorial' - add std readme
+    standard_readme_file_path = project.api_logic_server_dir_path.joinpath('prototypes/base').joinpath("readme.md")
     with open(project_readme_file_path, 'a') as project_readme_file:
         with open(standard_readme_file_path) as standard_readme_file:
             project_readme_file.write(standard_readme_file.read())
@@ -428,11 +427,11 @@ def create_project_and_overlay_prototypes(project: 'ProjectRun', msg: str) -> st
                     f'Suggestions:\n'
                     f'.. Verify the --project_name argument\n'
                     f'.. If you are using Docker, verify the -v argument\n\n')
+
         if project.nw_db_status in ["nw", "nw+"]:
             log.debug(".. ..Copying nw customizations: logic, custom api, readme, tests, admin app")
             project.add_nw_customizations(do_security=False, do_show_messages=False)
 
-
         if project.nw_db_status in ["nw+"]:
             log.debug(".. ..Copy in nw+ customizations: readme, perform_customizations")
             nw_dir = (Path(api_logic_server_dir_str)).\
@@ -1206,7 +1205,7 @@ def add_nw_customizations(self, do_show_messages: bool = True, do_security: bool
 
         2. Deep copy project_prototype_nw (adds logic)
 
-        3. Create readme files: Tutorial, api/integration_defs/readme.md
+        3. Create readme files: Tutorial (copy_md), api/integration_defs/readme.md
 
         Args:
         """
@@ -1222,7 +1221,7 @@ def add_nw_customizations(self, do_show_messages: bool = True, do_security: bool
             joinpath('prototypes/nw')  # PosixPath('/Users/val/dev/ApiLogicServer/ApiLogicServer-dev/org_git/ApiLogicServer-src/api_logic_server_cli/prototypes/nw')
         recursive_overwrite(nw_path, self.project_directory)  # '/Users/val/dev/ApiLogicServer/ApiLogicServer-dev/org_git/tutorial/1. Instant_Creation'
 
-        create_nw_tutorial(self.project_directory, str(self.api_logic_server_dir_path))
+        create_nw_tutorial_and_readme(project = self)
 
         copy_md(project = self,
                 from_doc_file="Sample-Integration.md",

api_logic_server_cli/prototypes/base/api/customize_api.py

@@ -11,18 +11,16 @@
 app_logger = logging.getLogger(__name__)
 
 def expose_services(app, api, project_dir, swagger_host: str, PORT: str):
-    """ Customize API - new end points for services 
+    """ #als: Customize API - new end points for services 
     
         Brief background: see readme_customize_api.md
+
+        Your Code Goes Here
     
     """
 
     app_logger.debug("api/customize_api.py - expose custom services")
 
-    #########################
-    # Define custom apis here
-    #########################    
-
     @app.route('/hello_world')
     def hello_world():  # test it with: http://api_logic_server_host:api_logic_server_port/hello_world?user=ApiLogicServer
         """

api_logic_server_cli/prototypes/base/config.py

@@ -9,9 +9,12 @@
 import socket
 import json
 
-#  for complete flask_sqlachemy config parameters and session handling,
-#  read: file flask_sqlalchemy/__init__.py AND flask/config.py
 '''
+#als: configuration settings
+
+For complete flask_sqlachemy config parameters and session handling,
+  see: file flask_sqlalchemy/__init__.py AND flask/config.py
+
 app.config.setdefault('SQLALCHEMY_DATABASE_URI', 'sqlite:///:memory:')
 app.config.setdefault('SQLALCHEMY_BINDS', None)
 app.config.setdefault('SQLALCHEMY_NATIVE_UNICODE', None)

api_logic_server_cli/prototypes/base/database/customize_models.py

@@ -11,4 +11,6 @@
 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/base/devops/docker-image/env.list

@@ -1,5 +1,6 @@
 # these values override the Config values, and the CLI arguments
 # the values below are for testing - uncomment and view them on console log on server start
+# #als: configure environment variables
 
 # ip to which flask will be bound (default: 0.0.0.0)
 # APILOGICPROJECT_FLASK_HOST=flask-host-e

api_logic_server_cli/prototypes/base/integration/kafka/kafka_consumer.py

@@ -49,7 +49,9 @@ def kafka_consumer(safrs_api: safrs.SAFRSAPI = None):
 
     logger.debug(f'Kafka Listener thread activated {bus}')
 
-    '''   Define topic handlers here, e.g.
+    '''   Your Code Goes Here
+    
+    Define topic handlers here, e.g.
 
     @bus.handle('order_shipping')
     def order_shipping(msg: object, safrs_api: safrs.SAFRSAPI):

api_logic_server_cli/prototypes/base/logic/declare_logic.py

@@ -11,11 +11,11 @@
 app_logger = logging.getLogger(__name__)
 
 def declare_logic():
-    ''' Declarative multi-table derivations and constraints, extensible with Python. 
-
+    ''' Declarative multi-table derivations and constraints, extensible with Python.
+ 
     Brief background: see readme_declare_logic.md
     
-    Use code completion (Rule.) to declare rules here:
+    Your Code Goes Here - Use code completion (Rule.) to declare rules
     '''
 
     def handle_all(logic_row: LogicRow):  # OPTIMISTIC LOCKING, [TIME / DATE STAMPING]

api_logic_server_cli/prototypes/base/readme.md

@@ -23,13 +23,15 @@ To run your project, the system requires various runtime systems for data access
 
 Setup your Python environment, according to whether you did a *local install*, or *Docker*.  Choose the appropriate section, then run.
 
+API Logic Server CLI provides commands you can use to ugrade your project, e.g., to add security.  Discover the CLI commands with `ApiLogicServer`.
+
  
 
 ## Establish Your Python Environment - Local Install
 
-VSCode projects automatically use installed API Logic Server `venv`, so this step is not required until you want to create a local `venv` for additional packages.
+> VSCode projects automatically use installed API Logic Server `venv`, so this step is ***not required*** until you want to create a local `venv` for additional packages.
 
-You `requirements.txt` has already been created, so...
+Your `requirements.txt` has already been created, so...
 
 ```bash title="Install API Logic Server in a Virtual Environment"
 python -m venv venv                        # may require python3 -m venv venv
@@ -43,8 +45,6 @@ Notes:
 
 * If using SqlServer, install `pyodbc`.  Not required for docker-based projects.  For local installs, see the [Quick Start](https://apilogicserver.github.io/Docs/Install-pyodbc/).
 
-* If you are creating multiple projects, you may wish to use a [Shared venv](https://apilogicserver.github.io/Docs/Project-Env/).
-
  
 
 ## Establish Your Python Environment - Docker
@@ -93,6 +93,8 @@ the created API, Logic and Web App.
 
 Please see the `nw` sample for examples of typical customizations.  You can open it in GitHub (use Shift + "." to view in project mode) - [click here](https://github.com/ApiLogicServer/demo).
 
+Search for `Your Code Goes Here`.  Key files summarized below:
+
 | Directory | Usage                         | Key Customization File             | Typical Customization                                                                 |
 |:-------------- |:------------------------------|:-----------------------------------|:--------------------------------------------------------------------------------------|
 | ```api``` | **JSON:API**<br>*Ready to Run*                    | ```api/customize_api.py```         | Add new end points / services                                                         |

api_logic_server_cli/prototypes/base/security/declare_security.py

@@ -9,12 +9,13 @@
 app_logger = logging.getLogger(__name__)
 
 """
-
 First, Activate Security: https://apilogicserver.github.io/Docs/Security-Activation/
 
 Then, Declare Security here: https://apilogicserver.github.io/Docs/Security-Authorization/
 
 See documentation: https://apilogicserver.github.io/Docs/Security-Overview/
 
 Security is invoked on server start (api_logic_server_run), per activation in `config.py`
+
+Your Code Goes Here
 """