ksauraj/jee_counsellor

"Introducing jee_counsellor - a tool to display colleges based on Jee Mains rank. Get personalized informations based on your rank and make informed decisions.

JEE Counsellor

A command-line tool for JEE counselling assistance.

Introduction

JEE Counsellor is a Python-based tool designed to assist with the counselling process for JEE (Joint Entrance Examination). It provides information about different rounds of counselling, institutes, programs, and closing ranks based on user input. This tool aims to simplify the decision-making process for JEE aspirants by providing relevant data.

Table of Contents

• Installation
  • Through Executable (Fast to install and setup, but slow to execute.)
    • Windows
    • Mac
    • Linux
  • Cloning from the Source (Recommended)
    • Windows
    • Mac
    • Linux
    • Termux Instructions
• Dependencies
• Usage
• License
• Credit

Installation

Executable (Might be Slow)

The JEE Counsellor tool is available as an executable for Windows, Mac, and Linux. Follow the instructions below to run the tool on your respective operating system.

Note: The provided installation method is only compatible with the x86_64 architecture. It will not work on other architectures.

Windows

• Download the jcounsellor.exe executable file from the latest release.

• Before running the tool, Windows may display a security warning message that prevents the execution of the tool. This is a precautionary measure to ensure the safety of your system. However, since jcounsellor is an open-source tool, you can bypass this security check and run the tool.

  • Here are two methods to bypass the security check:

    • Method 1: Use the "Run Anyway" option

      • When the security warning message appears, click on the "More info" link.
      • A new option "Run Anyway" should appear. Click on it to run the tool.

    • Method 2: Unblock the file

      • Right-click on the jcounsellor.exe file.
      • Select "Properties" from the context menu.
      • In the Properties window, locate and click on the "Unblock" button, if available.
      • Click "Apply" and then "OK" to save the changes.

    • By choosing the "Run Anyway" option or unblocking the file, you are indicating that you trust the source and intend to run the tool on your system.

    • Double-click the jcounsellor.exe file to run the tool. You should now be able to launch and use jcounsellor without any issues.

Note: Please understand that obtaining a license for commercial software can be expensive, and as an open-source tool, jcounsellor does not require any license fees. This allows us to provide the tool free of charge. However, it also means that we may not be able to offer the same level of support or additional features as commercial alternatives.

Mac

Note: The provided installation method is only compatible with the x86_64 architecture. It will not work on other architectures.

• Download the jcounsellor executable file from the latest release.

• Open the Terminal application.

• Navigate to the directory where the jcounsellor file is located using the cd command. For example, if the file is in the Downloads folder, use the following command:

  cd ~/Downloads

• Make the file executable by running the following command:

  chmod +x jcounsellor

• Run the tool using the following command:

  ./jcounsellor

Linux

Note: The provided installation method is only compatible with the x86_64 architecture. It will not work on other architectures.

• Download the jcounsellor executable file from the latest release.

• Open the Terminal application.

• Navigate to the directory where the jcounsellor file is located using the cd command. For example, if the file is in the Downloads folder, use the following command:

  cd ~/Downloads

• Make the file executable by running the following command:

  chmod +x jcounsellor

• Run the tool using the following command:

  ./jcounsellor

Cloning from the Source

By opting for this installation method, you gain the advantage of a dynamic and adaptable setup, ensuring access to the most recent code updates and the opportunity to actively participate in the project's advancement and enhancement.

Cloning from the Source ( Windows )

Prerequisites

Before cloning the repository and running the tool, ensure that you have the following software installed on your Windows system:

• Python 3.x
• Git

Steps

• Install Python:

  • Download the latest version of Python 3.x from the official Python website: Download Python.
  • Run the installer and follow the installation instructions.
  • Make sure to select the option to add Python to your system's PATH during the installation process.

• Install Git:

  • Download Git for Windows from the official Git website: Download Git.
  • Run the installer and follow the installation instructions.
  • During the installation, you can choose the default options unless you have specific preferences.

• Clone the repository:

  • Open the Command Prompt (CMD) or Git Bash.
  • Navigate to the directory where you want to clone the repository using the cd command. For example, to clone the repository into the current directory, use:

    cd /path/to/desired/directory

  • Clone the repository using the following command:

    git clone https://github.com/ksauraj/jee_counsellor.git

• Navigate to the project directory:

  • Change the current directory to the cloned repository:

    cd jee_counsellor

• Install the dependencies:

  • Install the required dependencies using the following command:

    pip install -r requirements.txt

• Run the tool:

  • Launch the JEE Counsellor tool using the following command:

    python tool.py

Cloning from the Source (Linux / Mac )

• Ensure that you have Python 3.x installed on your system.
• Clone the repository:

git clone https://github.com/ksauraj/jee_counsellor.git

• Navigate to the project directory:

cd jee_counsellor

• Install the dependencies:

pip install -r requirements.txt

• Run the tool:

python tool.py

Termux Instructions:

