İTÜ Kepler Ders Seçici

Bu repo sayesinde otomatik bir şekilde, önceden zamanlayarak ve HTTP request kullanarak İTÜ Kepler üzerinden ders seçebilirsiniz.

Nasıl Kurulur ve Kullanılır

1. İlk olarak repo'yu bilgisayarınıza kurun. Aşağıdaki iki seçenekten istediğiniz ile indirebilirsiniz.

   • Bilgisayarınızda Git kurulu ise aşağıdaki kod'u kullanın.

     git clone https://github.com/AtaTrkgl/itu-ders-secici.git

   • Manuel olarak indirmek için ise GitHub sayfasındaki yeşil "Code" Tuşuna basın ve açılan pencereden "Download ZIP" tuşuna basın. Ardından indirdiğiniz ZIP dosyasını sağ tıklayıp ayıklayın.

2. Kurulu değil ise Python kurun. (Detaylı bilgi). Kurulumda dikkat etmeniz gerekenler; ilk penceredeki Add Python to PATH kutucuğunu ve Optional Features bölümündeki pip kutucuğunu tiklemeniz gerekiyor.

3. Gerekli paketleri kurmak için aşağıdaki komutu çalıştırın.

   pip install -r requirements.txt

4. Daha sonra yapmanız gereken, gerekli bilgileri programa girmek. Bunun için kurulum sihirbazını kullanmanız önerilir fakat isterseniz manuel olarak da girebilirsiniz.

   ⚠️ Program zamanlama için bilgisayarınızın lokal zamanını kullanmaktadır, eğer bilgisayarınız Türkiye saat diliminde değil ise, lokal zamanınıza göre ders seçimi saatini ve tarihini giriniz.

   💡 Kurulum sihirbazı, girilen CRN'lerin doğrulunu ITU Helper SDK ile kontrol etmektedir.

   • [ÖNERİLEN] Kurulum Sihirbazı ile Kurulum: Gerekli dosyaları oluşturmak için aşağıdaki kodu kullanarak kurulum sihirbazını çalıştırın, sürecin devamında ekrandaki adımları takip edin.

     python src/setup.py

   • Manuel Kurulum: repo'nun içinde data adında bir klasör oluşturup içerisine gerekli config.json adında bir dosya oluşturun. ardından, dosyanın içerisine, aşağıdaki yazıyı yapıştırın ve boşlukları doldurun.

     config.json Şablonu

     {
        "account":
        {
           "username": "{İTÜ KULLANICI ADINIZ}",
           "password": "{İTÜ ŞİFRENİZ}"
        },
        "time":
        {
           "year": {DERS SEÇİM ZAMANI - YIL},
           "month": {DERS SEÇİM ZAMANI - AY},
           "day": {DERS SEÇİM ZAMANI - GÜN},
           "hour": {DERS SEÇİM ZAMANI - SAAT},
           "minute": {DERS SEÇİM ZAMANI - DAKİKA}
        },
        "courses":
        {
           "crn": [{ALINACAK CRN'ler, virgülle ayırılmış şekilde}],
           "scrn": [{BIRAKILACAK CRN'ler, virgülle ayırılmış şekilde}]
        }
     }  

     Doldurulmuş config.json Örneği

     İsmail Koyuncu (koyuncu@itu.edu.tr) için, 10 Şubat 2025, 14:00 tarihinde, 21340, 21311 ve 21332 CRN'li dersleri alıp, hiç bir dersi bırakmayacak config.json örneği:

     {
        "account":
        {
           "username": "koyuncu",
           "password": "cokGucluSifre123"
        },
        "time":
        {
           "year": 2025,
           "month": 2,
           "day": 10,
           "hour": 14,
           "minute": 0
        },
        "courses":
        {
           "crn": [21340, 21311, 21332],
           "scrn": []
        }
     }  

   Yukarıdaki yöntemlerden herhangi birini tamamladığınız takdirde, dosya yapınız aşağıdaki gibi görünmeli.

   .
   ├── data
   │   └── config.json
   ├── src
   │   ├── run.py
   │   ...
   ├── README.md
   └── requirements.txt
   ...
   

5. Programı başlatmak için aşağıdaki kodu çalıştırın.

   python src/run.py

6. Program çalışmaya başladığında, ders seçimi sonlanınca bilgisayarın kapatılıp kapatılmayacağı sorulacak, [E] harfine basmanız durumunda bilgisayar otomatik olarak kapatılacaktır. (NOT: Sadece Windows cihazlarda çalışır.)

Nasıl Çalışır / Program Akışı

1. data dosyasına girilen input değerleri okunur.

2. Belirtirlen ders seçim zamanına 5 dakika kalana kadar beklenir.

3. İTÜ OBS (Kepler) sitesi açılır ve data/config.json dosyasındaki bilgiler ile giriş yapılır.

4. Ders seçim zamanına 45 saniye kalana kadar beklenir.

5. Ders seçim zamanına 30 saniye kalana kadar, sitenin Network sekmesinden ders seçimi için kullanılan API Token durmadan alınır.

6. Ders seçimine 30 saniye kalması ile beraber, API Token okunması durdurulur ve ders seçimi beklenilir.

7. Ders seçimi başlayana kadar, 0.1 saniyede (src/run.py dosyasındaki DELAY_BETWEEN_TIME_CHECKS değişkeninin değeri belirler.) bir ders seçim vaktinin gelip gelmediği kontrol edilir.

   💡 Eğer program test modunda çalıştırılırsa, bu aşamada sadece girilen vaktin gelmesi beklenir.

8. Ders seçiminin başlandığı algılandıktan 10 dakika (src/run.py dosyasındaki SPAM_DUR değişkeninin değeri belirler.) sonraya kadar; 3 saniye (src/run.py dosyasındaki DELAY_BETWEEN_TRIES değişkeninin değeri belirler.) aralıklarla ders seçimi için HTTP request yollanır. Bu süreç, İTÜ OBS (Kepler) arayüzüne durmadan CRN'lerin - data/crn_list.txt dosyasındaki sırayla - girilip onaylanması ile aynı sonucu yaratır fakat websitesi çökmelerine daha dayanıklıdır. Bü süreçte bütün işlemlerin başarılı olması durumda program otomatik olaran sonlandırılacaktır.

9. Süreç boyuncaki eylemler loglanır ve logs/logs.txt dosyasına kaydedilir.

10. Program sonlanır ve programın başında onay verildiyse bilgisayar kapatılır.

Nasıl Test Edilir

Bu programın en güzel tarafı, ders seçimi için İTÜ OBS (Kepler) arayüzü yerine HTTP request kullanmasıdır. Bu sayede, aktif bir ders seçim zamanı içinde değilken ve ders kayıt taslak da aktif değilken bile test edebilirsiniz.

Öncelikle test için, ders seçim zamanını daha yakın bir vakit olarak girin, şu andan yaklaşık 5-10 dakika ilerisi önerlir. Daha sonra, programı aşağıdaki komut ile çalıştırın

python src/run.py -test

Ardından sonuçları İTÜ OBS (Kepler) - Ders Kayıt İşlem Geçmişi sayfasından görebilirsiniz (Hata olarak aktif bir ders seçim zamanı içinde değilsiniz mesajını göreceksiniz).

Geliştirme Planları

Bu repo'ya katkıda bulunmak isterseniz aşağıdaki eklemeler ile başlayabilirsiniz 😊

• API Token alınmasını durdurup, HTTP request ile ders seçimine geçmek yerine; API Token alınmasını farklı bir thread üzerinde durmadan devam ettirerek başka bir thread üzerinden de HTTP request atarak hata ihtimali daha da indirilebilir.
• Kurulum sırasındaki data klasörü ve içindeki dosyaların oluşturulması için daha kullanıcı dostu bir arayüz geliştirilebilir.
• Ders seçimi için yollanan HTTP request'leri, önceden belirlenmiş bir süre boyunca spam'lamak yerine, HTTP request'in return code'una bakarak devam edilebilir. Derslerin hepsi seçilince otomatik durup seçilememesi durumunda sadece seçilemeyen dersleri almaya çalışmaya devam edebilir. Bu sayede ayrıca yedek CRN sistemi eklenebilir ve seçilemeyen ders yerine yedek CRN alınabilir.
• Yatay geçiş yapanların İTÜ OBS (Kepler) giriş ekranında hangi bölümünü kullanacağını soran bir sayfa daha çıkıyor. Kod şu anda buna karşın hiç bir şey yapmıyor ve manuel olarak hızlıca seçilmediği sürece çalışmıyor. Bu ekranda otomatik olarak güncel bölümün seçilmesi eklenilebilir.