Merge pull request #14 from Tracks12/dev

v0.3

Author: Tracks12

CONTRIBUTING.md

@@ -45,16 +45,15 @@ class Hello(Tool):
 	version	= "0.1a"
 
 	def __init__(self, args: list[str]):
-		super().__init__()
-
 		self._args	= [
 			(("-s", "--say-hello", "<user>"), "Say hello to the user")
-		] + self._args[:]
+		]
 
 		self._execs = [
 			lambda x:self._sayHello(x)
-		] + self._execs[:]
+		]
 
+		super().__init__()
 		self._run(args)
 
 	def _sayHello(self, args: list[str]) -> bool:
@@ -75,7 +74,7 @@ class Hello:
 	# ❌ Missing Tool porperties command, name, path & version
 
 	def __init__(self, a: list[str]): # ❌ Naming mistake on args parameters
-		super().__init__()
+		super().__init__() # ❌ Bad super init position
 
 		# ❌ Missing init properties _args & _execs
 
@@ -106,6 +105,11 @@ class Hello:
 
 - Each new tool or feature must start from a dedicated branch from dev.
 - Branches must be named `feature/tool-name` or `hotfix/issue`.
+- Commit must be named like these:
+  - `doc(scope): ...` for documentation updates
+  - `feat(scope): ...` for feature developed
+  - `fix(scope): ...` for fix applied
+  - `refacto(scope): ...` for refactoring or code optimization
 - Always rebase before merging to dev.
 - The master branch should only receive tested and stable code.
 - Each merge to master must be accompanied by a versioned tag (v1.2.0, etc.).

README.md

