venvit 7.3.0__tar.gz

venvit-7.3.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+----------------------------------------------------------------------------
+Copyright (c) 2023, Hendrik du Toit
+
+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.

venvit-7.3.0/PKG-INFO

@@ -0,0 +1,466 @@
+Metadata-Version: 2.4
+Name: venvit
+Version: 7.3.0
+Summary: Tools for creating, maintaining and automating Python virtual environments.
+License-Expression: MIT
+License-File: LICENSE.txt
+Author: Hendrik du Toit
+Author-email: hendrik@brightedge.co.za
+Maintainer: Hendrik du Toit
+Maintainer-email: hendrikdt@citiqprepaid.co.za
+Requires-Python: >=3.10
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Archiving :: Packaging
+Requires-Dist: beetools (>=5.2.5,<6.0.0)
+Requires-Dist: gitpython (>=3.1.44,<4.0.0)
+Requires-Dist: pydantic (>=2.11.4,<3.0.0)
+Requires-Dist: pydantic-settings (>=2.9.1,<3.0.0)
+Project-URL: Homepage, https://github.com/BrightEdgeeServices/venvit
+Project-URL: Issues, https://github.com/BrightEdgeeServices/venvit/issues
+Project-URL: Repository, https://github.com/BrightEdgeeServices/venvit.git
+Project-URL: changelog, https://github.com/BrightEdgeeServices/venvit/releases
+Description-Content-Type: text/markdown
+
+# VEnvIt
+
+| **Category** | **Status' and Links**                                                                                                           |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| General      | \[![][maintenance_y_img]\][maintenance_y_lnk] \[![][semver_pic]\][semver_link]                                                  |
+| CI           | \[![][pre_commit_ci_img]\][pre_commit_ci_lnk] \[![][codecov_img]\][codecov_lnk] \[![][gha_docu_img]\][gha_docu_lnk]             |
+| Github       | \[![][gh_issues_img]\][gh_issues_lnk] \[![][gh_language_img]\][gh_language_lnk] \[![][gh_last_commit_img]\][gh_last_commit_lnk] |
+
+VEnvIt is a utility that employs Python and PowerShell scripts to create, initialize, and remove virtual environments
+tailored for both development and production systems. It provides significant flexibility, allowing users to configure
+their environments according to specific requirements.
+
+Instead of relying on traditional configuration files (INI, TOML, JSON), VEnvIt uses user-modifiable scripts for
+settings configuration. This design choice offers greater flexibility and adaptability, enabling fine-grained
+customization that standard configuration files cannot accommodate.
+
+However, this approach introduces additional complexity and requires a thorough understanding of the application's
+workings. Proficiency in Python and PowerShell scripting is essential to effectively utilize and configure VEnvIt.
+
+Is this a Python or a PowerShell project? Thechnically it is both. As much As I would like it to be rather a Python
+project, PowerShell is essential:
+
+- The assumption is that their is no native Python installation on the machine (see step Instlaation, Step 2 below). The
+  app must be kick-started from somewhere, so PowerSeell seems to be the right choice.
+- The instlaation manipulate the environment variables of the current session. This is tricky if not impossible with
+  Python only. PowerShell sorts this out.
+
+## Key Features
+
+- **Flexible Environment Management**: Create, initialize, and remove virtual environments using customizable scripts.
+- **User-Controlled Configuration**: Configure settings through scripts for maximum adaptability.
+- **Tailored for Complex Systems**: Designed to handle the intricacies of unique development and production
+  environments.
+
+## Prerequisites
+
+- **Scripting Knowledge**: Familiarity with Python and PowerShell scripting languages.
+- **Understanding of Virtual Environments**: Basic knowledge of virtual environments and their role in development and
+  production systems.
+
+# Usage Overview
+
+VEnvIt provides three primary scripts for managing virtual environments:
+
+- `vn.ps1`: Creates a new virtual environment.
+- `vs.ps1`: Initializes an existing virtual environment.
+- `vr.ps1`: Removes a virtual environment.
+
+Additional configuration scripts are auto-generated during environment setup for customization.
+
+# Detailed Usage
+
+## Creating a New Virtual Environment (`vn.ps1`)
+
+### Introduction
+
+The `vn.ps1` script creates a new Python virtual environment. It uses a combination of environment variables and
+command-line parameters to set up the environment. If the target project directory already exists and contains a
+`pyproject.toml` file, the Python modules will be installed accordingly. Otherwise, it installs a default set of
+development tools:
+
+- **Pre-Commit**
+- **Black**
+- **Flake8**
+
+### Syntax
+
+```powershell
+.\vn.ps1 -ProjectName <ProjectName> -PythonVer <PythonVer> -Organization <Organization> [-ResetScripts y|n] [-DevMode y|n]
+```
+
+or
+
+```powershell
+.\vn.ps1 -Help
+```
+
+or
+
+### Parameters
+
+- `ProjectName`: The name of the project.
+- `PythonVer`: The Python version for the virtual environment (e.g., `39` or `312`).
+- `Organization`: Acronym for the organization owning the project.
+- `-ResetScripts`: Optional. Use `-ResetScripts y` to reset scripts.
+- `-DevMode`: Optional. Use `-DevMode y` to install development modules from `pyproject.toml`.
+
+### Example
+
+```powershell
+.\vn.ps1 -ProjectName MyProject -PythonVer 310 -Organization MyOrg -ResetScripts y -DevMode y
+```
+
+This command creates a new virtual environment for a project named **MyProject**, using Python 3.10, associated with the
+organization **MyOrg**, resets scripts, and installs development modules.
+
+## Initializing an Existing Virtual Environment (`vs.ps1`)
+
+### Introduction
+
+The `vs.ps1` script initializes an existing virtual environment, ensuring all configurations and dependencies are up to
+date. This includes running project-specific setup and environment variable scripts.
+
+### Syntax
+
+```powershell
+.\vs.ps1 -ProjectName <ProjectName>
+```
+
+### Parameters
+
+- `ProjectName`: The name of the project.
+
+### Example
+
+```powershell
+.\vs.ps1 -ProjectName MyProject
+```
+
+or
+
+```powershell
+.\vs.ps1 -Help
+```
+
+This command initializes the virtual environment for **MyProject**.
+
+## Removing a Virtual Environment (`vr.ps1`)
+
+### Introduction
+
+The `vr.ps1` script removes an existing virtual environment, including all associated configurations and dependencies.
+It also archives and removes project-specific configuration scripts.
+
+### Syntax
+
+```powershell
+.\vr.ps1 -ProjectName <ProjectName>
+```
+
+### Parameters
+
+- `ProjectName`: The name of the project.
+
+### Example
+
+```powershell
+.\vr.ps1 -ProjectName MyProject
+```
+
+This command removes the virtual environment for **MyProject**.
+
+# Project-Specific PowerShell Configuration Scripts
+
+When you create a new virtual environment using `vn.ps1`, it generates additional PowerShell configuration scripts
+specific to the project. These scripts support unique configuration options and assist in the installation and
+activation of the virtual environment. They reside in various subdirectories accessed through environment variables
+pointing to these directories.
+
+### Script Descriptions
+
+1. **`VEnv<ProjectName>Install.ps1`**: Contains special instructions for installing this virtual environment. It is only
+   called by `vn.ps1`. The initial default version can be updated for subsequent runs.
+1. **`VEnv<ProjectName>EnvVar.ps1`**: Sets environment variables for the project.
+1. **`VEnv<ProjectName>Setup_custom.ps1`**: Contains special instructions for setting up the virtual environment.
+1. **`Secrets.ps1`**: Contains instructions for setting secrets for the project. Created in both the default and user
+   secrets directories (`VENVIT_DIR\Secrets` and `~\VenvIt\Secrets`).
+
+### Script Locations
+
+- **Default Configuration Directory (`VENV_CONFIG_DEFAULT_DIR`)**: This directory typically resides on a shared drive,
+  preferably as a subdirectory of the main installation directory (`VENVIT_DIR`). It contains organization-wide scripts.
+- **User Configuration Directory (`~\VenvIt\Config`)**: This directory typically resides on the local drive of the
+  developer's machine and should only be accessible to the current user/environment. Scripts here override those in the
+  default directory.
+
+### Script Management
+
+- If the `-ResetScripts` switch is used with `vn.ps1`, it will archive the current scripts for this project and create
+  new default scripts. Without `-ResetScripts`, existing scripts will be used if they exist.
+- If `vr.ps1` is called to remove the virtual environment, the scripts are archived, and new ones will be created upon
+  the next execution of `vn.ps1`. You can refer to the archive created by `vr.ps1` to access previous scripts.
+
+# Environment Variables
+
+VEnvIt utilizes several environment variables to manage virtual environments effectively. These variables should be set
+during installation.
+
+| Environment Variable        | Description                                                                                                                                                                                                                                                                                                                                                  |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **PROJECTS_BASE_DIR**       | The parent/base directory for all projects (e.g., `C:\Projects`). Organize repositories by organization, such as personal projects and organizational projects (e.g., `C:\Projects\MyOrg\MyProject`, `C:\Projects\Company\CompanyProject`).                                                                                                                  |
+| **VENV_BASE_DIR**           | The directory where the Python virtual environments are stored (e.g., `~\venv`). Unlike the conventional practice of keeping virtual environment files within the project directory, all virtual environments are stored together in this dedicated directory.                                                                                               |
+| **VENV_CONFIG_DEFAULT_DIR** | Directory for default (organization-wide) configuration scripts. Typically a subdirectory of `VENVIT_DIR` (e.g., `$VENVIT_DIR\Configs`). Shared among all developers.                                                                                                                                                                                        |
+| **~\\VenvIt\\Config**       | Directory for user-specific configuration scripts (e.g., `~\VEnvIt\Configs`). Should only be accessible to the current user/machine. Scripts here override those in the default directory.                                                                                                                                                                   |
+| **VENV_ENVIRONMENT**        | Identifies the working environment. Possible values include `loc_dev`, `github_dev`, `prod`, or other values defined by the organization. This variable may be set differently in various environments. The default is set in `$VENV_CONFIG_DEFAULT_DIR\VEnv<ProjectName>EnvVar.ps1` and can be overridden in `~\VenvIt\Config\VEnv<ProjectName>EnvVar.ps1`. |
+| **VENV_PYTHON_BASE_DIR**    | Directory for Python base installations (e.g., `C:\Python`). Different versions of Python are accessed during the creation of virtual environments (e.g., `C:\Python\Python35`, `C:\Python\Python312`).                                                                                                                                                      |
+| **VENVIT_DIR\\Secrets**     | Directory for default (organization-wide) secrets scripts for the current environment as per `VENV_ENVIRONMENT` (e.g., `$VENVIT_DIR\Secrets`). Contents are accessible to all who have access to the installation.                                                                                                                                           |
+| **~\\VenvIt\\Secrets**      | Directory for user-specific secrets scripts for the current environment (e.g., `~\VEnvIt\Secrets`). Contents are private and should not be shared or pushed to repositories. Scripts here override those in the default directory.                                                                                                                           |
+| **VENVIT_DIR**              | Installation directory where VEnvIt scripts reside (e.g., `C:\VEnvIt`). In an organizational setup, this should be a shared drive.                                                                                                                                                                                                                           |
+
+# Default Installation Directory Structure
+
+## Windows
+
+```
+c:\
+├── ~\.
+│   └── VEnvIt (Client/user files)
+│       ├── Config (User configuration files)
+│       │   ├── VEnvMyProjectInstall.ps1
+│       │   ├── VEnvMyProjectEnvVar.ps1
+│       │   ├── VEnvMyProjectCustomSetup.ps1
+│       │   ├── VEnvMyWorkProjectInstall.ps1
+│       │   ├── VEnvMyWorkProjectEnvVar.ps1
+│       │   ├── VEnvMyWorkProjectCustomSetup.ps1
+│       │   └── ...
+│       ├── Secrets (User secrets file)
+│       │   └── Secrets.ps1
+│       └── venv (env:VENV_BASE_DIR)
+│           ├── MyProject_env
+│           ├── MyWorkProject_env
+│           └── ...
+├── Projects (env:PROJECTS_BASE_DIR)
+│   ├── Personal (env:VENV_ORGANIZATION_NAME)
+│   │   ├── MyProject (env:PROJECT_NAME)
+│   │   └── ...
+│   └── Work (env:VENV_ORGANIZATION_NAME)
+│       ├── MyWorkProject (env:PROJECT_NAME)
+│       └── ...
+├── Python (env:VENV_PYTHON_BASE_DIR)
+│   ├── Python39
+│   ├── Python312
+│   └── ...
+.
+.
+.
+└── env:APPDATA (or shared directory for a shared installation)
+    └── VEnvIt (env:VENVIT_DIR)
+        ├── Config (Default configuration files)
+        │   ├── VEnvMyProjectInstall.ps1
+        │   ├── VEnvMyProjectEnvVar.ps1
+        │   ├── VEnvMyProjectCustomSetup.ps1
+        │   ├── VEnvMyWorkProjectInstall.ps1
+        │   ├── VEnvMyWorkProjectEnvVar.ps1
+        │   ├── VEnvMyWorkProjectCustomSetup.ps1
+        │   └── ...
+        └── Config (User configuration files)
+            └── Secrets.ps1
+```
+
+# Shared Installation
+
+To install a shared version of VEnvIt, follow these steps:
+
+1. **Set Environment Variables**: Decide on the values for the system environment variables listed above and set them
+   accordingly.
+
+1. **Remove Existing Python Installations**: Remove any native Python installations and ensure that any references to
+   Python installations are removed from the `PATH` environment variable. This step is vital for successful operation.
+
+1. **Install Python Versions**: Install the various versions of Python you intend to use (e.g., `C:\Python\Python39`,
+   `C:\Python\Python312`). During installation, use the following settings:
+
+   - **Do Not** select "Use admin privileges when installing py.exe."
+   - **Do Not** add `python.exe` to the `PATH`.
+   - Choose "Customize installation."
+   - **Unselect** "py launcher."
+   - **Unselect** "Install for all users."
+   - **Unselect** "Create shortcuts for installed applications."
+   - **Unselect** "Add Python to environment variables."
+   - **Select** "Precompile standard library."
+   - **Select** "Download debugging tools."
+   - **Select** "Download debug binaries (requires VS 2017 or later)."
+   - Change the "Customize install location" to your desired directory (e.g., `C:\Python\Python310`).
+
+1. **Ensure Shared Directory Exists**: The shared directory `VENVIT_DIR` must exist and be accessible.
+
+1. **Run Installation Script**: Open a new PowerShell window **with Administrator rights**. Do not use an existing one.
+   Paste the following script into the PowerShell window:
+
+   ```powershell
+   Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
+   $UpgradeScriptDir = New-Item -ItemType Directory -Path (Join-Path -Path $env:TEMP -ChildPath ("venvit_" + [Guid]::NewGuid().ToString()))
+   $Tag = (Invoke-WebRequest "https://api.github.com/repos/BrightEdgeeServices/venvit/releases" | ConvertFrom-Json)[0].tag_name
+   $UpgradeScriptPath = Join-Path -Path $UpgradeScriptDir.FullName -ChildPath "Installation-Files.zip"
+   Invoke-WebRequest "https://github.com/BrightEdgeeServices/venvit/releases/download/$Tag/Installation-Files.zip" -OutFile $UpgradeScriptPath
+   Expand-Archive -Path $UpgradeScriptPath -DestinationPath $UpgradeScriptDir
+   Import-Module -Name (Join-Path -Path $UpgradeScriptDir.FullName -ChildPath "src\Install-Conclude.psm1")
+   Invoke-ConcludeInstall -Release $Tag -UpgradeScriptDir $UpgradeScriptDir
+   ```
+
+1. **Configure Secrets Scripts**: Configure the `Secrets.ps1` script in both `VENVIT_DIR\Secrets` and
+   `~\VenvIt\Secrets`:
+
+   - Set the ports for the various Docker containers.
+   - Set environment variables for secrets (e.g., `$env:MY_SECRET = 'AaBbCcDdE'`), ensuring they match configurations
+     in GitHub or other services.
+
+1. **Confirm Installation**:
+
+   - Open a new PowerShell window.
+
+   - Verify that the environment variables are set correctly using `Get-ChildItem Env:`.
+
+   - Create a test project:
+
+     ```powershell
+     .\vn.ps1 -ProjectName TestProject -PythonVer 310 -Organization MyOrg -ResetScripts y -DevMode y
+     ```
+
+     - Ensure the virtual environment is activated.
+     - Verify the current directory is correct (e.g., `..\MyOrg\TestProject`).
+     - Confirm environment variables exist and have correct values.
+
+   - Initialize the test project:
+
+     ```powershell
+     .\vs.ps1 -ProjectName TestProject
+     ```
+
+     - Ensure the virtual environment is activated.
+     - Verify the current directory is correct.
+
+   - Remove the test project:
+
+     ```powershell
+     .\vr.ps1 -ProjectName TestProject
+     ```
+
+     - Ensure the virtual environment is deactivated.
+
+# Contributor Guide
+
+Thank you for your interest in contributing to **VEnvIt**. This project is open-source under
+the [MIT License](https://github.com/BrightEdgeeServices/venvit/blob/master/LICENSE) and welcomes contributions in the
+form of bug reports, feature requests, and pull requests.
+
+## Important Resources
+
+- **Source Code**: [GitHub Repository](https://github.com/BrightEdgeeServices/venvit)
+- **Issue Tracker**: [GitHub Issues](https://github.com/BrightEdgeeServices/venvit/issues)
+
+## Reporting Bugs
+
+Please report bugs on the [Issue Tracker](https://github.com/BrightEdgeeServices/venvit/issues). When filing an issue,
+please include:
+
+- A detailed description of the problem.
+  - What command did you execute?
+  - What did you expect to see?
+  - What did you see instead?
+- Steps to reproduce the issue or a test case.
+- Information about your operating system and Python version.
+- The version of VEnvIt you are using.
+
+## Requesting Features
+
+Feature requests are also handled through the [Issue Tracker](https://github.com/BrightEdgeeServices/venvit/issues).
+Please include:
+
+- A detailed description of the proposed feature or improvement.
+- The benefits it would bring to the project.
+- Any proposed solutions or implementation ideas.
+
+## Submitting Changes
+
+- Open a pull request to submit changes.
+- Ensure your code follows the project's coding standards and conventions.
+- If your changes add functionality, update the documentation accordingly.
+- It's recommended to open an issue before starting work to discuss your ideas and approach with the maintainers.
+
+# License
+
+This project is licensed under the terms of
+the [MIT License](https://github.com/BrightEdgeeServices/venvit/blob/master/LICENSE).
+
+# Support
+
+For support or any questions, please open an issue on
+the [Issue Tracker](https://github.com/BrightEdgeeServices/venvit/issues).
+
+# Example Usage of `vn.ps1`, `vs.ps1`, and `vr.ps1`
+
+______________________________________________________________________
+
+## Updating ReleaseNotes Instructions
+
+1. Run the `pushpy.ps1` script or manually commit the current changes.
+1. Generate the release notes
+   1. Use one of the following AI propmpts in Notion to generate the release notes.
+
+      - [Release - Update - General](https://www.notion.so/Release-Update-General-2c0bc8e6c6f38076b4cee82e3cf243fa?v=2c0bc8e6c6f3806e85db000c395f94ce&source=copy_link)
+      - [Release - Update - VenvIt](https://www.notion.so/Release-Update-VenvIt-2c0bc8e6c6f380de84a0f3fbb8b5dda5?v=2c0bc8e6c6f3806e85db000c395f94ce&source=copy_link)
+
+      or
+
+   1. Use the following template and manually update the ReleaseNotes.md file.
+
+      ```
+       # Release ?.?.?
+       ## Summary of Changes
+       - bla, bla, bla
+       ## Next Heading
+       - bla, bla, bla
+       ---
+      ```
+1. You can repeat step 1 multiple times.
+1. You can repeat step 2 multiple times but update the ReleaseNotes that has not been published.
+1. Run the `pushpr.ps1` script once you are ready to create the PR to publish the release. TOy can also manually create
+   the tag, touch a file, commit and push the changes.
+1. Merge the PR in GitHub.
+1. Confirm the following:
+   1. The release update reflects in GitHub
+   1. The release update notification was sent
+
+______________________________________________________________________
+
+[codecov_img]: https://img.shields.io/codecov/c/gh/BrightEdgeeServices/venvit "CodeCov"
+[codecov_lnk]: (https://app.codecov.io/gh/BrightEdgeeServices/venvit) "CodeCov"
+[gha_docu_img]: https://img.shields.io/readthedocs/venvit "Read the Docs"
+[gha_docu_lnk]: https://github.com/BrightEdgeeServices/venvit/blob/master/.github/workflows/02-check-documentation.yml "Read the Docs"
+[gh_issues_img]: https://img.shields.io/github/issues-raw/BrightEdgeeServices/venvit "GitHub - Issue Counter"
+[gh_issues_lnk]: https://github.com/BrightEdgeeServices/venvit/issues "GitHub - Issue Counter"
+[gh_language_img]: https://img.shields.io/github/languages/top/BrightEdgeeServices/venvit "GitHub - Top Language"
+[gh_language_lnk]: https://github.com/BrightEdgeeServices/venvit "GitHub - Top Language"
+[gh_last_commit_img]: https://img.shields.io/github/last-commit/BrightEdgeeServices/venvit/master "GitHub - Last Commit"
+[gh_last_commit_lnk]: https://github.com/BrightEdgeeServices/venvit/commit/master "GitHub - Last Commit"
+[maintenance_y_img]: https://img.shields.io/badge/Maintenance%20Intended-%E2%9C%94-green.svg?style=flat-square "Maintenance - intended"
+[maintenance_y_lnk]: http://unmaintained.tech/ "Maintenance - intended"
+[pre_commit_ci_img]: https://img.shields.io/github/actions/workflow/status/BrightEdgeeServices/venvit/01-pre-commit-and-document-check.yml?label=pre-commit "Pre-Commit"
+[pre_commit_ci_lnk]: https://github.com/BrightEdgeeServices/venvit/blob/master/.github/workflows/01-pre-commit-and-document-check.yml "Pre-Commit"
+[semver_link]: https://semver.org/ "Sentic Versioning - 2.0.0"
+[semver_pic]: https://img.shields.io/badge/Semantic%20Versioning-2.0.0-brightgreen.svg?style=flat-square "Sentic Versioning - 2.0.0"
+