updates

.gitmodules

@@ -1,6 +1,3 @@
-[submodule "docs"]
-	path = docs
-	url = git@bitbucket.org:ronnyabraham/fabric_docs.git
 [submodule "bin/deploy_meta"]
 	path = bin/deploy_meta
 	url = git@bitbucket.org:ronnyabraham/fabric_deploy.git

docs

@@ -1 +0,0 @@
-Subproject commit 0bf69ed3ca54049e6e25eda5714cef575636caeb

modules/django.py

@@ -330,10 +330,6 @@ def coverage(application=None, args="test", workingdir=None, outputdir=None,
         the application parameter is required because currently I do not know
         how to run manage.py test on all installed applications.
 
-    TODO:
-        test if coverage is installed and if it isn't give an error explaining
-        the problem
-
     TODO:
         currently, django.manage:test is not working properly because it does
         not find the tests on all installed applications.  Instead, each

modules/docker.py

@@ -25,6 +25,25 @@ except ImportError:
 
 @task
 def docker_ip():
+    """
+    Retrieves the IP address for the Docker database.
+
+    This method determines the appropriate IP address for the Docker-based
+    database.  If the host is set to 'local' in the configuration under
+    docker.database, it assumes the environment is OSX and uses docker-machine
+    to retrieve the IP. Otherwise, it returns the predefined host IP address
+    from the configuration.
+
+    Note:
+        - This method currently returns 'localhost' for 'local' configurations
+          instead of using docker-machine.
+        - For configurations with a specific IP (not 'local'), it directly
+          returns the configured IP address.
+
+    :returns: The IP address of the Docker database.
+    :rtype: str
+    """
+
     configuration = env.config
 
     # in the configuration file under docker,database, if host is set to local
@@ -51,6 +70,27 @@ def docker_ip():
 
 
 def docker_run(cmd):
+    """
+    Executes a Docker command either locally or on a remote host.
+
+    This function facilitates the execution of Docker commands. It determines
+    whether to run the command directly or with sudo based on the host
+    configuration. If the Docker database host is set to 'local', it assumes a
+    local (OSX) environment where the user can directly run Docker commands.
+    Otherwise, for remote hosts, it uses sudo for command execution.
+
+    :param cmd: The Docker command to be executed.
+    :type cmd: str
+
+    Note:
+        - The function uses 'executize' to dynamically select between 'run' and
+          'sudo' methods from fabric.operations based on the host setting.
+        - If 'env.debug' is enabled, the command to be executed is logged for
+          debugging purposes.
+
+    :returns: None. The function executes a command but does not return any
+              value.
+    """
     configuration = env.config
 
     if env.debug:
@@ -77,15 +117,26 @@ def docker_run(cmd):
 @task
 def generate():
     """
-    generates and uploads the docker.yml configuration file based on the
+    Generates and uploads a docker.yml configuration file.
-    settings in the yml file for the current branch.
+
+    This method creates a docker.yml file based on settings specified in the
+    YAML file for the current branch. It dynamically sets up the Docker
+    container configuration for the branch in use. This includes service names,
+    container names, environment variables (such as user, password, and
+    database name), Docker image, and port settings. If additional volume
+    settings are specified, these are also included in the context.
 
     e.g. if we are using development.yml then it will check for the docker
     settings in there to find out what conf values we want to use when creating
     whatever docker containers we are usign for this branch
 
-    currently, only the development branch is using docker, but I might change
+    Note:
-    that in the future.
+        - Primarily used for development branch currently, but can be adapted
+          for others.
+        - In debug mode, additional logging and context printing are enabled.
+
+    :returns: None. The method generates a file and optionally logs the
+        process.
     """
 
     configuration = env.config
@@ -178,12 +229,26 @@ def generate():
 @task
 def create(container='database'):
     """
-    helper function to create a docker-based database container
+    Creates a Docker-based database container.
 
-    container - specifies the type of container being built
+    This function is responsible for setting up a Docker container,
+    specifically a database container by default. It generates a container
+    template based on the specified type and uses Docker Compose to bring up
+    the container.
 
-    NOTE:
+    :param container: Specifies the type of container to create, defaults to
-        "container" must have a corresponding value in configuration file
+                      'database'.  The container type should have corresponding
+                      settings in the configuration file.
+
+    :type container: str
+
+    Note:
+        - The configuration file must contain corresponding settings for the
+          specified container type under the 'docker' section.
+        - In debug mode, additional logging information about the build path
+          and Docker Compose command is provided.
+
+    :returns: None. The function primarily executes Docker Compose commands.
     """
     configuration = env.config
 
@@ -220,19 +285,38 @@ under "docker"
 
 @task
 def status():
+    """
+    Displays the status of all Docker containers.
+
+    This function runs the 'docker ps -a' command which lists all Docker
+    containers and their current status, including those that are stopped.
+
+    :returns: None. The output is displayed to the console.
+    """
     docker_run("docker ps -a")
 
 
 @task
 def start(create=False):
     """
-    this will start the docker container referenced by container_type
+    Starts a specific Docker container.
 
-    NOTE: you should have created it with the docker.create method above
+    This function starts the Docker container as specified in the
-    first!
+    configuration. If the container does not exist and 'create' is set to True,
+    the container will be created and started.
 
-    container_type - the type of container to start
+    :param create: Flag indicating whether to create the container if it does
-    create - craete if container has not yet been created
+                   not exist, defaults to False.
+
+    :type create: bool
+
+    Note:
+        - The container is identified by the 'container_name' attribute in the
+          'docker.database' section of the configuration.
+        - The container should be created first using the 'docker.create'
+          method, unless 'create' is True.
+
+    :returns: None. The container is started, but no value is returned.
     """
     if env.debug:
         logger = loggify("docker", 'create')
@@ -253,14 +337,25 @@ def start(create=False):
 @task
 def stop(remove=False):
     """
-    remove=False
+    Stops and optionally removes a specific Docker container.
-    this will start the docker container referenced by container_type
 
-    NOTE: you should have created it with the docker.create method above
+    This function stops the Docker container as specified in the configuration.
-    first!
+    If the 'remove' flag is set to True, the container will also be removed
+    after being stopped.
 
-    container_type - the type of container to start
+    :param remove: Flag indicating whether to remove the container after
-    create - craete if container has not yet been created
+                   stopping, defaults to False.
+    :type remove: bool
+
+    Note:
+        - The container is identified by the 'container_name' attribute in the
+          'docker.database' section of the configuration.
+
+        - The container should be created first using the 'docker.create'
+            method.
+
+    :returns: None. The container is stopped, and optionally removed, but no
+        value is returned.
     """
     configuration = env.config
     remove = booleanize(remove)
@@ -284,7 +379,31 @@ def stop(remove=False):
 @task
 def edit(param='help'):
     """
-    calls up mvim on the docker conf and build files
+    Opens Docker configuration and build files in MacVim for editing.
+
+    This function streamlines the process of editing Docker-related files by
+    opening them in MacVim, a macOS version of the Vim text editor. It can be
+    directed to open specific Docker configuration or build files based on the
+    provided parameter. If 'help' or an unrecognized key is supplied as the
+    parameter, the function lists all the available files for editing along
+    with their paths.
+
+    :param param: The key for the specific Docker file to edit. Providing
+                  'help' lists all available keys and their associated file
+                  paths.  Defaults to 'help'.
+
+    :type param: str
+
+    Note:
+        - The editable file paths are determined from the project's
+          configuration.
+        - This function is tailored for use in environments where MacVim is
+          available.
+        - File editing is facilitated by the 'maintenance_edit' function, which
+          integrates with MacVim.
+
+    :returns: None. The function either invokes MacVim for a specific file or
+        outputs information.
     """
 
     from .maintenance import edit as maintenance_edit

modules/initialize.py

@@ -608,6 +608,10 @@ def _init_virtualenv(configuration, config, layout):
 
     configuration.addbranch('virtualenv')
 
+    #
+    # bin variable for where the virtualenvwrapper bin was installed
+    configuration.virtualenv.bin = None
+    configuration.virtualenv.bin = config['virtualenv'].get('bin')
     #
     # workon_home variable
     configuration.virtualenv.workon = config['virtualenv']['workon']

modules/maintenance.py

@@ -95,7 +95,7 @@ def edit(remote_path, host_string=None):
     if sys.platform == "darwin":
         editor = "mvim"
     else:
-        editor = "vim"
+        editor = "nvim"
 
     # if env.key_filename:
     #     cmd_edit = "{editor} sftp://{user}@{host_string}/{remote_path}" \

modules/pip.py

@@ -1,12 +1,14 @@
 from fabric.api import env, task
 from fabric.operations import run
+from fabric.context_managers import hide, settings
+from fabric.utils import abort
 
 import sys
 import os
 import logging
 
 from .utils import virtualenv_source, virtualenv
-from .utils import print_console, printerr
+from .utils import printerr
 
 ERROR_BAD_BRANCH_PARAM = -3
 ERROR_BAD_PARAM = -2
@@ -14,6 +16,23 @@ ERROR_BAD_PARAM = -2
 
 @task
 def setup_virtualenv(python3=True):
+    """
+    Sets up a virtual environment using virtualenvwrapper.
+
+    This method creates a new virtual environment with the specified Python
+    version. It uses the 'mkvirtualenv' command from virtualenvwrapper and can
+    optionally use Python 3.
+
+    :param python3: Specifies whether to use Python 3 for the virtual
+                    environment, defaults to True.
+
+    :type python3: bool
+
+    Note:
+        - The virtual environment's name is taken from
+            `configuration.virtualenv.name`.
+        - If `env.debug` is True, the method logs additional debug information.
+    """
     configuration = env.config
 
     if env.debug:
@@ -68,16 +87,30 @@ def setup_virtualenv(python3=True):
 @task
 def bootstrap_pip():
     """
-    bootstraps pip
+    Bootstraps pip in the current environment.
+
+    This method is a wrapper that calls the 'setup' method, intended for
+    setting up or bootstrapping pip in the current virtual environment.
+
+    Note:
+        - This method currently calls 'setup', which handles the installation
+          of packages via pip based on the requirements file.
     """
     # upgrade()
     setup()
 
 
 @task
-def upgrade():
+def update_pip():
     """
-    upgrade pip to latest version
+    Updates pip to the latest version.
+
+    This method updates pip, the Python package installer, to its latest
+    version within the current virtual environment.
+
+    Note:
+        - The method assumes it's running inside a virtual environment.
+        - If `env.debug` is True, it logs the upgrade command being executed.
     """
 
     # configuration = env.config
@@ -100,7 +133,15 @@ def upgrade():
 @task
 def setup():
     """
-    install all packages via pip
+    Installs all required packages via pip.
+
+    This method installs packages specified in a requirements file using pip.
+    The requirements file path is retrieved from
+    `configuration.virtualenv.requirements.filepath`.
+
+    Note:
+        - Assumes execution within a virtual environment.
+        - If `env.debug` is enabled, debug information is logged.
     """
     configuration = env.config
 
@@ -121,30 +162,61 @@ def setup():
 
 
 @task
-def install(package=None):
+def install(package_name=None):
     """
-    install a packages via pip
+    Installs a package via pip within a virtual environment.
+
+    This method installs a specified package using pip. If the package_name
+    is '--all', it installs all packages listed in the requirements file.
+
+    :param package_name: Name of the package to install or '--all' to install
+                         all packages from requirements file, defaults to None.
+    :type package_name: str, optional
+
+    :raises ValueError: If no package_name is provided.
     """
     configuration = env.config
 
-    if not package:
+    if not package_name:
-        printerr("You must specify a package to be installed", ERROR_BAD_PARAM)
+        abort("You must specify a package name to be installed")
 
-    if package == "--all":
+    if package_name == "--all":
         pipinstall_cmd = "pip install -r {requirements_file}".format(
             requirements_file=configuration.virtualenv.requirements.filepath)
     else:
         pipinstall_cmd = "pip install {package}".format(
-            package=package)
+            package=package_name)
 
     if env.debug:
