How szymon-25/wikiscraper works
Typ projektu i jego cel (z kontekstu drzewa + README)
To jest narzędzie CLI w Pythonie do:
• scrapowania stron Bulbapedii (HTTP → HTML),
• parsowania i ekstrakcji treści (np. pierwszy paragraf, tabele, linki),
• analizy tekstu (count words, względna częstotliwość słów, porównanie z częstotliwością w języku),
• opcjonalnie eksportu danych (CSV/JSON) oraz generowania wykresów.
Analiza struktury repo (co mapować na komponenty)
Z drzewa i README wynika naturalny podział na warstwy/moduły:
Warstwa uruchomieniowa (entrypoints)
• wiki_scraper.py — CLI (argparse), dispatch komend/trybów działania.
• obtain_data.py — skrypt pomocniczy do pobierania danych demonstracyjnych (offline cache / przykładowe dane).
• lang_confidence.ipynb — notebook analityczny (raczej poza “runtime”, ale może być “offline analysis”).
Warstwa logiki biznesowej
• scraper.py — klasa Scraper i “core” logiki scrapowania/parsowania/analiz.
Warstwa narzędziowa
• utils.py — konwersje zapytań→URL, małe helpery.
Testy
• tests/test_offline_only.py — unit testy offline (deterministyczne).
• tests/data/team_rocket.html — fixture HTML.
• wiki_scraper_integration_test.py — integracyjny test (real HTTP / real parsing).
Zależności zewnętrzne (z README/requirements)
• requests — HTTP client
• beautifulsoup4 — HTML parsing
• pandas — tablice/tabele + eksport CSV
• matplotlib — wykresy
• wordfreq — częstotliwość w języku (słownik/algorytm; potencjalnie też dane w data/word_counts_*.json wg README)
Systemy zewnętrzne / zasoby
• Bulbapedia (bulbapedia.bulbagarden.net) — upstream źródło HTML
• Lokalny filesystem — JSON/CSV/PNG, fixtures testowe
Co z README dopowiada architektonicznie (i co warto pokazać na diagramie)
README definiuje konkretne “use cases” CLI, które łatwo zamienić na “podsługi” w diagramie:
• --summary <title>: pobierz stronę → parse → wyciągnij 1 paragraf → stdout
• --table <title> --number N --first-row-is-header: pobierz → parse tabelę → pandas → CSV / analiza
• --count-words <title>: pobierz/parse text → tokenizacja → liczenie → wynik
• --analyze-relative-word-frequency --mode article|language --count K [--chart path]: agregacja z artykułów + porównanie z wordfreq/słownikami + opcjonalny wykres
• --auto-count-words <title> --depth D --wait S: rekursja po linkach + rate limiting (ważne: pokaż pętlę, kontrolę głębokości, “politeness delay”)
• wyraźny dispatcher komend (CLI → wybór ścieżki),
• wspólne pipeline’y: Fetch → Parse → Extract → Analyze → Output.
Podziel system na 6–8 bloków (im bardziej granularnie, tym lepiej, ale bez zgadywania):
CLI: wiki_scraper.py
• parsing args
• routing do funkcji
Core: Scraper (scraper.py)
• fetch_page(title/url)
• parse_html(...)
• extract_summary(...)
• extract_table(...)
• extract_links(...) (dla rekurencji)
• text extraction/cleaning
Utilities: utils.py
• build_bulbapedia_url(title)
• normalization (np. spacje/underscore) – o ile istnieje
External libs (podblok “Libraries”)
• requests (HTTP)
• BeautifulSoup4 (DOM parsing)
• pandas (table ops/export)
• matplotlib (chart)
• wordfreq (language freq baseline)
Local Storage / Artifacts
• data/*.json (jeśli faktycznie używane)
• Type.csv / Type_table.csv (z README)
• *.png (chart)
Tests
• Offline: tests/test_offline_only.py + fixture HTML
• Integration: wiki_scraper_integration_test.py → Bulbapedia
Relacje (strzałki) na tym diagramie:
• User → CLI
• CLI → Scraper (wywołania metod)
• Scraper → utils
• Scraper → requests → Bulbapedia (HTTP)
• Scraper → BeautifulSoup (parse)
• Scraper → pandas (tables)
• Scraper → wordfreq / lokalne data/*.json (jeśli to jest baseline)
• Scraper → filesystem (CSV/JSON/PNG)
• Tests → (Scraper/CLI) oraz Offline test → fixture HTML (bez requests)
(1) Summary / Count-words (prosty pipeline)
• CLI args → Scraper.fetch(title) → HTTP GET → HTML
• HTML → BS4 parse → Text extraction → Summary/Tokenize+count → stdout
(2) Table extraction
• CLI → Scraper.fetch(title) → parse → select table #N → normalize header (flag) → pandas DataFrame → export CSV → opcjonalna analiza
(3) Auto recursion
• CLI → (queue of pages) → loop(depth, wait)
• For each page: fetch → parse → extract links → enqueue next-level
• Aggregator: accumulate word counts
• Output: JSON/summary
• rate limit (wait), depth guard, visited set (nawet jeśli nie widzisz tego w kodzie, zostaw jako “recommended internal mechanism” i oznacz jako “if implemented”/“assumed”; najlepiej zweryfikować w scraper.py).
Najważniejsze wzorce/zasady architektoniczne do podkreślenia
Dla tego repo to raczej:
• Layering: CLI (I/O) vs Core logic vs Helpers
• Pipeline / ETL: Extract (HTML) → Transform (parse/clean) → Load/Output (stdout/files)
• Separation of concerns: tests offline vs integration
• External dependency boundaries: Bulbapedia + libs (requests/bs4/pandas/wordfreq)
Na diagramie warto zaznaczyć “granice”:
• granica procesu (to jest single-process CLI),
• granica sieci (wyjście do Bulbapedii),
• granica dysku (artefakty).
Jak dobrać poziom szczegółowości do tego typu projektu (CLI tool)
• komponenty kodu (pliki/moduły jako boxy),
• przepływy danych w ramach jednego procesu,
• ścieżki testowe (offline/integration) jako równoległe “consumer’y” core.
Unikaj wrzucania typowych elementów web-arch (load balancer, serwery, DB) jeśli nie ma ich w repo.
1) Czytelne etykiety: nazwy plików/modułów (wiki_scraper.py, scraper.py, utils.py) oraz technologie (requests, bs4, pandas, matplotlib, wordfreq)
Strzałki kierunkowe z opisem
• “HTTP GET / HTML”
• “DOM parse”
• “Extract table → DataFrame”
• “Write CSV/JSON/PNG”
Kolory / kształty (proponowany standard)
• Prostokąty: moduły repo
• Chmura: Bulbapedia (external)
• Przerywana ramka: test harness
• Inny kolor dla bibliotek zewnętrznych
Proponowany układ diagramu (żeby principal szybko to narysował)
Układ lewo→prawo, jedna “linia produkcyjna”:
[User] → [CLI wiki_scraper.py] → [Scraper (scraper.py)] →
• górą: [requests] → (Internet) → [Bulbapedia]
• środkiem: [BeautifulSoup parse] → [Extractors] → [Analyzers]
• dołem: [pandas/matplotlib/wordfreq]
• na końcu: [stdout] + [files: CSV/JSON/PNG]
Z boku (prawy dół): [Tests]
• Offline test → fixture HTML → Scraper (bez network)
• Integration test → Scraper → Bulbapedia
“Nie overthinkuj” – jak rozdzielić na jak najwięcej komponentów bez konfabulacji
Jeśli chcesz maksymalnej szczegółowości, ale nadal zgodnej z repo, rozbij Scraper wewnątrz jednego boxa na podboxy funkcjonalne (nawet jeśli to metody w jednej klasie), podpisane jako “functions/methods”:
• URL Builder (utils)
• Fetcher (requests)
• Parser (bs4)
• Content Extractor (summary/text)
• Table Extractor (tables→DataFrame)
• Word Count / Tokenizer
• Relative Frequency Analyzer (wordfreq baseline)
• Chart Renderer (matplotlib)
• Exporter (CSV/JSON)
To jest najlepszy kompromis: bardzo detalicznie pokazujesz architekturę, ale nie twierdzisz, że to osobne serwisy.