Skip to content

Commit 70b7038

Browse files
Tracks12Tracks12
authored
Merge pull request #8 from Tracks12/dev
Fixes, feature, documentation about core, tools & main script
2 parents 293115d + dc8d784 commit 70b7038

File tree

13 files changed

+549
-105
lines changed

13 files changed

+549
-105
lines changed

‎CONTRIBUTING.md

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# CONTRIBUTING
22

3+
[Back to index](README.md)
4+
35
## Coding Guidelines – toolsManager.py
46

57
This document defines the best development practices to follow when contributing to the project.
@@ -20,7 +22,7 @@ This document defines the best development practices to follow when contributing
2022
### 🧱 Tool Writing Convention
2123

2224
- Each tool must:
23-
- be in a separate file under tools/,
25+
- be in a separate file under `tools/`,
2426
- have the same name as the class (in PascalCase),
2527
- inherit from core.tool.Tool,
2628
- must implement the run() method.
@@ -59,22 +61,39 @@ class Hello(Tool):
5961

6062
self._run(args)
6163

62-
def _sayHello(user: str) -> bool:
63-
print(f"Hello {user} ! :D")
64+
def _sayHello(self, args: list[str]) -> bool:
65+
print(f"Hello world :D")
6466
return(True)
6567
```
6668

6769
#### 🚨 Non-compliant example:
6870

6971
```python
72+
# ❌ Missing environment & encoding declarations
73+
7074
# tools/hello.py
7175