-        print_console("pipinstall_cmd   : %s" % pipinstall_cmd)
+        print("pipinstall_cmd: %s" % pipinstall_cmd)
-
     else:
         with virtualenv():
             run(pipinstall_cmd)
 
 
+@task
+def uninstall(package_name, silent=False):
+    """
+    Uninstalls a specified package from the virtual environment.
+
+    This method activates the virtual environment and uses pip to uninstall the
+    specified package. It can optionally suppress command line output.
+
+    :param package_name: Name of the package to uninstall.
+    :type package_name: str
+
+    :param silent: Suppress command line output if True, defaults to False.
+    :type silent: bool
+    :return: None
+    """
+    with virtualenv():
+        with settings(
+                hide('warnings', 'running', 'stdout', 'stderr'),
+                warn_only=True):
+
+            run(f"pip uninstall -y {package_name}", quiet=silent)
+
+
 @task
 def freeze(param='help'):
     """
@@ -252,3 +324,31 @@ def copyto(branch):
         use_sudo=False,
         backup=True,
         template_dir=configuration.virtualenv.requirements.local)
+
+
+def check_package_installed(package_name, silent=False):
+    """
+    Checks if a specified package is installed in the virtual environment.
+
+    Activates the virtual environment and uses 'pip list' to check if the
+    specified package is installed. Can optionally suppress command line
+    output.
+
+    :param package_name: Name of the package to check.
+    :type package_name: str
+
+    :param silent: Suppress command line output if True, defaults to False.
+    :type silent: bool
+
+    :return: True if installed, False otherwise.
+    :rtype: bool
+    """
+    with virtualenv():
+
+        with settings(
+                hide('warnings', 'running', 'stdout', 'stderr'),
+                warn_only=True):
+
+            output = run(f"pip list | grep {package_name}", quiet=silent)
+
+        return package_name in output

modules/utils.py

@@ -357,17 +357,43 @@ def virtualenv_source():
 
     uses python yield command
     """
