flashcardz

What the program does

Flashcardz is used to aid in the learning a foreign language, math tables, etc. One-by-one a word, then its defintion, is shown to the user. A card's tally is incremented each time the user correctly recalled a word's defintion. Cards are removed once a card's maximum tally has been reached.

The program runs from python's command line terminal, i.e its REPL. Use flashcardz go() function to show cards one-by-one:

>>> go()

Adding words words to your deck of cards is easy. Use flashcardz's add() function:

>>> add('correr', 'to run (to move quickly on two feet)')

Words and definitions can also be imported from an Excel file.

Features

• Cost: Free.
• Easily add words and defintions via copy and paste.
• User can imbed url links into cards.
• Can import words and definitions from an Excel file.
• Deck is shuffled before each viewing.
• Score (i.e. a tally) is kept for each time word is successfully known.
• Cards whose max tally has been reached are removed from the deck.
• A card automatically removed each time its max tally has been reached.
• Portions of card's text can be highlighted with underscores, italics, or colors.
• Issue a trigger to a card, i.e. a key; Opens an web page from the Internet showing the word's definition.
• Run Flashcardz from a web page when Jupyter Lab software is installed.

How to install

For this program to run, it requires both python (which is free) and flashcardz.py to be installed on your computer.

To install python, download and install it from, python.org.

To install flashcardz.py, open a Window's command prompt (References: (1. how to open a command prompt, 2. command prompt basics) and enter into the command prompt:

C:\> pip install flashcardz

(C:> is the command prompt. Don't enter that.) Pip is a program that gets automatically installed when python is installed. Pip fetches python programs from pypi.org and installs them on your computer. (For more info about pip, see How to use pip).

Here is how you can update flashcardz to its latest version or uninstall it:

C:\> pip upgrade flashcardz

C:\> pip uninstall flashcardz

How to run flashcardz

Open a command prompt and start up a python session. In MS Windows, this is usually done by entering py. On other operating systems, python:

C:\> py
Python 3.12.2 (tags/v3.12.2:6abddd9, Feb  6 2024, 21:26:36) [MSC v.1937 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>>

As shown above, some introductory info is shown. You can ignore it. At the command prompt, i.e. the chevron (>>>), load flashcardz like this:

>>> from flashcardz import *

This imports flashcardz' functions with which you can control flashcardz.

Another way you can start flashcardz is if you downloaded flashcardz.py directly from its home site at https://github.com/kcarlton55/flashcardz. Start it up like this:

C:\> py -i flashcardz.py

The -i switch causes flashcardz to automatically open in interactive mode, i.e. opens the python REPL terminal for input and loads in flashcardz' functions. (reference: Open Command Prompt in Current Folder or Directory)

To see a list of flashcardz' functions and how do use them do:

>>> functions()

To add cards for use by flashcardz, use the add() function:

>>> add('amigo, amiga nm, nf', '(camarada) friend n buddy n')

That is, the structure should be add('my word', 'my definition'). Each time you use the add() function, the data you enter is added to a data file for later use. If you would like to add a multiline definition, do so like this:

>>> add('''amigo, amiga nm, nf''',
'''
(camarada) friend n buddy n

Nuestro primer viaje, a Cuzco, lo organizamos entre cuatro amigos.
We organized our first trip, to Cuzco, among four friends.

[how to pronounce](https://www.wordreference.com/es/en/translation.asp?spen=amigo)
''')

As you can see, use three quotation marks, ' ' ', to surround text when entering multiple lines. Note: you don't have to type all this in manually. Find a word's difintion on the Internet, copy words and definitions from there, and paste them into the REPL. Notice the last line in the definition. It is a URL link. URL links can be inserted into a word's definition using brackets and parenthesis using the format [link description](URL)

To see a list of your cards, and the number of the card according to its location in the deck, do:

>>> cards()

To see the definition of, for example, card no. 9 in the deck, do:

>>> cards(9)

When you're ready to view the cards one-by-one and test you memory of the words, run the go() function:

>>> go()

When the go() function is run, it automatically opens up the data file that contains your words and definitions, reads the data into memory, closes the file, and then begins showing the cards. When the go() function completes its task, tallies are updated, cards where maximum tallies have been reached are removed from the deck, the data file is reopened, updated data is saved, and finally the file is closed. It typically takes less than a second to open, close, and move data in and out of the data file.

When you want to exit python, enter either quit(), exit(), or Ctrl+D (or simply quit or exit works for python 3.13 and up):

>>> quit()

Convert an Excel file to a flashcardz data file

Words and definitions can be created in Excel and then exported to a text file that flashcardz can open and read. First, in cells A1 and B1 of the Excel file enter the column headers. Use as column headers "word" and "definition" (without the quotation marks) for these two cells. In subsequent rows, 2, 3, 4, etc. put in your words and definitions.

Save your file. Don't save it to a typical xlsx format. Save it instead to a cvs format. If you are not aware of this file format, please see this explanation: Comma-separated values. Futhermore UTF-8 character encoding is required. In Excel, when you do a "Save As", look for "CSV UTF-8 (Comma delimited)(*.csv)". (However, read on... a bug exists.)

There is a problem using the normal way that Excel exports to a csv file. The csv file that Excel exports to will have columns (i.e. the word and definition columns) separated by commas. That's well and good, but many times, like shown in the "add" example above, when copying and pasting definitions from the Internet, commas will be included within the definitions. When flashcardz reads in the csv file the result will be that flashcardz will interpret the additional commas to mean that your deck has additional columns, i.e. columns that shouldn't exist. This will cause flashcardz to crash.

To remedy this situation, flashcardz was instead coded to recognize the pipe, i.e. vertical bar character, |, as the separator (more specifically called a delimiter). Excel was somewhat poorly designed because Excel does not allow to change to a different delimiter when exporting. But there is a relatively easy work-around. See this youtube video for how to do it: Export Data with Pipe Delimiters Instead of Commas

Opening a flashcardz data file into Excel

Opening a flashcardz data file into Excel is relatively easy. When you open a flashcardz data file (with a csv or txt extension), you will be given the option to use a different delimiter other than a comma. Use the vertical bar character, also called a pipe, |, as a delimiter.

When you import your flashcardz data file into Excel, you will see that the flashcardz program has modified the data slightly by adding an additional column, the tally column.

Run flashcardz on a web page

A program named Jupyter Lab allows flashcardz to be run on a web page. Flashcardz works best when using this Jupyter Lab program! Jupyter Lab is free and is easy to install. It is not included in the basic python package. To install do:

C:\> pip install jupyterlab

Then to start up Jupyter Lab do:

C:\> jupyter lab

More info about Jupyter Lab can be found at https://jupyter.org/. This video can help: Jupyter Notebook Complete Beginner Guide.

Jupyter Lab is vaguely similar to Microsoft Excel. Like Excel, Jupyter Lab contains cells in which data can be entered. However Jupyter Lab contains only one column of cells; and the cells are not automatically present. Each cell has to be created manually (via selecting appropriate menu commands).

For flashcardz, the first cell should contain from flashcardz import *. Do Ctrl+Enter to run the cell. Create a new cell and enter one of flashcardz' functions. For example: go(). Press Ctrl+Enter to run that cell.