7276
# ❌ Missing inheritance from Tool
7377
class Hello:
74-
def run(self):
75-
...
78+
79+
# ❌ Missing Tool porperties command, name, path & version
80+
81+
def __init__(self, a: list[str]): # ❌ Naming mistake on args parameters
82+
super().__init__()
83+
84+
# ❌ Missing init properties _args & _execs
85+
86+
self.hey(a) # ❌ Missing _run(args) method
87+
88+
# ❌ Bad name compliance
89+
def hey(self, args: list[str]) -> bool:
90+
print(f"Goodbye world :(")
91+
return(True)
7692
```
7793

94+
> [!Tip]
95+
> You can create you own tool by typing `$ python main.py -g`
96+
7897
## 🧪 Tests
7998

8099
- Tests are currently manual.
@@ -90,7 +109,7 @@ class Hello:
90109
## 🔁 GitFlow
91110

92111
- Each new tool or feature must start from a dedicated branch from dev.
93-
- Branches must be named feature/tool-name or fix/issue.
112+
- Branches must be named `feature/tool-name` or `hotfix/issue`.
94113
- Always rebase before merging to dev.
95114
- The master branch should only receive tested and stable code.
96115
- Each merge to master must be accompanied by a versioned tag (v1.2.0, etc.).
@@ -106,4 +125,6 @@ class Hello:
106125
## 🤝 Contribution
107126

108127
- Forks, pull requests, and issues welcome.
109-
- Please respect the structure and naming, and keep the code readable.
128+
- Please respect the structure and naming, and keep the code readable.
129+
130+
[Back to index](README.md)

‎README.md

Lines changed: 168 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,86 +1,207 @@
1-
# **toolsManager.py**
2-
3-
Un multi-outils disposant de modèle générique permettant de développer des outils de gestion comme WSLBuilder pour la gestion des instances WSL construite à l'aide d'images exportés depuis Docker
4-
5-
## Sommaire
6-
7-
1. [Aperçu](#aperçu)
8-
2. [Pré-requis](#pré-requis)
9-
- [Dépendances](#dépendances)
10-
- [WSL / Docker](#wsl--docker)
11-
3. [Utilisations](#utilisations)
12-
- [Gestion des outils](#gestion-des-outils)
13-
- [Gestion WSL avec WSLBuilder](#gestion-des-images-wsl)
14-
4. [Options & Configurations](#options--configurations)
15-
6. [Licence](#licence)
16-
17-
## Aperçu
1+
# **ToolsManager.py**
2+
3+
A multi-tool with a generic template for developing management tools like WSLBuilder for managing WSL instances built using images exported from Docker.
4+
5+
## Summary
6+
7+
- [**ToolsManager.py**](#toolsmanagerpy)
8+
- [Summary](#summary)
9+
- [I. Preview](#i-preview)
10+
- [II. Prerequisites](#ii-prerequisites)
11+
- [II.1 Dependencies](#ii1-dependencies)
12+
- [III. Uses](#iii-uses)
13+
- [III.1 Command Prompt](#iii1-command-prompt)
14+
- [III.2 Main Program](#iii2-main-program)
15+
- [IV. Tool Management](#iv-tool-management)
16+
- [IV.1 Tool Structure](#iv1-tool-structure)
17+
- [IV.2 Tools Registry](#iv2-tools-registry)
18+
- [IV.3 Tools Index](#iv3-tools-index)
19+
- [V. Options \& Configurations](#v-options--configurations)
20+
- [VI. Contributing](#vi-contributing)
21+
- [VII. License](#vii-license)
22+
23+
## I. Preview
1824

1925
![preview](preview.gif)
2026

21-
[Sommaire](#sommaire)
27+
[Summary](#summary)
2228

23-
## Pré-requis
29+
## II. Prerequisites
2430

25-
L'installation de **[Python 3](https://www.python.org/downloads/)** est recommandé pour l'éxécution du script sur windows
31+
> [!Important]
32+
> Installing **[Python 3](https://www.python.org/downloads/)** is recommended to run this script on Windows.
2633
27-
[Sommaire](#sommaire)
34+
[Summary](#summary)
2835

29-
### Dépendances
36+
### II.1 Dependencies
3037

3138
- [base64.b64decode](https://docs.python.org/3/library/base64.html#base64.b64decode), [base64.b64encode](https://docs.python.org/3/library/base64.html#base64.b64encode)
3239
- [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)
33-
- [os.listdir](https://docs.python.org/3/library/os.html#os.listdir), [os.system](https://docs.python.org/3/library/os.html#os.system)
40+
- [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)
3441
- [platform.system](https://docs.python.org/3/library/platform.html#platform.system)
42+
- [re.split](https://docs.python.org/3/library/re.html#re.split)
3543
- [random.shuffle](https://docs.python.org/3/library/random.html#random.shuffle)
44+
- [readline](https://docs.python.org/3/library/readline.html)
45+
- [shutil.rmtree](https://docs.python.org/3/library/shutil.html#shutil.rmtree)
3646
- [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)
3747
- [time.sleep](https://docs.python.org/3/library/time.html#time.sleep)
48+
- [traceback.format_exc](https://docs.python.org/3/library/traceback.html#traceback.format_exc)
49+
50+
> [!Note]
51+
> [readline](https://docs.python.org/3/library/readline.html) is for multiline finder in linux system
52+
53+
[Summary](#summary)
54+
55+
## III. Uses
56+
57+
To use the tool manager, you need to open a terminal prompt and run the python script at the root of the project
58+
59+
> [!Important]
60+
> Some tools present in the registry have dependencies contained in the [`libs/`](libs/) folder in the form of a `*.rar` file, you must unzip them by typing the command `$ python setup.py`
61+
62+
### III.1 Command Prompt
63+
64+
Usage: `$ python main.py <argument>`
65+
66+
| Arguments | Values ​ ​| Descriptions |
67+
| --------------------- | ------------------- | ------------------------------------------- |
68+
| `-g`, `--generate` | - | Generate a tool with interactive inputs |
69+
| `-l`, `--list` | - | Display the list of Python tools |
70+
| `-s`, `--set` | `<prop>`, `<value>` | Apply new configuration value to a property |
71+
| `-t`, `--tool` | `<tool>` | Launch a tool |
72+
| `-h`, `--help` | - | Display the help menu |
73+
| `-D`, `--debug` | - | Run in debugger mode |
74+
| `-v`, `--version` | - | Display the program version |
75+
76+
[Summary](#summary)
77+
78+
### III.2 Main Program
79+
80+
Usage: `$ python main.py`
81+
82+
```
83+
_ _ __ __
84+
| | | | | \/ |
85+
| |_ ___ ___ | | _|_\ / | __ _ _ __ __ _ __ _ ___ _ __
86+
| __/ _ \ / _ \| |/ _/|\/| |/ _` | '_ \ / _` |/ _` |/ _ \ '__|
87+
| || (_) | (_) | _\ \ | | | (_| | | | | (_| | (_| | __/ |
88+
\__\___/ \___/|/___/_| |_|\__,_|_| |_|\__,_|\__, |\___|_|
89+
version: 0.1 |___/
90+
91+
List of commands:
92+
93+
(mat)rix
94+
(sh)ell
95+
(wb)wslbuilder
96+
97+
(s)ettings
98+
(v)ersion
99+
(h)elp
38100
39-
[Sommaire](#sommaire)
101+
(q)uit
40102
41-
### WSL / Docker
103+
(toolsManager.py)>
104+
```
105+
106+
[Summary](#summary)
107+
108+
## IV. Tool Management
109+
110+
[Summary](#summary)
111+
112+
### IV.1 Tool Structure
113+
114+
Here you will find a typical example of a tool structure:
115+
116+
```python
117+
#!/usr/bin/env python3
118+
# -*- coding: utf-8 -*-
119+
120+
# tools/hello.py
121+
122+
# Importation of the tool model
123+
from core.tool import Tool
124+
125+
class Hello(Tool):
126+
""" Say hello to the user
127+
"""
42128

43-
[Sommaire](#sommaire)
129+
command = (("hello", "hel"), "(hel)lo") # The launch command control by name or alias
130+
name = "Hello" # Tool name
131+
path = __file__ # Path of tool file
132+
version = "0.1a" # Tool version
44133

45-
## Utilisations
134+
def __init__(self, args: list[str]):
135+
# Initialization of Tool
136+
super().__init__()
46137

47-
Exécution du script: `$ python main.py <arg>`
138+
# Argument registry corresponding to lamdba registry index
139+
self._args = [
140+
(("-s", "--say-hello", ""), "Say a hello world")
141+
] + self._args[:]
48142

49-
| Arguments | Valeur | Descriptions |
50-
| ---------------------------- | ----------------------- | ---------------------------------- |
51-
| `-l`, `--list` | - | Affiche la liste des outils python |
52-
| `-t <tool>`, `--tool <tool>` | `<tool>` nom de l'outil | Lance un outil |
53-
| `-h`, `--help` | - | Affiche le menu d'aide |
54-
| `-D`, `--debug` | - | Exécution en mode debuger |
55-
| `-v`, `--version` | - | Affiche la version du programme |
143+
# Lamdba registry corresponding to argument registry index
144+
self._execs = [
145+
lambda x:self._sayHello(x)
146+
] + self._execs[:]
56147

57-
[Sommaire](#sommaire)
148+
# _run(args) method to lauch method in lambda registry with arguments
149+
# tips: you can rewrite the methode if you want to put some exception or rules to launch
150+
self._run(args)
58151

59-
### Gestion des outils
152+
def _sayHello(self, args: list[str]) -> bool:
153+
print(f"Hello world :D")
154+
return(True)
60155

61-
[Sommaire](#sommaire)
156+
# ...
157+
```
158+
159+
> [!Tip]
160+
> Since the last update, you can create you own tool by typing `$ python main.py -g`
161+
162+
[Summary](#summary)
163+
164+
### IV.2 Tools Registry
165+
166+
[Summary](#summary)
62167

63-
### Gestion WSL avec WSLBuilder
168+
### IV.3 Tools Index
64169

65-
[Sommaire](#sommaire)
170+
| Tool | Version |
171+
| -------------------------------- | ------- |
172+
| [WSLBuilder](docs/WSLBuilder.md) | v0.1a |
66173

67-
## Options & Configurations
174+
[Summary](#summary)
68175

69-
La configuration du programme se fait depuis le fichier **[config.json](config.json)** au format **json**, dans ce fichier vous pouvez l'**encodage des caractères** ainsi que l'affichage du splash screen.
176+
## V. Options & Configurations
177+
178+
The program is configured from the **[config.json](config.json)** file in **json** format. In this file, you can set the **character encoding** and the splash screen display.
70179

71180
```json
72181
{
182+
"colors": false,
73183
"encoding": "utf-8",
74184
"splash": true
75185
}
76186
```
77187

78-
Vous pouvez le modifier directement (ce qui est peu conseiller) ou bien passer par le programme de configuration avec **tous les choix des paramètres possible à l'option "Paramètres" du menu principal**.
188+
You can modify it directly (which is not recommended) or use the configuration program with **all possible parameter choices in the "Settings" option in the main menu**.
189+
190+
> [!Note]
191+
> You can manage settings with cli command `$ python main.py -s encoding utf-8` inside a shell
192+
>
193+
> Or directly in main config index by typing `settings` & `set encoding utf-8` inside the program
194+
195+
[Summary](#summary)
196+
197+
## VI. Contributing
198+
199+
If you to contribute to the project, you access to the coding guideline at [CONTRIBUTING.md](CONTRIBUTING.md)
79200

80-
[Sommaire](#sommaire)
201+
[Summary](#summary)
81202

82-
## Licence
203+
## VII. License
83204

84-
Code sous license [GPL v3](LICENSE)
205+
Code licensed under [GPL v3](LICENSE)
85206

86-
[Sommaire](#sommaire)
207+
[Summary](#summary)

‎core/__init__.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919

2020
from core.colors import Colors
2121
from core.config import ACCEPT_ENCODING, Config, getConfig, setConfig
22+
from core.generate import Generate
2223
from core.icons import Icons
2324
from core.tool import Tool
2425

‎core/colors.py

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@
1414
from platform import system
1515

1616
ENABLE_COLOR = bool(system() == "Linux")
17+
""" Color application state constant
18+
"""
1719

1820
try:
1921
with open(abspath("config.json"), "r", encoding="utf-8") as cfgFile:
@@ -24,6 +26,26 @@
2426
pass
2527

2628
class Colors:
29+
30+
""" CLI ASCII colors
31+
32+
Note:
33+
Colors was disabled if the `colors` of `config.json` was in False or system is Windows
34+
35+
Attributes:
36+
bold (str):
37+
italic (str):
38+
red (str):
39+
green (str):
40+
yellow (str):
41+
blue (str):
42+
purple (str):
43+
cyan (str):
44+
white (str):
45+
end (str):
46+
47+
"""
48+
2749
if(ENABLE_COLOR):
2850
bold : str = "\033[1m"
2951
italic : str = "\033[3m"

0 commit comments

Comments
 (0)