Kurs Python · Moduł 12: Projekt końcowy
Portfolio na GitHubie
W tej lekcji6
Tropiciel, który mówi "widziałem lwa", ale nie ma żadnego zdjęcia, nie przekona nikogo. Rekruter patrzy na CV tak samo: "znam Pythona i FastAPI" to deklaracja, a repozytorium z działającym projektem to dowód. Portfolio na GitHubie to Twoja wizytówka w świecie IT, a na nim wiele osób ocenia kandydata, zanim przeczyta list motywacyjny. Pokażmy światu, co potrafisz.
Struktura repozytorium
Pierwsze wrażenie robi układ plików. Przejrzysta struktura mówi "ta osoba wie, co robi", zanim ktokolwiek otworzy kod:
ai-document-assistant/
├── .github/
│ ├── workflows/
│ │ ├── test.yml
│ │ └── deploy.yml
│ └── ISSUE_TEMPLATE/
├── app/
│ ├── __init__.py
│ ├── main.py
│ ├── models/
│ ├── services/
│ ├── api/
│ └── config.py
├── tests/
│ ├── unit/
│ ├── integration/
│ └── conftest.py
├── docs/
│ ├── architecture.md
│ └── api.md
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
├── README.md
├── LICENSE
└── .env.exampleKod aplikacji leży w app/ z podziałem na warstwy, testy w tests/ z podziałem na unit i integration, workflowy CI w .github/workflows/. Plik .env.example zawiera nazwy zmiennych bez prawdziwych wartości, a sam .env dopisujesz do .gitignore. Plik LICENSE mówi, na jakich zasadach inni mogą używać Twojego kodu. Bez licencji obowiązuje pełne prawo autorskie, więc formalnie nikt nie może kodu kopiować ani modyfikować. Dla projektu portfolio licencja MIT to najprostszy wybór, a GitHub doda ją jednym kliknięciem przy tworzeniu repozytorium.
Zmienne środowiskowe
Skąd aplikacja bierze klucz API, skoro nie ma go w repozytorium? Z pliku .env, który czyta biblioteka python-dotenv. Funkcja load_dotenv() ładuje zmienne z pliku do środowiska procesu, a os.getenv je odczytuje:
import os
from dotenv import load_dotenv
load_dotenv() # wczytuje zmienne z pliku .env
api_key = os.getenv("API_KEY")Jeśli zmiennej nie ma, os.getenv zwraca None zamiast rzucać wyjątek. Kod się nie zmienia między laptopem a serwerem, zmienia się tylko środowisko.
Historia commitów
Rekruterzy zaglądają też w historię. Konwencja Conventional Commits standaryzuje format wiadomości: prefiks feat: oznacza nową funkcjonalność, fix: poprawkę błędu, docs: zmiany w dokumentacji, chore: prace porządkowe. Typowy przepływ to nowa gałąź, zmiany, commit, Pull Request, a na końcu code review i merge:
git checkout -b feature/upload
git commit -m "feat: add API endpoint"Gałąź utworzysz też nowszym poleceniem git switch -c feature/upload, efekt jest ten sam. Nawet w projekcie solo Pull Requesty pokazują, że znasz pracę zespołową.
README Template
README w portfolio sprzedaje projekt. Kluczowe elementy to tytuł z opisem, instrukcja instalacji, przykłady użycia i licencja. Plakietki na górze pokazują technologie i status testów:
# Project Name




> Krótki, chwytliwy opis projektu (1-2 zdania)
## Problem & Solution
**Problem:** Co rozwiązuje projekt?
**Solution:** Jak to robi?
## Demo

