A modern, type-safe Python wrapper for YOKATLAS API with pydantic validation.
Requirements | Gereksinimler: Python 3.9+
You can install the package using pip:
Paketi pip kullanarak yükleyebilirsiniz:
pip install yokatlas-py
Or with uv (recommended):
Ya da uv ile (önerilen):
uv add yokatlas-py
✅ Type Safe: Full type hints and pydantic validation
✅ Modern Python: Requires Python 3.9+ with modern syntax
✅ Fast HTTP: Uses httpx for both sync and async operations
✅ Validation: Runtime validation of all API responses
✅ IDE Support: Enhanced autocomplete and error detection
✅ Smart Search: Fuzzy university matching and flexible program name search
✅ Complete Data: All 235 lisans + 176 önlisans universities with 450+ programs
from yokatlas_py import search_lisans_programs, search_onlisans_programs
# 🎯 Smart fuzzy search - works with partial names and abbreviations
# Akıllı bulanık arama - kısmi isimler ve kısaltmalarla çalışır
# Search for bachelor's programs with fuzzy matching
results = search_lisans_programs({
"uni_adi": "boğaziçi", # Finds "BOĞAZİÇİ ÜNİVERSİTESİ"
"program_adi": "bilgisayar", # Finds all computer-related programs
"sehir": "istanbul" # Case-insensitive city matching
})
print(f"📚 Found {len(results)} lisans programs:")
for program in results[:3]:
print(f"🎓 {program['uni_adi']}")
print(f"💻 {program['program_adi']}")
print(f"📍 {program['sehir_adi']}")
print("---")
# Search for associate programs with abbreviations
onlisans_results = search_onlisans_programs({
"uni_adi": "anadolu", # Finds "ANADOLU ÜNİVERSİTESİ"
"program_adi": "turizm" # Finds all tourism-related programs
})
print(f"🏫 Found {len(onlisans_results)} önlisans programs:")
for program in onlisans_results[:2]:
print(f"🎓 {program['uni_adi']}")
print(f"🏖️ {program['program_adi']}")
print("---")
from yokatlas_py import YOKATLASLisansTercihSihirbazi
from yokatlas_py.models import SearchParams, ProgramInfo
from pydantic import ValidationError
# Type-safe parameter validation
params = SearchParams(
puan_turu="say",
length=10,
sehir="İstanbul",
universite_turu="Devlet"
)
# Perform search with validated parameters
search = YOKATLASLisansTercihSihirbazi(params.model_dump(exclude_none=True))
results = search.search()
# Process results with validation
for result in results[:3]:
try:
program = ProgramInfo(**result)
print(f"🎓 {program.uni_adi}")
print(f"📚 {program.program_adi}")
print(f"🏛️ {program.fakulte}")
print(f"📍 {program.sehir_adi}")
print("---")
except ValidationError as e:
print(f"⚠️ Invalid data: {e}")
from yokatlas_py import (
YOKATLASLisansAtlasi,
YOKATLASLisansTercihSihirbazi,
YOKATLASOnlisansAtlasi,
YOKATLASOnlisansTercihSihirbazi
)
# Atlas classes use async methods
async def example_atlas_usage():
# Lisans (Bachelor's) program details
lisans_atlasi = YOKATLASLisansAtlasi({'program_id': '104111719', 'year': 2024})
lisans_result = await lisans_atlasi.fetch_all_details()
print("YOKATLAS Lisans Atlas Result:", lisans_result)
# Önlisans (Associate) program details
onlisans_atlasi = YOKATLASOnlisansAtlasi({'program_id': '203550463', 'year': 2024})
onlisans_result = await onlisans_atlasi.fetch_all_details()
print("YOKATLAS Önlisans Atlas Result:", onlisans_result)
# Search classes use sync methods
def example_search_usage():
# Search for bachelor's programs
lisans_params = {
'puan_turu': 'say', # Score type: say, ea, söz, dil
'sehir': 'ANKARA', # Filter by city
'universite_turu': 'Devlet', # State universities only
'length': 5 # Results per page
}
lisans_search = YOKATLASLisansTercihSihirbazi(lisans_params)
lisans_results = lisans_search.search()
print("Lisans Search Results:", lisans_results)
# Search for associate programs
onlisans_params = {
'puan_turu': 'tyt', # Score type for associate degrees
'sehir': 'İSTANBUL', # City filter
'universite_turu': 'Devlet', # State universities
'length': 10 # Results per page
}
onlisans_search = YOKATLASOnlisansTercihSihirbazi(onlisans_params)
onlisans_results = onlisans_search.search()
print("Önlisans Search Results:", onlisans_results)
# Run examples
example_search_usage()
# For async atlas usage, use asyncio in your environment:
# import asyncio
# asyncio.run(example_atlas_usage())
The library includes comprehensive pydantic models for type safety and validation:
Kütüphane tip güvenliği ve doğrulama için kapsamlı pydantic modelleri içerir:
- SearchParams: Search parameter validation
- ProgramInfo: University program information
- YearlyData: Year-based statistical data
- ErrorResponse: Error handling and reporting
from yokatlas_py.models import SearchParams, ProgramInfo
from pydantic import ValidationError
# Invalid search parameters will be caught
try:
params = SearchParams(
puan_turu="invalid_type", # Invalid score type
length=-5 # Invalid length
)
except ValidationError as e:
print(f"Validation error: {e}")
# Valid parameters pass validation
params = SearchParams(
puan_turu="say",
sehir="İstanbul",
length=10
)
The library automatically matches partial and abbreviated university names:
from yokatlas_py import search_lisans_programs
# All of these work and find "BOĞAZİÇİ ÜNİVERSİTESİ"
search_lisans_programs({"uni_adi": "boğaziçi"})
search_lisans_programs({"uni_adi": "bogazici"}) # Without Turkish chars
search_lisans_programs({"uni_adi": "boun"}) # Common abbreviation
# Common university abbreviations supported:
# "odtu"/"metu" → "ORTA DOĞU TEKNİK ÜNİVERSİTESİ"
# "itu" → "İSTANBUL TEKNİK ÜNİVERSİTESİ"
# "hacettepe" → "HACETTEPE ÜNİVERSİTESİ"
Partial program names automatically find all related programs:
# "bilgisayar" finds all computer-related programs:
# - "Bilgisayar Mühendisliği"
# - "Bilgisayar Bilimleri"
# - "Bilgisayar ve Öğretim Teknolojileri Öğretmenliği"
results = search_lisans_programs({"program_adi": "bilgisayar"})
# "mühendislik" finds all engineering programs
engineering_programs = search_lisans_programs({"program_adi": "mühendislik"})
Search both lisans and önlisans programs simultaneously:
from yokatlas_py import search_programs
# Search both program types at once
all_results = search_programs({
"uni_adi": "anadolu",
"program_adi": "bilgisayar"
})
print(f"Lisans programs: {len(all_results['lisans'])}")
print(f"Önlisans programs: {len(all_results['onlisans'])}")
-
Smart Search: Use
search_lisans_programs()
andsearch_onlisans_programs()
for better search experience - Fuzzy Matching: University and program names are matched intelligently
- Complete Data: All Turkish universities and programs included
-
Update the package
pip install --upgrade yokatlas-py
-
Use new smart search functions (recommended)
# Old way (still works) from yokatlas_py import YOKATLASLisansTercihSihirbazi search = YOKATLASLisansTercihSihirbazi({"universite": "BOĞAZİÇİ ÜNİVERSİTESİ"}) # New way (with fuzzy matching) from yokatlas_py import search_lisans_programs results = search_lisans_programs({"uni_adi": "boğaziçi"}) # Much easier!
-
Optional: Use type-safe features
from yokatlas_py.models import SearchParams params = SearchParams(puan_turu="say", length=10)
This project is licensed under the MIT License - see the LICENSE file for details.
Bu proje MIT Lisansı ile lisanslanmıştır - detaylar için LICENSE dosyasına bakınız.