# YOKATLAS-py
A modern, type-safe Python wrapper for YOKATLAS API with pydantic validation.
[](https://www.python.org/downloads/)
[](https://docs.python.org/3/library/typing.html)
[](https://pydantic.dev)
## Installation | Kurulum
**Requirements | Gereksinimler:** Python 3.9+
You can install the package using pip:
Paketi pip kullanarak yükleyebilirsiniz:
```sh
pip install yokatlas-py
```
Or with uv (recommended):
Ya da uv ile (önerilen):
```sh
uv add yokatlas-py
```
## Features | Özellikler
✅ **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
## How to | Kullanım
### Quick Start with Smart Search | Akıllı Arama ile Hızlı Başlangıç
```python
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("---")
```
### Type-Safe Search | Tip Güvenli Arama
```python
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}")
```
### Traditional Usage | Geleneksel Kullanım
```python
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())
```
## Pydantic Models | Pydantic Modelleri
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:
### Available Models | Mevcut Modeller
- **SearchParams**: Search parameter validation
- **ProgramInfo**: University program information
- **YearlyData**: Year-based statistical data
- **ErrorResponse**: Error handling and reporting
### Example with Validation | Doğrulama ile Örnek
```python
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
)
```
## Smart Search Features | Akıllı Arama Özellikleri
### Fuzzy University Matching | Bulanık Üniversite Eşleştirme
The library automatically matches partial and abbreviated university names:
```python
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İ"
```
### Flexible Program Matching | Esnek Program Eşleştirme
Partial program names automatically find all related programs:
```python
# "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"})
```
### Universal Search | Evrensel Arama
Search both lisans and önlisans programs simultaneously:
```python
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'])}")
```
## Migration from v0.3.x | v0.3.x'den Geçiş
### New Features in v0.4.2+ | v0.4.2+'daki Yeni Özellikler
- **Smart Search**: Use `search_lisans_programs()` and `search_onlisans_programs()` for better search experience
- **Fuzzy Matching**: University and program names are matched intelligently
- **Complete Data**: All Turkish universities and programs included
### Migration Steps | Geçiş Adımları
1. **Update the package**
```bash
pip install --upgrade yokatlas-py
```
2. **Use new smart search functions (recommended)**
```python
# 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!
```
3. **Optional: Use type-safe features**
```python
from yokatlas_py.models import SearchParams
params = SearchParams(puan_turu="say", length=10)
```
## License | Lisans
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.
Raw data
{
"_id": null,
"home_page": null,
"name": "yokatlas-py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "yokatlas, turkish-education, university, yok, higher-education, turkey, api",
"author": null,
"author_email": "Said S\u00fcr\u00fcc\u00fc <saidsrc@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/0b/66/6a36fab5956626e74cc8800524a6095e62c1bd4d2f433aa40cd85b66356a/yokatlas_py-0.4.3.tar.gz",
"platform": null,
"description": "\n# YOKATLAS-py\n\nA modern, type-safe Python wrapper for YOKATLAS API with pydantic validation.\n\n[](https://www.python.org/downloads/)\n[](https://docs.python.org/3/library/typing.html)\n[](https://pydantic.dev)\n\n\n## Installation | Kurulum\n\n**Requirements | Gereksinimler:** Python 3.9+\n\nYou can install the package using pip:\n\nPaketi pip kullanarak y\u00fckleyebilirsiniz:\n\n```sh\npip install yokatlas-py\n```\n\nOr with uv (recommended):\n\nYa da uv ile (\u00f6nerilen):\n\n```sh\nuv add yokatlas-py\n```\n\n## Features | \u00d6zellikler\n\n\u2705 **Type Safe**: Full type hints and pydantic validation \n\u2705 **Modern Python**: Requires Python 3.9+ with modern syntax \n\u2705 **Fast HTTP**: Uses httpx for both sync and async operations \n\u2705 **Validation**: Runtime validation of all API responses \n\u2705 **IDE Support**: Enhanced autocomplete and error detection \n\u2705 **Smart Search**: Fuzzy university matching and flexible program name search \n\u2705 **Complete Data**: All 235 lisans + 176 \u00f6nlisans universities with 450+ programs \n\n## How to | Kullan\u0131m\n\n### Quick Start with Smart Search | Ak\u0131ll\u0131 Arama ile H\u0131zl\u0131 Ba\u015flang\u0131\u00e7\n\n```python\nfrom yokatlas_py import search_lisans_programs, search_onlisans_programs\n\n# \ud83c\udfaf Smart fuzzy search - works with partial names and abbreviations\n# Ak\u0131ll\u0131 bulan\u0131k arama - k\u0131smi isimler ve k\u0131saltmalarla \u00e7al\u0131\u015f\u0131r\n\n# Search for bachelor's programs with fuzzy matching\nresults = search_lisans_programs({\n \"uni_adi\": \"bo\u011fazi\u00e7i\", # Finds \"BO\u011eAZ\u0130\u00c7\u0130 \u00dcN\u0130VERS\u0130TES\u0130\"\n \"program_adi\": \"bilgisayar\", # Finds all computer-related programs\n \"sehir\": \"istanbul\" # Case-insensitive city matching\n})\n\nprint(f\"\ud83d\udcda Found {len(results)} lisans programs:\")\nfor program in results[:3]:\n print(f\"\ud83c\udf93 {program['uni_adi']}\")\n print(f\"\ud83d\udcbb {program['program_adi']}\")\n print(f\"\ud83d\udccd {program['sehir_adi']}\")\n print(\"---\")\n\n# Search for associate programs with abbreviations\nonlisans_results = search_onlisans_programs({\n \"uni_adi\": \"anadolu\", # Finds \"ANADOLU \u00dcN\u0130VERS\u0130TES\u0130\"\n \"program_adi\": \"turizm\" # Finds all tourism-related programs\n})\n\nprint(f\"\ud83c\udfeb Found {len(onlisans_results)} \u00f6nlisans programs:\")\nfor program in onlisans_results[:2]:\n print(f\"\ud83c\udf93 {program['uni_adi']}\")\n print(f\"\ud83c\udfd6\ufe0f {program['program_adi']}\")\n print(\"---\")\n```\n\n### Type-Safe Search | Tip G\u00fcvenli Arama\n\n```python\nfrom yokatlas_py import YOKATLASLisansTercihSihirbazi\nfrom yokatlas_py.models import SearchParams, ProgramInfo\nfrom pydantic import ValidationError\n\n# Type-safe parameter validation\nparams = SearchParams(\n puan_turu=\"say\",\n length=10,\n sehir=\"\u0130stanbul\",\n universite_turu=\"Devlet\"\n)\n\n# Perform search with validated parameters\nsearch = YOKATLASLisansTercihSihirbazi(params.model_dump(exclude_none=True))\nresults = search.search()\n\n# Process results with validation\nfor result in results[:3]:\n try:\n program = ProgramInfo(**result)\n print(f\"\ud83c\udf93 {program.uni_adi}\")\n print(f\"\ud83d\udcda {program.program_adi}\")\n print(f\"\ud83c\udfdb\ufe0f {program.fakulte}\")\n print(f\"\ud83d\udccd {program.sehir_adi}\")\n print(\"---\")\n except ValidationError as e:\n print(f\"\u26a0\ufe0f Invalid data: {e}\")\n```\n\n### Traditional Usage | Geleneksel Kullan\u0131m\n\n```python\nfrom yokatlas_py import (\n YOKATLASLisansAtlasi,\n YOKATLASLisansTercihSihirbazi,\n YOKATLASOnlisansAtlasi,\n YOKATLASOnlisansTercihSihirbazi\n)\n\n# Atlas classes use async methods\nasync def example_atlas_usage():\n # Lisans (Bachelor's) program details\n lisans_atlasi = YOKATLASLisansAtlasi({'program_id': '104111719', 'year': 2024})\n lisans_result = await lisans_atlasi.fetch_all_details()\n print(\"YOKATLAS Lisans Atlas Result:\", lisans_result)\n \n # \u00d6nlisans (Associate) program details \n onlisans_atlasi = YOKATLASOnlisansAtlasi({'program_id': '203550463', 'year': 2024})\n onlisans_result = await onlisans_atlasi.fetch_all_details()\n print(\"YOKATLAS \u00d6nlisans Atlas Result:\", onlisans_result)\n\n# Search classes use sync methods\ndef example_search_usage():\n # Search for bachelor's programs\n lisans_params = {\n 'puan_turu': 'say', # Score type: say, ea, s\u00f6z, dil\n 'sehir': 'ANKARA', # Filter by city\n 'universite_turu': 'Devlet', # State universities only\n 'length': 5 # Results per page\n }\n lisans_search = YOKATLASLisansTercihSihirbazi(lisans_params)\n lisans_results = lisans_search.search()\n print(\"Lisans Search Results:\", lisans_results)\n \n # Search for associate programs\n onlisans_params = {\n 'puan_turu': 'tyt', # Score type for associate degrees\n 'sehir': '\u0130STANBUL', # City filter\n 'universite_turu': 'Devlet', # State universities\n 'length': 10 # Results per page\n }\n onlisans_search = YOKATLASOnlisansTercihSihirbazi(onlisans_params)\n onlisans_results = onlisans_search.search()\n print(\"\u00d6nlisans Search Results:\", onlisans_results)\n\n# Run examples\nexample_search_usage()\n\n# For async atlas usage, use asyncio in your environment:\n# import asyncio\n# asyncio.run(example_atlas_usage())\n```\n\n## Pydantic Models | Pydantic Modelleri\n\nThe library includes comprehensive pydantic models for type safety and validation:\n\nK\u00fct\u00fcphane tip g\u00fcvenli\u011fi ve do\u011frulama i\u00e7in kapsaml\u0131 pydantic modelleri i\u00e7erir:\n\n### Available Models | Mevcut Modeller\n\n- **SearchParams**: Search parameter validation\n- **ProgramInfo**: University program information \n- **YearlyData**: Year-based statistical data\n- **ErrorResponse**: Error handling and reporting\n\n### Example with Validation | Do\u011frulama ile \u00d6rnek\n\n```python\nfrom yokatlas_py.models import SearchParams, ProgramInfo\nfrom pydantic import ValidationError\n\n# Invalid search parameters will be caught\ntry:\n params = SearchParams(\n puan_turu=\"invalid_type\", # Invalid score type\n length=-5 # Invalid length\n )\nexcept ValidationError as e:\n print(f\"Validation error: {e}\")\n\n# Valid parameters pass validation\nparams = SearchParams(\n puan_turu=\"say\",\n sehir=\"\u0130stanbul\", \n length=10\n)\n```\n\n## Smart Search Features | Ak\u0131ll\u0131 Arama \u00d6zellikleri\n\n### Fuzzy University Matching | Bulan\u0131k \u00dcniversite E\u015fle\u015ftirme\n\nThe library automatically matches partial and abbreviated university names:\n\n```python\nfrom yokatlas_py import search_lisans_programs\n\n# All of these work and find \"BO\u011eAZ\u0130\u00c7\u0130 \u00dcN\u0130VERS\u0130TES\u0130\"\nsearch_lisans_programs({\"uni_adi\": \"bo\u011fazi\u00e7i\"})\nsearch_lisans_programs({\"uni_adi\": \"bogazici\"}) # Without Turkish chars\nsearch_lisans_programs({\"uni_adi\": \"boun\"}) # Common abbreviation\n\n# Common university abbreviations supported:\n# \"odtu\"/\"metu\" \u2192 \"ORTA DO\u011eU TEKN\u0130K \u00dcN\u0130VERS\u0130TES\u0130\"\n# \"itu\" \u2192 \"\u0130STANBUL TEKN\u0130K \u00dcN\u0130VERS\u0130TES\u0130\" \n# \"hacettepe\" \u2192 \"HACETTEPE \u00dcN\u0130VERS\u0130TES\u0130\"\n```\n\n### Flexible Program Matching | Esnek Program E\u015fle\u015ftirme\n\nPartial program names automatically find all related programs:\n\n```python\n# \"bilgisayar\" finds all computer-related programs:\n# - \"Bilgisayar M\u00fchendisli\u011fi\"\n# - \"Bilgisayar Bilimleri\" \n# - \"Bilgisayar ve \u00d6\u011fretim Teknolojileri \u00d6\u011fretmenli\u011fi\"\n\nresults = search_lisans_programs({\"program_adi\": \"bilgisayar\"})\n\n# \"m\u00fchendislik\" finds all engineering programs\nengineering_programs = search_lisans_programs({\"program_adi\": \"m\u00fchendislik\"})\n```\n\n### Universal Search | Evrensel Arama\n\nSearch both lisans and \u00f6nlisans programs simultaneously:\n\n```python\nfrom yokatlas_py import search_programs\n\n# Search both program types at once\nall_results = search_programs({\n \"uni_adi\": \"anadolu\",\n \"program_adi\": \"bilgisayar\"\n})\n\nprint(f\"Lisans programs: {len(all_results['lisans'])}\")\nprint(f\"\u00d6nlisans programs: {len(all_results['onlisans'])}\")\n```\n\n## Migration from v0.3.x | v0.3.x'den Ge\u00e7i\u015f\n\n### New Features in v0.4.2+ | v0.4.2+'daki Yeni \u00d6zellikler\n\n- **Smart Search**: Use `search_lisans_programs()` and `search_onlisans_programs()` for better search experience\n- **Fuzzy Matching**: University and program names are matched intelligently\n- **Complete Data**: All Turkish universities and programs included\n\n### Migration Steps | Ge\u00e7i\u015f Ad\u0131mlar\u0131\n\n1. **Update the package**\n ```bash\n pip install --upgrade yokatlas-py\n ```\n\n2. **Use new smart search functions (recommended)**\n ```python\n # Old way (still works)\n from yokatlas_py import YOKATLASLisansTercihSihirbazi\n search = YOKATLASLisansTercihSihirbazi({\"universite\": \"BO\u011eAZ\u0130\u00c7\u0130 \u00dcN\u0130VERS\u0130TES\u0130\"})\n \n # New way (with fuzzy matching)\n from yokatlas_py import search_lisans_programs\n results = search_lisans_programs({\"uni_adi\": \"bo\u011fazi\u00e7i\"}) # Much easier!\n ```\n\n3. **Optional: Use type-safe features**\n ```python\n from yokatlas_py.models import SearchParams\n params = SearchParams(puan_turu=\"say\", length=10)\n ```\n\n## License | Lisans\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\nBu proje MIT Lisans\u0131 ile lisanslanm\u0131\u015ft\u0131r - detaylar i\u00e7in LICENSE dosyas\u0131na bak\u0131n\u0131z.\n",
"bugtrack_url": null,
"license": null,
"summary": "A python wrapper for YOKATLAS API",
"version": "0.4.3",
"project_urls": {
"Homepage": "https://github.com/saidsurucu/yokatlas-py",
"Issues": "https://github.com/saidsurucu/yokatlas-py/issues"
},
"split_keywords": [
"yokatlas",
" turkish-education",
" university",
" yok",
" higher-education",
" turkey",
" api"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "34b63e9aaabf87d4f1bd632845e5f01eed17193adb405b3e06f5129ca140bac4",
"md5": "91c7c8f540d0fb60cb0899f796f92c03",
"sha256": "963d8e68ea57d4abed62ba3caaaa62388058cd30128608d26310ee0e94ba422a"
},
"downloads": -1,
"filename": "yokatlas_py-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "91c7c8f540d0fb60cb0899f796f92c03",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 108482,
"upload_time": "2025-07-20T11:23:36",
"upload_time_iso_8601": "2025-07-20T11:23:36.090986Z",
"url": "https://files.pythonhosted.org/packages/34/b6/3e9aaabf87d4f1bd632845e5f01eed17193adb405b3e06f5129ca140bac4/yokatlas_py-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0b666a36fab5956626e74cc8800524a6095e62c1bd4d2f433aa40cd85b66356a",
"md5": "2031ece2dc93bc01208641e24c74d6ca",
"sha256": "791a2f6deb9e14b4034c5f422e9620675daed8358a2231df611edeecdd379ab4"
},
"downloads": -1,
"filename": "yokatlas_py-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "2031ece2dc93bc01208641e24c74d6ca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 49283,
"upload_time": "2025-07-20T11:23:37",
"upload_time_iso_8601": "2025-07-20T11:23:37.769243Z",
"url": "https://files.pythonhosted.org/packages/0b/66/6a36fab5956626e74cc8800524a6095e62c1bd4d2f433aa40cd85b66356a/yokatlas_py-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-20 11:23:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "saidsurucu",
"github_project": "yokatlas-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "yokatlas-py"
}
JSON