• Clone the repository (if git isn't installed use pkg install git):

git clone https://github.com/ksauraj/jee_counsellor.git

• Navigate to the project directory:

cd jee_counsellor

• Install python if it isn't installed using:

pkg install -y python

• Sometimes libexpat.so is missing, so to avoid any issues later install it using:

pkg install libexpat

• Install python-numpy and python-pandas which is under tur-repo:

pkg install python-numpy
pkg install tur-repo
pkg install python-pandas

• Install the last dependency:

pip install colorama

• Now you can run the tool using:

python tool.py

Dependencies

The following dependencies are required to run JEE Counsellor:

• Python 3.x
• pandas
• colorama

You can install the required dependencies using the following command:

pip install -r requirements.txt

Usage

• Launch the tool by following the installation instructions.
• Select the counseling type (JOSAA or CSAB) and the respective round.
• Choose the institute type and program(s) you are interested in.
• Enter your rank to view the closing ranks and related information.
• The tool will display the results in a browser window.

jee_counsellor_tut.mp4

License

This project is licensed under the GNU General Public License v3.0. For more details, see the LICENSe file.

Credit

• This project has been developed by Ksauraj.

jee_counsellor's Issues

[Feature]: Add the GitHub action workflow for greeting contributors

Description:

The current project lacks an automated action to greet contributors. GitHub Actions can significantly enhance project automation. I propose adding a GitHub Action workflow to greet new pull requests (PR) and issue creators, fostering a welcoming environment.

Proposed Changes:

Implement a GitHub Action workflow that triggers new PRs and issues. The workflow should include a greeting message to acknowledge and appreciate the contributors for their efforts.

Please assign me this issue under IWOC

test: make a test configuration file which will work under GitHub branch protection rule.

We can utilise GitHub branch protection rule and make a github workflow file to run some tests before merging a pull request.

You can utilise tools like unittest to do so.

This might be a sample for .github/workflows/test.yml file

name: Run Tests

on:
  push:
    branches:
      - main  # Adjust the branch name as needed

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: 3.8  # Adjust the Python version as needed

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt  # If you have a requirements file

      - name: Run tests
        run: python -m unittest discover -v

webpage: display the applied settings in the html file.

We can add feature to display the applied settings like what Institutes Type, Course Type, Quota, Rank etc was applied in following filtered data set.

Objective - This would make sharing of html file more useful as it will make sense what filters were applied during creating this filtered data.

For example -

Rank - 12424
Gender - Gender-Neutral
Seat Type - Open
Quota - AI, HS
Institutes - ALL
Institute Type - NITs
Round - 6
Year - 2023
Counseling Type - JOSAA

This needs to be added in webpage ( find a suitable place to add )

Feat: Adding GitHub workflows for issue and pull request

A template is necessary for the beginners to report any issue or pull request

Please assign me this under IWOC

tool: adding an option to exit from main menu of tool.

I iust realised we don't have option for exiting from tool from main menu, We should have one.

This looks ugly, we must fix it by adding option for exiting from tool.

feature: export to pdf, csv and json along with html

Feature Request: Export to PDF/CSV

Description

New feature that allows users to export the displayed data to PDF or CSV directly from the HTML page or form the script itself. This enhancement would provide users with the ability to save and share the information in a convenient and portable format.

Is this PDF/CSV formats or okay for the tool , or if you have any other format suggestions kidly give the response regarding this !

Expected Behavior

• The export options should include PDF and CSV formats.
• The exported file should accurately represent the currently displayed data on the HTML page.

tool: implement page indexing system in cli tool.

Implement a page indexing system for Institutes listing.

Institutes section contains large numbers of elements, which looks ugly to display all at once. So, we can implement a page indexing system which can display entries in bunches. Like at page 1 it will display 15 entries ( including the arbitrary "All" option ) and page 2 next 15 entries and we can switch between pages which choosing Institute types.

Any enhancement in Idea itself is welcomed ☺️

Refrence - 20b6257

I failed to implement it properly that time, So I just removed it 😅###

tool: adding a about section in the tool

In the main menu, we propose adding an 'About' section that will showcase the current version, provide a brief overview of the tool, acknowledge contributors, and include other relevant information. This section aims to offer users a comprehensive understanding of the tool, its evolution, and the people involved in its development.

Tool fails due to permission elevation

When opening an HTML file through Termux on an Android device, you may encounter permission issues related to the Termux sandbox environment and the security policies of the Chrome browser.

Termux operates within a restricted environment on Android, and certain actions that require broader permissions are restricted.

So this line eventually fails(it reaches the last case in android as both above conditions becomes false):

---

Due to permission, one just can't hit the following url
content://com.termux.files/data/data/com.termux/files/home/jee_counsellor/output/<fileName>.html

---

Security Policies of Chrome:

• The Chrome browser, like other modern browsers, enforces strict security policies, especially when it comes to opening local files. Chrome's security model limits the ability of web pages to access local resources to prevent potential security vulnerabilities and attacks.

---

Solution could be:

• Move file to allowed location, but it can lead to exception and often requires root privileges to write in some destination.
• Use a Simple HTTP Server: Start a simple HTTP server in Termux using Python or another tool. This way, you can access the HTML file through a local web server, and Chrome's security policies may allow it.

webview: update ui for the created html file for displaying filtered contents.

The created webpage is quite ugly right now, any improvement is welcomed.

You can edit your code here

webpage: Implement a page indexing system.

Implement a page indexing system in webpage which will make the filtered data to be displayed in systematic manner.

data: Generate json files for 2023 JOSAA and CSAB rounds.

Generate json files for 2023 josaa and csab rounds.

You can use tools like csvtojson or csvkit to perform such operations.

Reference - https://github.com/ksauraj/jee_counsellor/tree/master/josaa/2022/round_1

feature: add a progress bar for different filter as we apply.

It would be a great idea if we can implement a progress bar which react according to the number of filter applied and are yet to be applied.

termux: find a way to run tool on termux

All dependencies used here are available on termux ( pandas, colorama )
But the main problem is to install numpy ( which is used by pandas ) in termux.
If someone can make a accurate guide to make it run on termux will be very helpful.
We can also add bash script for reducing pain for new users.