[Live Demo](https://your-demo-url.com) | [Video](https://youtube.com/...)
## Tech Stack
- **Backend:** Python, FastAPI, SQLAlchemy
- **AI/ML:** LlamaIndex, OpenAI, Qdrant
- **Infrastructure:** Docker, GitHub Actions
- **Testing:** pytest, httpx
## Features
- Feature 1
- Feature 2
- Feature 3 (in progress)
## Architecture
```
[Diagram architektury]
```
## Quick Start
[Instrukcje instalacji]
## Performance
| Metric | Value |
|--------|-------|
| Response Time | <2s |
| Accuracy | 92% |
| Uptime | 99.9% |
## Contributing
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md)
## License
MIT © [Your Name](https://github.com/username)Sekcja "Problem & Solution" jest najważniejsza, bo odpowiada na pytanie "po co to istnieje". Liczby w tabeli Performance to miejsce na Twoje prawdziwe pomiary z ewaluacji, nie wpisuj wartości, których nie zmierzyłeś. Plakietka testów pobiera status z GitHub Actions, więc zielona oznacza, że testy naprawdę przechodzą.
GitHub Profile README
GitHub pokazuje README z repozytorium o tej samej nazwie co Twój login na górze profilu. To miejsce na krótkie przedstawienie się:
# Hi, I'm [Name]
Python Developer | AI/ML Enthusiast | Building cool stuff
## Current Projects
- [AI Document Assistant](link) - RAG system for document Q&A
- [Project 2](link) - Description
## Skills
```
Python ████████████████████ 95%
FastAPI ███████████████████ 90%
ML/AI ████████████████ 80%
Docker ███████████████ 75%
```
## GitHub Stats

## Contact
- LinkedIn: [link]
- Email: your@email.comPaski umiejętności to ozdobnik, traktuj je z przymrużeniem oka. Lepiej działa link do projektu, który można uruchomić. Statystyki z github-readme-stats to zewnętrzny serwis, który bywa niedostępny, więc nie opieraj na nim całego profilu.
Wskazówki
Na profilu możesz przypiąć do sześciu repozytoriów lub gistów, więc wybierz sześć najlepszych. Regularne commity pokazują aktywność, a na zielonym wykresie kontrybucji regularność znaczy więcej niż intensywność. Każde repozytorium powinno mieć README, zawsze. Jeśli to możliwe, dodaj live demo, bo działający link przekonuje bardziej niż opis.
Moja rada: lepiej trzy dopracowane projekty z testami i README niż dwadzieścia porzuconych szkiców. W ostatniej lekcji przygotujemy się do kariery.
Pamiętaj: portfolio to zdjęcia z Twojej ekspedycji, dowód, że naprawdę przeszedłeś sawannę.
Kod do tej lekcji: main.py
# ===========================================
# Safari Capstone: Project Setup & Configuration
# ===========================================
# Set up the complete project structure with
# configuration management and logging.
import logging
import json
from dataclasses import dataclass, field, asdict
from pathlib import Path
from typing import Optional
from datetime import datetime
# --- Configuration ---
@dataclass
class AppConfig:
"""Application configuration for the safari system."""
app_name: str = "Safari Wildlife Manager"
version: str = "1.0.0"
debug: bool = False
database_url: str = "sqlite:///safari.db"
api_port: int = 8000
log_level: str = "INFO"
max_observations_per_day: int = 1000
@classmethod
def from_dict(cls, data: dict) -> "AppConfig":
return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
def to_dict(self) -> dict:
return asdict(self)
# --- Logging setup ---
def setup_logging(config: AppConfig):
"""Configure application logging."""
logging.basicConfig(
level=getattr(logging, config.log_level),
format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
datefmt="%Y-%m-%d %H:%M:%S"
)
logger = logging.getLogger(config.app_name)
logger.info(f"Logging initialized at {config.log_level} level")
return logger
# --- Data models ---
@dataclass
class Animal:
animal_id: str
species: str
name: str
weight_kg: float
region: str
status: str = "active"
tags: list[str] = field(default_factory=list)
created_at: str = field(default_factory=lambda: datetime.now().isoformat())
@dataclass
class Observation:
obs_id: str
animal_id: str
latitude: float
longitude: float
observer: str
notes: str = ""
timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
# --- Application bootstrap ---
config = AppConfig(debug=True, log_level="DEBUG")
logger = setup_logging(config)
print("=== Safari Project Setup ===")
print(f"App: {config.app_name} v{config.version}")
print(f"Debug: {config.debug}")
print(f"Database: {config.database_url}")
print(f"Port: {config.api_port}")
logger.info("Application started")
logger.debug("Debug mode is enabled")
# Create sample data
simba = Animal("LN-001", "Lion", "Simba", 195.0, "Savanna", tags=["alpha", "collared"])
obs = Observation("OBS-001", "LN-001", -2.33, 34.83, "Dr. Darwin", "Morning patrol sighting")
print(f"\nSample animal: {simba.name} ({simba.species})")
print(f"Sample observation: {obs.obs_id} at ({obs.latitude}, {obs.longitude})")
print(f"Config dict: {json.dumps(config.to_dict(), indent=2)}")
# TODO: Add environment-based configuration loading
# import os
# def load_config() -> AppConfig:
# env = os.getenv("APP_ENV", "development")
# config_data = {
# "debug": env == "development",
# "log_level": "DEBUG" if env == "development" else "INFO",
# "database_url": os.getenv("DATABASE_URL", "sqlite:///safari.db"),
# "api_port": int(os.getenv("PORT", "8000")),
# }
# return AppConfig.from_dict(config_data)
# TODO: Add a health check function
# def health_check(config: AppConfig) -> dict:
# return {
# "status": "healthy",
# "version": config.version,
# "database": "connected",
# "uptime_seconds": 0
# }
Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Ile repozytoriów można przypiąć (pin) na profilu GitHub?
2. Który prefix commita oznacza nową funkcjonalność w Conventional Commits?
Zadania praktyczne w grze
- Klikanie w kolejności
Kliknij w kolejności:
- Układanie w poziomie
Ułóż elementy:
- Układanie w pionie
Uporządkuj kroki:
- Układanie w pionie
Które elementy są kluczowe dla dobrego README?