-    with prefix("source virtualenvwrapper.sh"):
+    configuration = env.config
+    venv_bin = configuration.virtualenv.bin
+
+    if venv_bin: 
+     venv_activate = f"source {venv_bin}/virtualenvwrapper.sh"
+    else:
+     venv_activate = "source virtualenvwrapper.sh"
+
+    with prefix(venv_activate):
         yield
 
 
 @_contextmanager
 def virtualenv():
     """
-    helper method to set the virtual environment for the following commands
+    Context manager for setting the virtual environment for commands.
 
-    uses python yield command
+    This helper method sets up the virtual environment specified in the
+    configuration before executing any commands within its context. It uses
+    the Python context manager pattern with the `yield` keyword to
+    temporarily modify the environment for the duration of the with-block.
+    The virtual environment is specified by the name in
+    `configuration.virtualenv.name` and is activated using the `workon`
+    command.
+
+    Note:
+        - This method relies on the Fabric library's `prefix` context manager
+          and assumes the use of virtualenvwrapper or a similar tool for
+          managing virtual environments.
+        - The method expects `configuration.virtualenv.name` to be properly
+          set in `env.config`.
+
+    Example Usage:
+        with virtualenv():
+            run("python manage.py migrate")
     """
+
     configuration = env.config
     with virtualenv_source():
         with prefix("workon %s" % configuration.virtualenv.name):

