added packages

Author: SaraFreitas-dev

Python_core/Packages/packages_guide.md

@@ -0,0 +1,292 @@
+# 📦 Python Packages Guide
+
+> Beginner-friendly documentation about Python packages, imports, modules, and project organization.
+
+This document explains:
+- what packages are
+- how imports work
+- `__init__.py`
+- package organization
+- absolute vs relative imports
+- common beginner mistakes
+- project structure examples
+
+---
+
+# 📚 Table of Contents
+
+- [📖 What is a Package?](#-what-is-a-package)
+- [📦 What is a Module?](#-what-is-a-module)
+- [🧱 Basic Package Structure](#-basic-package-structure)
+- [📥 Importing Modules](#-importing-modules)
+- [📌 __init__.py](#-__init__py)
+- [🌿 Absolute Imports](#-absolute-imports)
+- [🔗 Relative Imports](#-relative-imports)
+- [🛠️ Organizing Large Projects](#️-organizing-large-projects)
+- [📌 __init__.py Contents](#-__init__py-contents)
+- [⚠️ Common Beginner Mistakes](#️-common-beginner-mistakes)
+- [📚 Final Notes](#-final-notes)
+
+---
+
+# 📖 What is a Package?
+
+A package is a folder containing Python modules.
+
+Packages help:
+- organize code
+- separate logic
+- structure large projects
+- improve readability
+
+---
+
+# 📦 What is a Module?
+
+A module is simply:
+
+```text
+a Python file
+```
+
+Example:
+
+```text
+utils.py
+```
+
+This file itself is a module.
+
+---
+
+# 🧱 Basic Package Structure
+
+```text
+project/
+│
+├── main.py
+├── parser/
+│   ├── __init__.py
+│   ├── config_parser.py
+│   └── validator.py
+│
+└── render/
+    ├── __init__.py
+    └── draw.py
+```
+
+---
+
+# 📥 Importing Modules
+
+## Import Entire Module
+
+```python
+import math
+```
+
+Usage:
+
+```python
+math.sqrt(25)
+```
+
+---
+
+## Import Specific Function
+
+```python
+from math import sqrt
+```
+
+Usage:
+
+```python
+sqrt(25)
+```
+
+---
+
+# 📌 __init__.py
+
+`__init__.py` tells Python that a folder should behave like a package.
+
+Without it, imports may fail in some project structures.
+
+---
+
+# 🌿 Absolute Imports
+
+Absolute imports start from the project root.
+
+## Example
+
+```python
+from parser.config_parser import parse_config
+```
+
+---
+
+# 🔗 Relative Imports
+
+Relative imports use dots (`.`).
+
+## Example
+
+```python
+from .validator import validate_config
+```
+
+---
+
+# 🛠️ Organizing Large Projects
+
+Example organization:
+
+```text
+project/
+│
+├── core/
+├── parsing/
+├── render/
+├── utils/
+├── tests/
+└── assets/
+└── main.py
+```
+
+And each folder would have a __init__.py file to make it a package.
+
+---
+
+# 📌 __init__.py Contents
+
+In many Python projects, `__init__.py` is often left empty.
+
+Example:
+
+```python
+# __init__.py
+```
+
+This is completely normal and commonly used only to mark the folder as a package.
+
+---
+
+# Why Leave It Empty?
+
+An empty `__init__.py`:
+- keeps the package simple
+- avoids unnecessary imports
+- helps Python recognize the directory as a package
+
+---
+
+# What Can Be Inside __init__.py?
+
+Although often empty, it may also contain:
+- package imports
+- helper variables
+- package initialization code
+- exposed public functions/classes
+
+---
+
+# Example
+
+```python
+from .config_parser import parse_config
+from .validator import validate_config
+```
+
+This allows imports like:
+
+```python
+from parser import parse_config
+```
+
+instead of:
+
+```python
+from parser.config_parser import parse_config
+```
+
+---
+
+# Why This is Useful
+
+This can:
+- simplify imports
+- expose public APIs
+- improve package organization
+
+Very common in:
+- libraries
+- frameworks
+- large Python projects
+
+---
+
+# Good Practice
+
+For beginner projects:
+- keeping `__init__.py` empty is completely fine
+
+As projects grow larger:
+- it may be used to organize package exports and initialization logic
+
+
+---
+
+# ⚠️ Common Beginner Mistakes
+
+## ❌ Missing __init__.py
+
+Problem:
+
+```text
+ModuleNotFoundError
+```
+
+---
+
+## ❌ Circular Imports
+
+Example:
+
+```python
+# a.py imports b.py
+# b.py imports a.py
+```
+
+---
+
+## ❌ Running Files Directly
+
+Bad:
+
+```bash
+python3 parser/config_parser.py
+```
+
+Better:
+
+```bash
+python3 main.py
+```
+
+
+---
+
+# 📚 Final Notes
+
+Understanding packages is extremely important for modern Python development.
+
+Good package organization helps:
+- readability
+- maintainability
+- debugging
+- scalability
+- teamwork
+
+---

README.md

@@ -18,7 +18,7 @@ PYTHON_42_SCHOOL_DOCUMENTATION/
 ├── 🛠️ Makefile
 ├── 🎮 MLX-42lib
 ├── 🚀 Projects
-└── 🐍 Python_core
+└── 🐍 Python_core  # With concepts including Packages, OOP, etc.
 ```
 
 The repository contains multiple sections dedicated to Python core concepts, development tooling, MLX-related notes, and project documentation designed to support and explain newer 42 School Python projects.
@@ -59,6 +59,7 @@ The repository contains multiple sections dedicated to Python core concepts, dev
 - JSON validation
 - virtual environments
 - error handling
+- Packages
 
 ---