Rain/framework_note
1
0
Fork 0
mirror of https://github.com/Rainyy21/framework_note.git synced 2026-10-11 01:10:28 -04:00
Code Issues Packages Projects Releases Wiki Activity

vault backup: 2026-05-30 16:02:33

Browse Source
This commit is contained in:
Rainyy21
2026-05-30 16:02:33 -04:00
commit 96449f8968
43 changed files with 2837 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
note/python/python_note/__init__.py explained.md
+152
View File
@@ -0,0 +1,152 @@
---
title: What is __init__.py?
created: 2026-05-22
tags:
- python
- python_note
- packaging
- reference
category: python_note
status: reference
up: "[[project/index]]"
related:
- "[[poetry_guide]]"
- "[[poetry_project_ideas]]"
source:
author:
published:
---
# What is `__init__.py`?
`__init__.py` is the file that tells Python "this folder is a package". When you put it inside a directory, that directory becomes importable like a module.
## The Core Purpose
Without `__init__.py` (in older Python, ≤3.2), a folder was just a folder — Python could not `import` from it. With it, the folder becomes a **package** you can do this with:
```python
from recipe_scraper.scraper import fetch_recipe
```
Here, `recipe_scraper/` is a package because it contains `__init__.py`.
> Note: Since Python 3.3, "namespace packages" allow imports without `__init__.py`, but **regular packages still use it** because it gives you more control (init code, explicit exports, IDE/tooling support).
---
## What It Does in Practice
### 1. Marks the folder as a package
Even an **empty** `__init__.py` is meaningful. It signals to Python:
> "Treat this directory as something you can import from."
### 2. Runs initialization code
Anything inside `__init__.py` runs **the first time** the package is imported. This is useful for:
- Setting up logging
- Loading config
- Registering plugins
```python
# recipe_scraper/__init__.py
import logging
logging.getLogger(__name__).addHandler(logging.NullHandler())
```
### 3. Controls the package's public API
You can re-export things so users don't need to know the internal file layout:
```python
# recipe_scraper/__init__.py
from .scraper import fetch_recipe
from .parser import parse_recipe
from .db import save_recipe
__all__ = ["fetch_recipe", "parse_recipe", "save_recipe"]
```
Now consumers can write the short form:
```python
from recipe_scraper import fetch_recipe # clean
# instead of:
from recipe_scraper.scraper import fetch_recipe # verbose
```
### 4. Defines package metadata
A common pattern is exposing a version string:
```python
# recipe_scraper/__init__.py
__version__ = "0.1.0"
```
---
## How It Fits the Recipe Scraper Project
Given the folder structure from [[Recipe Web Scraper - Getting Started]]:
```
recipe-scraper/
├── pyproject.toml
└── recipe_scraper/
├── __init__.py ← makes this a package
├── scraper.py
├── parser.py
├── db.py
└── cli.py
```
The `__init__.py` here lets you:
1. Run `poetry run python -m recipe_scraper.cli` — only works because `recipe_scraper` is a package.
2. Import cleanly from anywhere in the project:
```python
from recipe_scraper.db import Recipe
```
3. Optionally expose a tidy top-level API:
```python
# recipe_scraper/__init__.py
from .scraper import scrape_url
from .db import Recipe, init_db
__version__ = "0.1.0"
__all__ = ["scrape_url", "Recipe", "init_db"]
```
So users of your library can just do:
```python
import recipe_scraper
recipe_scraper.scrape_url("https://...")
```
---
## When to Leave It Empty vs. Fill It
| Situation | What to put in `__init__.py` |
| :--- | :--- |
| Internal-only package, no public API | Empty file |
| You want a clean import surface | Re-exports + `__all__` |
| Library shipped to PyPI | `__version__`, re-exports, maybe logging setup |
| One-time setup needed (config, env) | Initialization code at the top |
**Rule of thumb:** start with an empty `__init__.py`. Only add code when you have a concrete reason — re-exports, version, or setup. Don't put heavy logic in `__init__.py`; it runs on every import.
---
## Common Gotchas
- **Heavy imports slow everything down.** If `__init__.py` imports a big library (e.g., `pandas`), every `import recipe_scraper.anything` pays that cost. Keep it light.
- **Circular imports** often start in `__init__.py`. If `__init__.py` imports from `scraper.py`, and `scraper.py` imports from the package root, you get a cycle. Use lazy imports or restructure.
- **Tests need it too.** A `tests/` folder usually has an empty `__init__.py` so pytest can discover test modules consistently (though pytest's `rootdir` config can avoid this).
---
## TL;DR
- `__init__.py` = "this folder is a Python package".
- Can be empty — just its presence matters.
- Use it to **re-export** the public API, set `__version__`, or run small setup.
- Keep it light: every import of the package runs it.
## Related
- [[Recipe Web Scraper - Getting Started]]
- [[poetry_guide]] — Poetry's `poetry new` creates this file automatically
note/python/python_note/__init__.py vs main.py.md
+177
View File
@@ -0,0 +1,177 @@
---
title: __init__.py vs main.py
created: 2026-05-22
tags:
- python
- python_note
- packaging
- reference
category: python_note
status: reference
up: "[[project/index]]"
related:
- "[[__init__.py explained]]"
- "[[Recipe Web Scraper - Getting Started]]"
source:
author:
published:
---
# `__init__.py` vs `main.py`
Both files live inside a Python package, but they have very different jobs. This note uses the [[Recipe Web Scraper - Getting Started|recipe scraper]] project as the running example.
## The Recipe Scraper Layout
```
recipe-scraper/
└── src/
└── recipe_scraper/
├── __init__.py ← marks this as a package
├── main.py ← CLI entry point (you run this)
├── scraper.py
├── models.py
├── db.py
└── exporters.py
```
Two files, two completely different purposes.
---
## At a Glance
| Aspect | `__init__.py` | `main.py` |
| :--- | :--- | :--- |
| **Purpose** | Marks the folder as a package; sets up the package | Holds the **program's entry point** (the code you run) |
| **Required?** | Yes (for regular packages) | No — it's a convention, name can be anything |
| **When it runs** | Automatically, on **any** import of the package | Only when you **explicitly run it** |
| **Typical contents** | Re-exports, `__version__`, light setup | `main()` function, CLI parsing, `if __name__ == "__main__"` |
| **Who calls it** | Python's import system | The user (via `python -m`, `poetry run`, etc.) |
| **Should be lightweight?** | **Yes** — runs every import | Can be heavy — runs once when invoked |
---
## `__init__.py` — The Package Setup File
Its job is to tell Python "this folder is a package" and optionally configure what the package looks like from the outside.
```python
# src/recipe_scraper/__init__.py
from .scraper import scrape_url
from .db import Recipe, init_db
__version__ = "0.1.0"
__all__ = ["scrape_url", "Recipe", "init_db"]
```
After this, anyone using the library can write:
```python
from recipe_scraper import scrape_url
scrape_url("https://example.com/recipe")
```
instead of digging into `recipe_scraper.scraper`. **It never gets "run" directly — it runs implicitly whenever the package is imported.**
See [[__init__.py explained]] for the full picture.
---
## `main.py` — The Program Entry Point
Its job is to be the **code that actually executes when you launch the program**. For the recipe scraper, it's where the CLI lives:
```python
# src/recipe_scraper/main.py
import typer
from .scraper import scrape_url
from .db import init_db
app = typer.Typer()
@app.command()
def scrape(url: str):
"""Scrape a recipe URL and save it to the database."""
init_db()
recipe = scrape_url(url)
print(f"Saved: {recipe.title}")
@app.command()
def list_recipes():
"""List all saved recipes."""
...
def main():
app()
if __name__ == "__main__":
main()
```
You run it like:
```bash
poetry run python -m recipe_scraper.main scrape https://example.com/recipe
```
Or, if `pyproject.toml` defines an entry point pointing at `main:main`, just:
```bash
poetry run recipe-scraper scrape https://example.com/recipe
```
---
## The Key Mental Model
> `__init__.py` answers: **"What is this package?"**
> `main.py` answers: **"What happens when you run this program?"**
- Importing the package → `__init__.py` runs.
- Running the program → `main.py` runs (and it imports things, which triggers `__init__.py`).
So in a typical execution:
```
$ poetry run python -m recipe_scraper.main scrape ...
│
├── Python loads `recipe_scraper` package
│ └── runs __init__.py (sets up exports, version, etc.)
│
└── Python runs main.py as the module
└── parses CLI args, calls scrape_url(), saves to DB
```
`__init__.py` runs **first** (because `main.py` is inside the package), but it does almost nothing visible. `main.py` is where the actual work happens.
---
## Common Pitfalls
### 1. Putting CLI code in `__init__.py`
**Don't.** It will run every time *anything* imports your package, including your tests. Keep entry-point code in `main.py` (or `cli.py`).
### 2. Heavy imports in `__init__.py`
If `__init__.py` imports `pandas`, `torch`, or anything slow, every import of your package pays that cost. For the recipe scraper, avoid importing `recipe-scrapers` or SQLAlchemy at the top of `__init__.py` — import them inside the modules that need them.
### 3. Forgetting `if __name__ == "__main__":` in `main.py`
Without that guard, `main.py`'s code runs whenever the module is **imported**, not just when it's **executed**. Always wrap the entry-point call:
```python
if __name__ == "__main__":
main()
```
### 4. Confusing `main.py` with `__main__.py`
- `main.py` — just a convention; you have to point at it explicitly (`python -m recipe_scraper.main`).
- `__main__.py` — a **special name**: lets you run `python -m recipe_scraper` (no `.main` needed).
If you want `python -m recipe_scraper` to work, rename `main.py` to `__main__.py`. Many projects keep both: `__main__.py` is a one-liner that calls into `main.py`.
---
## TL;DR
- **`__init__.py`** = package marker + public-API shaping. Runs on every import. Keep it light.
- **`main.py`** = program entry point. Runs when you invoke the CLI. This is where the action is.
- They're complementary, not alternatives. In the recipe scraper, `__init__.py` exposes the library; `main.py` is the CLI you actually run.
## Related
- [[__init__.py explained]]
- [[Recipe Web Scraper - Getting Started]]
- [[poetry_guide]]