Kurs Python · Moduł 12: Projekt końcowy

Portfolio na GitHubie

4 min czytania ·
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.example

Kod 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

![Python](https://img.shields.io/badge/Python-3.12-blue)
![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-green)
![Tests](https://github.com/user/repo/actions/workflows/test.yml/badge.svg)
![License](https://img.shields.io/badge/License-MIT-yellow)

> Krótki, chwytliwy opis projektu (1-2 zdania)

## Problem & Solution

**Problem:** Co rozwiązuje projekt?
**Solution:** Jak to robi?

## Demo

![Demo GIF](docs/demo.gif)

[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

![Stats](https://github-readme-stats.vercel.app/api?username=yourusername)

## Contact

- LinkedIn: [link]
- Email: your@email.com

Paski 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. 1. Ile repozytoriów można przypiąć (pin) na profilu GitHub?

  2. 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?

  1. PytanieGitHub Portfolio
  2. Kliknij w kolejnościEnv config
  3. PytanieConventional Commits
  4. Ułóż w kolejnościGit commit
  5. Ułóż w kolejnościGit workflow
  6. Ułóż w kolejnościElementy dobrego README

Przydatne artykuły