share/templates/conf/django/files/local.generated.jinja2

@@ -140,7 +140,7 @@ LOGGING = {
     'root': {
         # automatically set to level WARNING
 
-        'handlers': ['console.code', 'file.log', 'server.file.log'],
+        'handlers': ['console.code', '{{ file_log_handler__name_project }}', '{{ file_debug_handler__name_server }}' ],
         'propagate': True,
     },
 

share/templates/conf/gunicorn/files/local.generated.jinja2

@@ -140,7 +140,7 @@ LOGGING = {
     'root': {
         # automatically set to level WARNING
 
-        'handlers': ['console.code', 'file.log', 'server.file.log'],
+        'handlers': ['console.code', '{{ file_log_handler__name_project }}', '{{ file_debug_handler__name_server }}' ],
         'propagate': True,
     },
 

share/templates/readmes/debug_toolbar.md

@@ -0,0 +1,13 @@
+
+# Problem with Django Debug Toolbar
+
+If the Django Debug Toolbar runs on the admin but not on your apps, this might be the issue and solution:
+
+The problem turned out to be that the `<body> ... </body>` tags were not rendered in the template. Adding them to my template fixed the issue.
+
+It's interesting that the Django tutorial doesn't use a template with a complete HTML document, yet it specifically mentions following the installation directions for the Django Debug Toolbar, even though the app won't work with it as presented.
+
+Anyway, many thanks to u/reallydarkcloud for the insightful response.
+
+
+https://www.reddit.com/r/django/comments/15k68fa/djangodebugtoolbar_works_in_the_admin_but_not_in/

share/templates/readmes/ycm.md

@@ -0,0 +1,37 @@
+# YCM Setup with Python 3.11.9
+
+## Overview
+
+Due to issues with getting YCM (YouCompleteMe) to work with Python 3.12, it's recommended to create all virtual environments using Python version 3.11.9. This guide will walk you through setting up YCM with Python 3.11.9.
+
+## Creating a Virtual Environment
+
+To create a virtual environment using Python 3.11.9, run the following command:
+
+```bash
+mkvirtualenv -p $(pyenv which python3.11) environment_name
+```
+
+Replace environment_name with your desired virtual environment name.
+
+## Recompiling YCM
+If you encounter issues with YCM, you may need to recompile it. Follow these steps:
+
+```
+cd ~/.vim/bundle/YouCompleteMe
+git pull origin master
+python3 install.py --all
+```
+
+This will pull the latest changes from the YCM repository and recompile it with the necessary support.
+
+## Setting Up YCM
+To configure YCM for your project, create a .ycm_extra_conf.py file in the root directory of your project. The file should contain the following Python code:
+
+```python
+def Settings(**kwargs):
+    return {
+        'interpreter_path': "/Users/ronny/.virtualenvs/PROJECT_NAME/bin/python"
+    }
+```
+