Skip to content

Commit 94d947b

Browse files
GiulioRussoGiulioRusso
committed
Add: Python-Project-Guide and Back to Index connections
1 parent 55d8ae2 commit 94d947b

File tree

3 files changed

+164
-2
lines changed

3 files changed

+164
-2
lines changed

‎Deep-Learning-Project-Guide.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1115,5 +1115,4 @@ net/
11151115

11161116
Go check [this repository](https://github.com/GiulioRusso/Deep-Learning-boilerplate) for a Deep Learning boilerplate project.
11171117

1118-
1119-
1118+
[Back to Index 🗂️](./README.md)

‎Machine-Learning-Project-Guide.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -493,3 +493,5 @@ These metrics provide an honest snapshot of generalisation performance and guide
493493
```
494494

495495
Go check [this repository](https://github.com/GiulioRusso/Machine-Learning-boilerplate) for a Machine Learning boilerplate project.
496+
497+
[Back to Index 🗂️](./README.md)

‎Python-Project-Guide.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
[Back to Index 🗂️](./README.md)
2+
3+
<center><h1>👨‍💻 Python Project Guide</h1></center>
4+
5+
A practical guide to organizing, documenting, and maintaining clean Python projects — whether for Deep Learning, Data Science, or Software Engineering.
6+
7+
<br>
8+
9+
# 1️⃣ Project Folder Structure
10+
11+
Always use a clean and modular structure:
12+
13+
```bash
14+
my_project/
15+
├── README.md # Project overview, installation, and usage
16+
├── requirements.txt # List of Python dependencies
17+
├── .gitignore # Files and folders to exclude from version control
18+
├── venv/ # Virtual environment (excluded from Git)
19+
├── config/ # Centralized configuration for paths, parameters, etc.
20+
│ └── config.yaml # YAML file storing configurable paths or hyperparameters
21+
├── src/ # Main application code (organized by function or logic)
22+
│ ├── main.py # Entry point script
23+
│ ├── dataset.py # Dataset loading and preprocessing logic
24+
│ ├── model.py # Model architecture definitions
25+
│ ├── train.py # Training loop
26+
│ └── utils.py # General utilities
27+
├── tests/ # Unit and integration tests
28+
│ └── test_*.py # Individual test files
29+
```
30+
31+
* `src/`: Contains your actual training, inference, and business logic.
32+
* `config/`: Stores one or more `.yaml` (for path structures), `.json`(for light data storage) or `.env` (for environment variables). These files can be easy loaded in your Python scripts with the libraries `yaml`, `json`and `dotenv` respectively.
33+
* `tests/`: Ensures all key functionality is verifiable.
34+
* `venv/`: Local project environment, kept out of version control.
35+
* `requirements.txt`: Captures dependencies used in the project.
36+
* `.gitignore`: Prevents accidental commits of logs, temp files, environments, etc.
37+
* `README.md`: Provides project setup, usage, and documentation.
38+
39+
> Optional directories like `notebooks/`, `scripts/`, or `data/` should be added only when necessary and clearly documented.
40+
41+
<br>
42+
43+
# 2️⃣ Function Documentation (PEP 257 Style)
44+
45+
Clear function documentation improves readability, usability, and maintainability. When writing your functions, you should:
46+
- Use type hints in the function signature.
47+
- Include a docstring that describes what the function does.
48+
- Use `:param` and `:return` tags to document each input and output.
49+
50+
Template Example:
51+
52+
```python
53+
def function(parameter_1: str,
54+
parameter_2: bool = False) -> List[float]:
55+
"""
56+
Load numerical data from a file.
57+
58+
:param parameter_1: Parameter 1 description.
59+
:param parameter_2: Parameter 2 description.
60+
61+
:return: Returned object.
62+
"""
63+
64+
# your code here
65+
66+
pass
67+
```
68+
69+
> Keep your descriptions short but clear. Mention any assumptions or side effects if needed.
70+
71+
This format is ideal for auto-generated documentation tools and makes code easier to navigate for collaborators and future-you.
72+
73+
<br>
74+
75+
# 3️⃣ Virtual Environments & Dependency Tracking
76+
77+
It's good practice to activate a virtual environment when working on any Python project, ensuring your dependencies remain isolated and controlled. All the dependencies are kept into a `requirements.txt` file that specify the name of the library used and eventually its version:
78+
79+
Example:
80+
81+
```bash
82+
Python>=3.8 # Python version
83+
torch>=1.13 # Package version greater or equal than
84+
numpy==2.2.3 # Exact version needed
85+
scikit-learn # No version specified (the latest for your Python will be used)
86+
```
87+
88+
You can automatically generate a `requirements.txt` with the `pipreqs` package:
89+
90+
```bash
91+
pip install pipreqs
92+
```
93+
94+
```bash
95+
pipreqs ./ # Scans your code and creates a minimal requirements.txt
96+
```
97+
98+
When starting a project or collaborating, you can install the requirements specified with:
99+
100+
```bash
101+
pip install -r requirements.txt
102+
```
103+
104+
<br>
105+
106+
# 4️⃣ Writing a clear README.md
107+
108+
Your `README.md` is the first place users, collaborators, and future-you will look to understand how your project works. It should serve as both a quick-start guide and high-level documentation. Recommended sections are:
109+
110+
- **Project Title and Description**.
111+
- **Installation**: List dependencies and how to install them.
112+
- **Configuration**: Explain how to configure the project. If using configuration files, include an example or point to one in the repository.
113+
- **Project Structure**: Briefly describe the folder structure and what each directory/file is responsible for.
114+
- **Usage**: Show how to run key scripts (e.g. training, testing, inference).
115+
116+
Here follow a good structure to describe your Python script:
117+
118+
```markdown
119+
### `your_script.py`
120+
121+
**Description**
122+
Briefly describe what this script does.
123+
_Example: This script trains a neural network on a dataset using the configuration defined in a YAML file._
124+
125+
**Requirements**
126+
List any files, pre-setup, or directories needed before running this script.
127+
128+
- Fill out the configuration file at `config/train_config.yaml`
129+
- Ensure the dataset is located in the `data/` directory
130+
- Create an empty `checkpoints/` folder for saving models
131+
132+
**Arguments**
133+
134+
| Argument | Type | Description | Required | Default |
135+
|------------------|---------|-----------------------------------------------|----------|-----------------|
136+
| `--config` | string | Path to the configuration file | Yes | - |
137+
| `--epochs` | int | Number of training epochs | No | `10` |
138+
| `--batch_size` | int | Size of each training batch | No | `64` |
139+
| `--save_dir` | string | Directory to save trained model checkpoints | No | `./checkpoints` |
140+
| `--eval_only` | flag | Run in evaluation mode only | No | `False` |
141+
142+
**Examples**
143+
144+
Train the model using a specific configuration:
145+
146+
```bash
147+
python your_script.py --config config/train_config.yaml --epochs 100
148+
```
149+
150+
Evaluate a pre-trained model:
151+
152+
```bash
153+
python your_script.py --config config/eval_config.yaml --eval_only
154+
```
155+
156+
**Notes**
157+
- Logging output will be saved to the `logs/` directory, if enabled in the config.
158+
- The script will automatically create the `save_dir` if it doesn't exist.
159+
```
160+
161+
[Back to Index 🗂️](./README.md)

0 commit comments

Comments
 (0)