@@ -5,20 +5,20 @@ A multi-tool with a generic template for developing management tools like WSLBui
 ## Summary
 
 - [**ToolsManager.py**](#toolsmanagerpy)
-	- [Summary](#summary)
-	- [I. Preview](#i-preview)
-	- [II. Prerequisites](#ii-prerequisites)
-		- [II.1 Dependencies](#ii1-dependencies)
-	- [III. Uses](#iii-uses)
-		- [III.1 Command Prompt](#iii1-command-prompt)
-		- [III.2 Main Program](#iii2-main-program)
-	- [IV. Tool Management](#iv-tool-management)
-		- [IV.1 Tool Structure](#iv1-tool-structure)
-		- [IV.2 Tools Registry](#iv2-tools-registry)
-		- [IV.3 Tools Index](#iv3-tools-index)
-	- [V. Options \& Configurations](#v-options--configurations)
-	- [VI. Contributing](#vi-contributing)
-	- [VII. License](#vii-license)
+  - [Summary](#summary)
+  - [I. Preview](#i-preview)
+  - [II. Prerequisites](#ii-prerequisites)
+    - [II.1 Dependencies](#ii1-dependencies)
+  - [III. Uses](#iii-uses)
+    - [III.1 Command Prompt](#iii1-command-prompt)
+    - [III.2 Main Program](#iii2-main-program)
+  - [IV. Tool Management](#iv-tool-management)
+    - [IV.1 Tool Structure](#iv1-tool-structure)
+    - [IV.2 Tools Registry](#iv2-tools-registry)
+    - [IV.3 Tools Index](#iv3-tools-index)
+  - [V. Options \& Configurations](#v-options--configurations)
+  - [VI. Contributing](#vi-contributing)
+  - [VII. License](#vii-license)
 
 ## I. Preview
 
@@ -39,16 +39,16 @@ A multi-tool with a generic template for developing management tools like WSLBui
 - [json.loads](https://docs.python.org/3/library/json.html#json.loads), [json.dumps](https://docs.python.org/3/library/json.html#json.dumps), [json.load](https://docs.python.org/3/library/json.html#json.load), [json.dump](https://docs.python.org/3/library/json.html#json.dump)
 - [os.listdir](https://docs.python.org/3/library/os.html#os.listdir), [os.mkdir](https://docs.python.org/3/library/os.html#os.mkdir), [os.remove](https://docs.python.org/3/library/os.html#os.remove), [os.rmdir](https://docs.python.org/3/library/os.html#os.rmdir), [os.system](https://docs.python.org/3/library/os.html#os.system), [os.path](https://docs.python.org/3/library/os.path.html#os.path)
 - [platform.system](https://docs.python.org/3/library/platform.html#platform.system)
-- [re.split](https://docs.python.org/3/library/re.html#re.split)
 - [random.shuffle](https://docs.python.org/3/library/random.html#random.shuffle)
+- [re.split](https://docs.python.org/3/library/re.html#re.split)
 - [readline](https://docs.python.org/3/library/readline.html)
+- [requests](https://pypi.org/project/requests/)
 - [shutil.rmtree](https://docs.python.org/3/library/shutil.html#shutil.rmtree)
 - [sys.argv](https://docs.python.org/3/library/sys.html#sys.argv), [sys.version_info](https://docs.python.org/3/library/sys.html#sys.version_info)
 - [time.sleep](https://docs.python.org/3/library/time.html#time.sleep)
 - [traceback.format_exc](https://docs.python.org/3/library/traceback.html#traceback.format_exc)
 
-> [!Note]
-> [readline](https://docs.python.org/3/library/readline.html) is for multiline finder in linux system
+> [!Note] > [readline](https://docs.python.org/3/library/readline.html) is for multiline finder in linux system
 
 [Summary](#summary)
 
@@ -65,21 +65,21 @@ To use the tool manager, you need to open a terminal prompt and run the python s
 
 Usage: `$ python main.py <argument>`
 
-| Arguments             | Values ​             ​| Descriptions                                |
-| --------------------- | ------------------- | ------------------------------------------- |
-| `-g`, `--generate`    | -                   | Generate a tool with interactive inputs     |
-| `-l`, `--list`        | -                   | Display the list of Python tools            |
-| `-s`, `--set`         | `<prop>`, `<value>` | Apply new configuration value to a property |
-| `-t`, `--tool`        | `<tool>`            | Launch a tool                               |
-| `-h`, `--help`        | -                   | Display the help menu                       |
-| `-D`, `--debug`       | -                   | Run in debugger mode                        |
-| `-v`, `--version`     | -                   | Display the program version                 |
+| Arguments          | Values ​ ​          | Descriptions                                |
+| ------------------ | ------------------- | ------------------------------------------- |
+| `-g`, `--generate` | -                   | Generate a tool with interactive inputs     |
+| `-l`, `--list`     | -                   | Display the list of Python tools            |
+| `-s`, `--set`      | `<prop>`, `<value>` | Apply new configuration value to a property |
+| `-t`, `--tool`     | `<tool>`            | Launch a tool                               |
+| `-h`, `--help`     | -                   | Display the help menu                       |
+| `-D`, `--debug`    | -                   | Run in debugger mode                        |
+| `-v`, `--version`  | -                   | Display the program version                 |
 
 [Summary](#summary)
 
 ### III.2 Main Program
 
-Usage: `$ python main.py`
+Execute the main script at the root of project folder with `$ python main.py`, when you arrived at the main menu, you can run directly all tools in registry
 
 ```
    _              _    __  __
@@ -88,12 +88,13 @@ Usage: `$ python main.py`
   | __/ _ \ / _ \| |/ _/|\/| |/ _` | '_ \ / _` |/ _` |/ _ \ '__|
   | || (_) | (_) | _\ \ |  | | (_| | | | | (_| | (_| |  __/ |
    \__\___/ \___/|/___/_|  |_|\__,_|_| |_|\__,_|\__, |\___|_|
-     version: 0.1                               |___/
+     version: 0.3                               |___/
 
  List of commands:
 
  (mat)rix
  (sh)ell
+ (tr)anslator
  (wb)wslbuilder
 
  (s)ettings
@@ -109,6 +110,17 @@ Usage: `$ python main.py`
 
 ## IV. Tool Management
 
+All tools can be created with `$ python main.py -g`, after that, the program ask you 3 questions about the new tool you want to create, once the tool was created, you must import it and enter it in the tool registry at [`tools/__init__.py`](tools/__init__.py)
+
+Once the tool is declared in the [tools registry](#iv2-tools-registry), you can call it in the main program or as a command argument with `-t`
+
+To recognize a tool, it is imperative to follow the Tool class nomenclature, while providing the following metadata for proper management:
+
+- `command`: a tuple that references the tool's command and main alias, along with its acronym for display in the main menu
+- `name`: a string representing the tool's name
+- `path`: the absolute path to the tool's file (usually declared with the constant `__file__`)
+- `version`: a string representing the tool's version (e.g., 0.1a, 1.0, 2.0)
+
 [Summary](#summary)
 
 ### IV.1 Tool Structure
@@ -134,18 +146,18 @@ class Hello(Tool):
 	version	= "0.1a" # Tool version
 
 	def __init__(self, args: list[str]):
-		# Initialization of Tool
-		super().__init__()
-
 		# Argument registry corresponding to lamdba registry index
 		self._args	= [
 			(("-s", "--say-hello", ""), "Say a hello world")
-		] + self._args[:]
+		]
 
 		# Lamdba registry corresponding to argument registry index
 		self._execs = [
 			lambda x:self._sayHello(x)
-		] + self._execs[:]
+		]
+
+		# Initialization of Tool
+		super().__init__()
 
 		# _run(args) method to lauch method in lambda registry with arguments
 		# tips: you can rewrite the methode if you want to put some exception or rules to launch
@@ -165,14 +177,32 @@ class Hello(Tool):
 
 ### IV.2 Tools Registry
 
+To use the tool you just created, you must declare it in the tool registry by importing it into the [`tools/__init__.py`](tools/__init__.py) file and declaring it in the `TOOLS` constant
+
+```python
+from core.tool import Tool
+
+from tools.matrix import Matrix # Tool importation
+...
+
+TOOLS: tuple[Tool] = (
+	Matrix, # Tool declaration
+	...
+)
+""" Tools registry """
+```
+
+> [!note]
+> Eventually, this method of tool declaration will be automated in the tool generation script
+
 [Summary](#summary)
 
 ### IV.3 Tools Index
 
 | Tool                             | Version | Description                                |
 | -------------------------------- | ------- | ------------------------------------------ |
 | [Shell](docs/Shell.md)           | v1.0    | Prompt interface with custom schedules     |
-| [Translator](docs/Translator.md) | v1.0    | Translation tool manager                   |
+| [Translator](docs/Translator.md) | v1.1    | Translation tool manager                   |
 | [WSLBuilder](docs/WSLBuilder.md) | v1.1    | Managing Docker images compatible with WSL |
 
 [Summary](#summary)
@@ -193,7 +223,7 @@ You can modify it directly (which is not recommended) or use the configuration p
 
 > [!Note]
 > You can manage settings with cli command `$ python main.py -s encoding utf-8` inside a shell
-> 
+>
 > Or directly in main config index by typing `settings` & `set encoding utf-8` inside the program
 
 [Summary](#summary)

core/__init__.py

@@ -19,6 +19,7 @@
 
 from core.colors import Colors
 from core.config import ACCEPT_ENCODING, Config, getConfig, setConfig
+from core.exceptions import RequestError, ToolInitError, ValidationError
 from core.generate import Generate
 from core.icons import Icons
 from core.tool import Tool
@@ -27,7 +28,7 @@
 	"author": "Florian Cardinal",
 	"github": "https://github.com/Tracks12/toolsManager.py",
 	"name": "toolsManager.py",
-	"version": "0.1",
+	"version": "0.3",
 })
 """ Contains application information such as version, git commit hash, and other metadata
 """

core/exceptions.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+r""" Custom exception classes for application-level error handling.
+
+	This module provides a centralized place to define and manage reusable
+	exceptions across the codebase. These exceptions are intended to replace
+	standard Python or third-party exceptions with more meaningful, context-aware
+	errors suited to the specific needs of the application.
+
+	Can include (but is not limited to):
+	- Request/HTTP errors
+	- Validation or input errors
+	- Configuration errors
+
+"""
+
+class RequestError(Exception):
+
+	""" Raised when an HTTP request fails or returns an unexpected response.
+
+		Attributes:
+			message (str): Description of the error.
+			url (str): URL that triggered the exception.
+			status_code (int): HTTP status code (if available).
+
+	"""
+
+	def __init__(self, message: str, url: str = None, status_code: int = None):
+		super().__init__(message)
+
+		self.message		= str(message)
+		self.url			= str(url)
+		self.status_code	= int(status_code)
+
+	def __str__(self) -> str:
+		parts = list[str]([ f"RequestError: {self.message}" ])
+
+		if(self.url):
+			parts.append(f"URL: {self.url}")
+
+		if(self.status_code):
+			parts.append(f"Status: {self.status_code}")
+
+		return("\n\t| ".join(parts))
+
+class ToolInitError(Exception):
+
+	""" Raised when a tool fails to initialize properly.
+
+		Attributes:
+			tool_name (str): Name of the tool.
+			details (str): Explanation of the failure.
+
+	"""
+
+	def __init__(self, tool_name: str, details: str):
+		super().__init__(f"Failed to initialize tool '{tool_name}': {details}")
+
+		self.tool_name	= str(tool_name)
+		self.details	= str(details)
+
+class ValidationError(Exception):
+
+	""" Raised when an input or configuration value is invalid.
+
+		Attributes:
+			field (str): Name of the field or parameter in error.
+			reason (str): Explanation of why the value is invalid.
+
+	"""
+
+	def __init__(self, field: str, reason: str):
+		super().__init__(f"Validation failed for '{field}': {reason}")
+
+		self.field	= str(field)
+		self.reason	= str(reason)

core/generate.py

@@ -34,16 +34,15 @@ class {classname}(Tool):
 	version	= "0.1a"
 
 	def __init__(self, args: list[str]):
-		super().__init__()
-
 		self._args	= [
 			(("-s", "--say-hello", ""), "Say a hello world")
-		] + self._args[:]
+		]
 
 		self._execs = [
 			lambda x:self._sayHello(x)
-		] + self._execs[:]
+		]
 
+		super().__init__()
 		self._run(args)
 
 	def _sayHello(self, args: list[str]) -> bool: