marksman 0.6.5

CLI Tool to manage marks of students efficiently.

marksman

CLI Tool to manage marks of students efficiently.

Features

• CRUD ( create / read / update / delete )
• Email ( email results to students )
• Visualize ( visualize the data )
• Utils ( fill dummy data / import from csv / export csv )

Getting Started

You must have Python 3.9 installed on your system.

Install easily via pip, Python's official Package Manager.

pip install marksman

Note: Linux and Mac users might have to use pip3 to invoke pip

Please read this if you are new to command-line-interfaces.

Tip: You can use the alias mm instead of typing the long marksman. Its already set for you when you install.

CRUD

CRUD stands for Create,Read,Update,Delete. These are the fundamental operations we can perform on a database. marksman supports all these operations, through its CLI.

You can CRUD the students, exams and marks entries using marksman.

To use the CRUD action, first read its usage.

Suppose you want to CRUD students, here is an example.

If you have noticed the above gif carefully, you can observe that when you run the crud action with students as the option, you are first asked the roll number of the student. If a student with that roll exists, you are shown its details. You also have further options to see more data or update or delete the student.

If the student, with the roll number you entered does not exist, then you will be given the choice to create the student.

If you don't enter any roll number, then marksman will display all students in the database and exit.

In the same fashion you can also crud exams and marks entries. See more examples of crud in action.

Email

You can run marksman email --help to see how to use the email action. To configure settings for your emailing, read Configuration.

Now you have seen, how to use the email action, below is an example usage.

The result is this:

You can also use a custom template for the email message. If no template is found the default will be used.

For using a custom template, create a file called marksman_email_template.md and put in the directory from which you are running marksman.

You can insert variables in your template like this ::var::.

Here is a sample template.

Hi ::name::, you have scored ::marks:: in ::exam::.

Highest marks is ::highest::
Average marks is ::average::
Your rank is ::rank::

Please find the attached graph of your performance analysis.

Best Regards,
::inst::

The list of supported variables are as follows:

List of variables passed to the template:

1. name
2. roll
3. email
4. exam
5. marks
6. rank
7. highest
8. average
9. inst ( name of institute )

As this template is in a markdown file, you can use any valid markdown formatting.

Visualize

Data visualization is essential in taking important decisions. We can have a lot of data, but if we cannot make meaningful conclusions from it, then it is useless.

In marksman you have the data of marks of all students. marksman allows you to easily visualize the performance of the entire batch or of an individual student using simple graphs.

You can learn to use the visualize action by using the --help flag.

Let us see an example, where the teacher can visualize the results of an exam for the entire batch.

You can also visualize the result of one particular student in that exam. Just use the --r flag to supply the roll number of the student to marksman. See the example below for clarity.

Utils

marksman provides certain additional utilities to make your life easy. If you want to experiment with marksman, without actually putting any data your self, then marksman can help you by filling some dummy data. You can also import or export your data from or to CSV file formats.

To learn about the utils action, use the --help flag.

As you can see that utils can accept either of the three arguments:

1. dummy : fill the database with fake students, exams and marks for testing purposes.
2. import : insert data into the database from CSV files ( of specific format )
3. export : write existing data to CSV files

Lets see some examples, for full clarity.

Filling dummy data is a piece of cake. Just run marksman utils dummy

Now when it comes to importing data from CSV files, it must be in a specific format.

Here is a brief description of the convention that is supported by marksman:

Data	Filename	CSV Headers
Students	students.csv	roll,name,email
Exams	exams.csv	uid,name
Marks	marks.csv	student,exam,marks

All three files must be kept in the same folder. For the CSV file for marks, student column should contain the roll, and exam the uid.

It is not compulsory to have all the three files for the import. Marksman will take whatever data you give it.

See the following example for understanding better.

You can use the export option to write the data in the database to CSV files. The exported files will have the same format as shown above.

Configuration

You can configure marksman by using certain environment variables.

marksman loads the environment variables from the system's environment and from two special files:

1. the .env file in ~/.marksman ( global settings for marksman )
2. the .env file in the current directory from which you are running marksman ( local settings for marksman )

The local settings will override the global settings.

Note: ~ means the user directory. It is different for Unix and Windows. Windows 10: ~ expands to <root>\Users\<username> For Linux: ~ expands to /home/<username> The ~ symbol can be used directly in the terminal, let your OS expand it for you.

List of environment variables supported:

Variable	Description	Default
marksman_db	the path to store the .db file	~/.marksman/database.db
marksman_sender	email address to be used to send emails
marksman_auth	password to login to sender's email account
marksman_smtp_host	url of SMTP host server	smtp.gmail.com
marksman_smtp_port	SMTP port for sending emails	587
marksman_inst	name of institute which is sending emails

You can write these settings in the .env file like this:

marksman_sender=[e-mail]
marksman_auth=dummypass

If you do not provide a value, the default value will be used.

If a value is required, marksman will prompt you to to enter it during program execution. marksman will also ask you if you want to save it. If you say yes, marksman will save that setting in the global scope ( ~/.marksman/.env file). In this way, marksman can exempt you from manually editing the configs. You can always manually edit them when you want.

API Reference

As marksman is written purely in python, it can easily be imported and extended by other Python programs.

Read the full API Reference which is published from the docstrings.