python-lab-toolkit 1.0.0__tar.gz

python_lab_toolkit-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Python Lab Toolkit Developers
+
+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.

python_lab_toolkit-1.0.0/PKG-INFO

@@ -0,0 +1,427 @@
+Metadata-Version: 2.1
+Name: python-lab-toolkit
+Version: 1.0.0
+Summary: A beginner-friendly CLI and toolkit to generate 52 complete Python lab solutions with automated dataset management.
+Author-email: Python Lab Toolkit Developers <dev@pylabtoolkit.org>
+License: MIT
+Project-URL: Homepage, https://github.com/pylabtoolkit/python-lab-toolkit
+Project-URL: Documentation, https://github.com/pylabtoolkit/python-lab-toolkit#readme
+Project-URL: Repository, https://github.com/pylabtoolkit/python-lab-toolkit.git
+Project-URL: Issues, https://github.com/pylabtoolkit/python-lab-toolkit/issues
+Keywords: education,python-lab,code-generator,data-science,cli
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Operating System :: OS Independent
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Provides-Extra: requests
+Requires-Dist: requests>=2.25.0; extra == "requests"
+Provides-Extra: labs
+Requires-Dist: requests>=2.25.0; extra == "labs"
+Requires-Dist: numpy>=1.20.0; extra == "labs"
+Requires-Dist: pandas>=1.3.0; extra == "labs"
+Requires-Dist: matplotlib>=3.4.0; extra == "labs"
+Requires-Dist: seaborn>=0.11.0; extra == "labs"
+Requires-Dist: scikit-learn>=1.0.0; extra == "labs"
+Requires-Dist: mlxtend>=0.19.0; extra == "labs"
+Requires-Dist: mysql-connector-python>=8.0.0; extra == "labs"
+
+# Python Lab Toolkit (`python-lab-toolkit`)
+
+[![PyPI Version](https://img.shields.io/badge/pypi-v1.0.0-blue.svg)](https://pypi.org/project/python-lab-toolkit/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Zero Comments in Generated Code](https://img.shields.io/badge/clean%20code-zero%20comments-brightgreen.svg)]()
+[![Offline Ready](https://img.shields.io/badge/offline-bundled%20datasets-success.svg)]()
+
+A beginner-friendly, production-quality Python package and CLI named `pylab` designed to generate complete, working, runnable solutions for all **52 Python laboratory questions** with automatic dataset downloading and verified offline support.
+
+---
+
+## Table of Contents
+1. [Key Features](#key-features)
+2. [Installation](#installation)
+3. [Quick Start](#quick-start)
+4. [Complete Command Reference](#complete-command-reference)
+5. [The 52 Lab Questions Catalog](#the-52-lab-questions-catalog)
+6. [Automated Dataset Management](#automated-dataset-management)
+7. [Offline Installation & Laboratory Bundle](#offline-installation--laboratory-bundle)
+8. [Database Configuration (SQLite & MySQL)](#database-configuration-sqlite--mysql)
+9. [CGI Web Handlers and Local Test Servers](#cgi-web-handlers-and-local-test-servers)
+10. [Troubleshooting & FAQ](#troubleshooting--faq)
+11. [Development & Automated Testing](#development--automated-testing)
+12. [PyPI Publication Guide](#pypi-publication-guide)
+13. [License & Dataset Attribution](#license--dataset-attribution)
+
+---
+
+## 1. Key Features
+
+- **Short, Intuitive Commands**: Generate any project with simple commands like `pylab q1`, `pylab q12`, `pylab q49`.
+- **Zero Comments in Generated Code**: In accordance with clean code standards, generated Python source code contains **no explanatory inline comments, decorative comments, or header comments**, remaining self-explanatory through readable structure and expressive naming.
+- **Real, Runnable Python Files**: Generates real files on disk (not hidden functions or stubs) that students and instructors can inspect, run, and modify.
+- **Automated Dataset Handling**: Automatically downloads datasets when missing or instantly extracts verified bundled datasets when offline.
+- **100% Offline Capable**: Small verified copies of all required datasets (`winequality-red.csv`, `iris.csv`, `breast-cancer.csv`, `groceries.csv`, `Data.csv`, `dirtydata.csv`, `alphabet_stock_data.csv`, `rainfall.csv`, `students.csv`) are bundled inside the package wheel.
+- **Zero External Dependencies for Generator**: The `pylab` CLI and generator depend strictly on the Python standard library. It installs anywhere instantly without dependency conflicts.
+- **Accidental Overwrite Protection**: Existing user files are never silently overwritten. Use `--force` to deliberately replace files.
+- **Built-in System Doctor**: Run `pylab doctor` to check Python versions, directory permissions, and optional scientific libraries.
+
+---
+
+## 2. Installation
+
+### Standard Installation via pip
+```bash
+python -m pip install python-lab-toolkit
+```
+
+### Optional Scientific Libraries
+The core toolkit runs anywhere on standard Python. If you want to execute machine learning, plotting, or numerical labs (Q23, Q31-Q52), install the scientific packages:
+```bash
+python -m pip install -r requirements-labs.txt
+```
+Or install specific dependencies per question:
+```bash
+pylab install-deps q49
+```
+
+---
+
+## 3. Quick Start
+
+### 1. View Available Questions
+```bash
+pylab list
+```
+
+### 2. Generate a Single Question
+Generate the modular text analysis lab (Question 12):
+```bash
+pylab q12
+```
+Output:
+```text
+Question 12 generated successfully.
+
+Project: q12_text_analysis/
+
+Files:
+  text_preprocessor.py
+  text_analyzer.py
+  main_analyzer.py
+  README.md
+
+Run:
+  python q12_text_analysis/main_analyzer.py
+```
+
+### 3. Run the Generated Program
+```bash
+python q12_text_analysis/main_analyzer.py
+```
+
+### 4. Generate Machine Learning Labs with Automatic Datasets
+Generate the 22-step Wine Quality regression pipeline:
+```bash
+pylab q49
+```
+This automatically obtains `winequality-red.csv` and `winequality-white.csv`, creates `results/`, and generates `wine_regression.py` and `README.md`.
+
+---
+
+## 4. Complete Command Reference
+
+| Command | Description |
+| :--- | :--- |
+| `pylab list` | Display all 52 registered questions with numbers, titles, and categories. |
+| `pylab list --category <cat>` | Filter questions by category (`fundamentals`, `oop`, `pandas`, etc.). |
+| `pylab q<N>` | Generate Question `<N>` (e.g. `pylab q1`, `pylab q25`, `pylab q49`). |
+| `pylab q<N> --force` | Overwrite existing project files. |
+| `pylab q<N> --offline` | Force usage of bundled offline datasets. |
+| `pylab q<N> --output-dir <dir>` | Generate the project inside a specified directory. |
+| `pylab category <cat>` | Generate all questions belonging to a specific category. |
+| `pylab all` | Generate all 52 questions (prompts for confirmation). |
+| `pylab all --yes` | Generate all 52 questions non-interactively. |
+| `pylab doctor` | Inspect environment, Python version, directory write permissions, and libraries. |
+| `pylab datasets` | Display status and metadata for all bundled and downloadable datasets. |
+| `pylab install-deps <q>` | Check and install missing optional pip packages for a specific question. |
+| `pylab version` | Show the installed toolkit version. |
+| `pylab --help` | Display CLI help and options. |
+
+---
+
+## 5. The 52 Lab Questions Catalog
+
+### Python Fundamentals (Questions 1–11)
+- **Q1 (`q01_variable_name_validator`)**: Validate identifier rules and check reserved keywords using `keyword.iskeyword()`.
+- **Q2 (`q02_single_number`)**: Find the unique integer in an array where all other integers appear twice using XOR ($O(n)$ time, $O(1)$ space).
+- **Q3 (`q03_string_operations`)**: Implement `process_string()` to display uppercase, lowercase, length, slicing reversal `[::-1]`, and palindrome status.
+- **Q4 (`q04_menu_string_processor`)**: Menu-driven program for substring checking, character occurrence counting, substring replacement, and uppercase conversion.
+- **Q5 (`q05_phonebook`)**: Dictionary-based contact management supporting Add, Update, Search, Delete, and Display.
+- **Q6 (`q06_simple_calculator`)**: Arithmetic calculator supporting `+`, `-`, `*`, `/`, `//`, `%`, `**` with zero-division handling.
+- **Q7 (`q07_session_attendees`)**: Set operations on conference attendees: Union, Intersection, AI-only, and Cybersecurity-only.
+- **Q8 (`q08_number_properties`)**: Functions verifying Even/Odd, Palindrome, Armstrong numbers, Prime numbers, and Perfect numbers.
+- **Q9 (`q09_greet_people`)**: Variable argument function `greet_people(*names)` handling zero, one, or multiple parameters.
+- **Q10 (`q10_password_strength`)**: Password validator testing length, digits, uppercase, lowercase, and special characters with detailed deficiency reporting.
+- **Q11 (`q11_recursion`)**: Recursive sum and recursive factorial evaluated on $n = 5, 10, 18$.
+
+### Modular Programming (Question 12)
+- **Q12 (`q12_text_analysis`)**: Multi-module architecture with `text_preprocessor.py`, `text_analyzer.py`, and `main_analyzer.py` displaying required function docstrings via `__doc__`.
+
+### Object-Oriented Programming (Questions 13–18)
+- **Q13 (`q13_student_class`)**: `Student` class with `name`, `roll_number`, `course`, and `display()`.
+- **Q14 (`q14_circle_class`)**: `Circle` class with radius, `area()`, and `circumference()` methods using `math.pi`.
+- **Q15 (`q15_employee_salary`)**: `Employee` gross salary calculator with basic pay, HRA (20%), and DA (10%).
+- **Q16 (`q16_smart_calculator`)**: `SmartCalculator` demonstrating default arguments, `*args` multiplication, and polymorphic type dispatch.
+- **Q17 (`q17_complex_number`)**: `ComplexNumber` class with `+` (`__add__`) and `==` (`__eq__`) operator overloading.
+- **Q18 (`q18_vehicle_inheritance`)**: `Vehicle` base class and `Car` derived class with method overriding and `super()`.
+
+### Files, Exceptions, and Dates (Questions 19–22)
+- **Q19 (`q19_file_word_counter`)**: Read text file, count lines, words, characters, find top 5 frequent words, and handle file exceptions. Includes `sample.txt`.
+- **Q20 (`q20_custom_exception_age`)**: Custom exception `InvalidAgeException` validating ages between 18 and 60.
+- **Q21 (`q21_transaction_handling`)**: Robust banking transaction demonstrating `try`, `except`, `else`, and `finally` blocks.
+- **Q22 (`q22_date_formatter`)**: Date parser converting `dd-mm-yyyy` to `MonthName dd, yyyy` with invalid calendar date detection.
+
+### CSV Processing (Questions 23–24)
+- **Q23 (`q23_rainfall_analysis`)**: Read rainfall CSV data, calculate station averages, maximum rainfall record, standard deviation, and export results.
+- **Q24 (`q24_students_csv`)**: Manage `students.csv`, find highest-scoring student, and compute class average marks.
+
+### Database Systems (Questions 25–26)
+- **Q25 (`q25_sqlite_library`)**: SQLite Library Management system with parameterized single inserts, `executemany()` batch inserts, category queries, and menu CLI.
+- **Q26 (`q26_mysql_employee`)**: MySQL Employee Management system with parameterized queries, salary filtering (> ₹50,000), and secure environment credentials.
+
+### REST API & Networking (Question 27)
+- **Q27 (`q27_crudcrud_api`)**: Functional `requests`-based REST client performing Create, Read, Update, and Delete on students. Includes built-in `mock_server.py` for offline testing!
+
+### CGI & Web Applications (Questions 28–30)
+- **Q28 (`q28_cgi_login`)**: HTML login form and Python CGI handler displaying welcome response, with built-in `server.py`.
+- **Q29 (`q29_cgi_registration`)**: MSc registration form and Python CGI script returning formatted admission receipt.
+- **Q30 (`q30_cgi_crud`)**: Web-based database CRUD portal backed by SQLite, HTML frontend, and Python CGI HTTP server.
+
+### NumPy and Pandas Numerical Analysis (Questions 31–43)
+- **Q31 (`q31_numpy_matrix_operations`)**: Array 1–20 reshaped to 4×5, transpose, total/row/column sums, and even number extraction.
+- **Q32 (`q32_numpy_slicing_reversal`)**: 5×5 array (1–25) submatrix slicing, row slicing, column slicing, and axis reversals.
+- **Q33 (`q33_pandas_student_pass_fail`)**: Convert student marks Series to DataFrame, classify Pass/Fail, and filter passing students.
+- **Q34 (`q34_pandas_employee_salary`)**: Departmental salary analysis computing average salary per department and top earner.
+- **Q35 (`q35_pandas_sales_barchart`)**: 6 months sales table for 3 products, detecting top month, and plotting bar chart to `results/`.
+- **Q36 (`q36_pandas_weather_plot`)**: 7-day weather table calculating average temperature and total rainfall, plotting temperature trend line.
+- **Q37 (`q37_pandas_age_categorization`)**: Continuous age categorization using `pd.cut()` with mismatch detection.
+- **Q38 (`q38_pandas_concat_rows`)**: Concatenate two student DataFrames along rows (`axis=0`).
+- **Q39 (`q39_pandas_concat_cols`)**: Combine student DataFrames along columns (`axis=1`).
+- **Q40 (`q40_pandas_concat_merge`)**: Concatenate student batches and merge with exam scores DataFrame on `student_id`.
+- **Q41 (`q41_pandas_join_operations`)**: Relational join operations: Inner, Left, Right, and Outer joins with detailed semantics explanation.
+- **Q42 (`q42_pandas_groupby_school`)**: Group school records by school code, compute mean/min/max age, and inspect GroupBy object type.
+- **Q43 (`q43_pandas_groupby_multi`)**: Multi-column GroupBy (`['school_code', 'class']`) computing group counts with `size()`.
+
+### Visualization and Preprocessing (Questions 44–48)
+- **Q44 (`q44_alphabet_stock_visualization`)**: Alphabet stock historical data filtering, line plots, volume bar plot, stacked OHLC histogram, and scatter correlation.
+- **Q45 (`q45_multi_plot_demonstration`)**: 2×2 multi-plot demonstration grid (waveform, categories, scatter, histogram).
+- **Q46 (`q46_dataframe_barchart`)**: Grouped categorical bar plot with value annotations and legends.
+- **Q47 (`q47_data_preprocessing`)**: Impute missing numerical values (`SimpleImputer`), One-Hot encode categorical features, and standard scale features (`StandardScaler`).
+- **Q48 (`q48_dirtydata_cleaning`)**: Clean dirty dataset: fix inconsistent date formats, impute null calories, correct outlier duration, and drop duplicates.
+
+### Machine Learning & Data Mining Pipelines (Questions 49–52)
+- **Q49 (`q49_wine_quality_regression`)**: Full 22-step regression pipeline on red and white wine: data integration, correlation heatmap, feature scaling, Linear Regression, Decision Tree Regressor, Random Forest Regressor, and $R^2$, MAE, MSE, RMSE evaluation.
+- **Q50 (`q50_breast_cancer_classification`)**: Breast cancer diagnosis classification, Random Forest feature ranking, top-feature reduction, and classifier comparison (Decision Tree, Random Forest, Logistic Regression) with confusion matrices and false-negative analysis.
+- **Q51 (`q51_iris_clustering`)**: Unsupervised clustering on Iris features: standardization, K-Means ($k = 2, 3, 4$), elbow method, and 2D PCA cluster visualization.
+- **Q52 (`q52_apriori_association_rules`)**: Market basket transaction processing with Apriori, frequent itemset generation, and association rules sorted by lift.
+
+---
+
+## 6. Automated Dataset Management
+
+When generating questions requiring datasets, `pylab` automatically acquires them:
+
+```text
+q49_wine_quality_regression/
+├── wine_regression.py
+├── winequality-red.csv          <-- Auto-acquired
+├── winequality-white.csv        <-- Auto-acquired
+├── README.md
+└── results/
+```
+
+### Dataset Registry
+| Dataset Filename | Used In | Official Source | Bundled Offline |
+| :--- | :--- | :--- | :--- |
+| `winequality-red.csv` | Q49 | UCI Machine Learning Repository | Yes |
+| `winequality-white.csv` | Q49 | UCI Machine Learning Repository | Yes |
+| `breast-cancer.csv` | Q50 | UCI Machine Learning Repository | Yes |
+| `iris.csv` | Q51 | UCI Machine Learning Repository | Yes |
+| `groceries.csv` | Q52 | Association Mining Market Baskets | Yes |
+| `Data.csv` | Q47 | ML Preprocessing Reference Data | Yes |
+| `dirtydata.csv` | Q48 | Data Cleaning Reference Data | Yes |
+| `alphabet_stock_data.csv` | Q44 | Financial Time Series Reference | Yes |
+| `rainfall.csv` | Q23 | Weather Station Records | Yes |
+| `students.csv` | Q24 | Student Grades Records | Yes |
+
+To view dataset status at any time, run:
+```bash
+pylab datasets
+```
+
+---
+
+## 7. Offline Installation & Laboratory Bundle
+
+In lab environments where internet access is unavailable or restricted, you can prepare an offline installation bundle.
+
+### Step 1: Prepare the Offline Wheels Folder (on an internet-connected machine)
+```bash
+mkdir -p offline_bundle/wheels
+python -m pip download -d offline_bundle/wheels python-lab-toolkit
+python -m pip download -d offline_bundle/wheels -r requirements-labs.txt
+```
+
+### Step 2: Install Completely Offline in the Laboratory
+Transfer the `offline_bundle` folder to your offline laboratory computers and install:
+```bash
+python -m pip install --no-index --find-links ./offline_bundle/wheels python-lab-toolkit
+```
+
+### Step 3: Run Generation Offline
+```bash
+pylab q49 --offline
+```
+The toolkit will immediately use the verified bundled datasets stored inside the package wheel.
+
+---
+
+## 8. Database Configuration (SQLite & MySQL)
+
+### SQLite (Q25 & Q30)
+SQLite is built into Python. No installation, server configuration, or credentials are required. The database files (`library.db` and `cgi_records.db`) are created automatically in the project folder.
+
+### MySQL (Q26)
+Question 26 integrates with a MySQL database.
+To run Question 26 against your MySQL server:
+1. Start your local MySQL service (e.g. `sudo systemctl start mysqld` or through XAMPP / MySQL Workbench).
+2. Configure credentials using environment variables:
+   ```bash
+   export MYSQL_HOST="localhost"
+   export MYSQL_USER="root"
+   export MYSQL_PASSWORD="your_password"
+   export MYSQL_DATABASE="company_db"
+   ```
+3. Run the manager:
+   ```bash
+   python q26_mysql_employee/mysql_employee_manager.py
+   ```
+   Or run the automated demonstration:
+   ```bash
+   python q26_mysql_employee/mysql_employee_manager.py --demo
+   ```
+
+---
+
+## 9. CGI Web Handlers and Local Test Servers
+
+Questions 28, 29, and 30 demonstrate CGI forms and web applications. Each generated project contains a self-contained local Python HTTP server (`server.py`).
+
+To test in your browser:
+```bash
+cd q28_cgi_login
+python server.py
+```
+Open `http://localhost:8080` in your web browser. You can enter credentials, submit forms, and inspect the CGI responses immediately!
+
+---
+
+## 10. Troubleshooting & FAQ
+
+### "No module named 'numpy'" or other scientific library error
+The code generator does not require scientific libraries, but running the generated script might. Run:
+```bash
+pylab install-deps <question_number>
+# Example: pylab install-deps q49
+```
+Or install all lab dependencies at once:
+```bash
+pip install -r requirements-labs.txt
+```
+
+### "The directory already contains existing files"
+To prevent accidental loss of code, `pylab` will not overwrite existing directories. Pass `--force`:
+```bash
+pylab q12 --force
+```
+
+### How can I check if my Python environment is ready?
+Run the built-in system diagnostics tool:
+```bash
+pylab doctor
+```
+
+---
+
+## 11. Development & Automated Testing
+
+### Running Tests
+The toolkit includes a 56-test automated test suite verifying registry integrity, file generation, syntax correctness, comment absence (Rule A), CLI subcommands, database queries, and program execution.
+
+Run the test suite using standard Python:
+```bash
+python -m unittest discover -s tests -v
+```
+
+### Building Distribution Packages
+Build modern wheel and source distributions into `dist/`:
+```bash
+python setup.py sdist bdist_wheel
+```
+
+---
+
+## 12. PyPI Publication Guide
+
+To publish `python-lab-toolkit` to PyPI:
+
+### Step 1: Install Build and Twine Tools
+```bash
+python -m pip install --upgrade build twine
+```
+
+### Step 2: Build Clean Artifacts
+```bash
+rm -rf dist build src/*.egg-info
+python -m build
+```
+
+### Step 3: Check Package Metadata with Twine
+```bash
+python -m twine check dist/*
+```
+
+### Step 4: Securely Upload to PyPI using an API Token
+```bash
+python -m twine upload --username __token__ dist/*
+```
+When prompted for your password, enter your PyPI API token (`pypi-AgEI...`).
+
+> [!IMPORTANT]
+> Never hardcode API tokens or passwords in configuration files or version control. Always use `__token__` and enter the secret token interactively or via the `TWINE_PASSWORD` environment variable.
+
+---
+
+## 13. License & Dataset Attribution
+
+### Package License
+This software is distributed under the **MIT License**. See [LICENSE](LICENSE) for full details.
+
+### Dataset Attributions
+- **Wine Quality Datasets (`winequality-red.csv`, `winequality-white.csv`)**: P. Cortez, A. Cerdeira, F. Almeida, T. Matos, and J. Reis (2009). Modeling wine preferences by data mining from physicochemical properties. *Decision Support Systems*, Elsevier, 47(4):547-553.
+- **Breast Cancer Wisconsin (Diagnostic) Dataset (`breast-cancer.csv`)**: Dr. William H. Wolberg, W. Nick Street, and Olvi L. Mangasarian. UCI Machine Learning Repository.
+- **Iris Dataset (`iris.csv`)**: R.A. Fisher (1936). The use of multiple measurements in taxonomic problems. *Annals of Eugenics*, 7, Part II, 179-188.
+- **Groceries Dataset (`groceries.csv`)**: Michael Hahsler, Kurt Hornik, and Christian Buchta (2005). arules - Mining Association Rules and Frequent Itemsets.