palgoviz - Materials for Python and algorithms, with visualization

This is a project to develop approaches and materials for teaching and learning Python together with algorithms and data structures, with a substantial component of visualization. The intended learner is (at least at this point) expected to have substantial programming experience, but not necessarily any experience in Python, and not necessarily any experience with algorithms and data structures, other than the most basic topics such as using arrays.

Graphviz is heavily used for visualizations. Not all topics have demos or exercises that produce visualizations, and probably some never will (they may not always be helpful), but most topics should eventually have them.

This project is a work in progress. It is unknown how comprehensive it will be, or whether it will become a goal to produce materials that are ready-made for widespread use (rather than requiring careful selection and customization). In particular, classroom use is not currently a focus.

License

palgoviz is licensed under 0BSD (the BSD Zero Clause License). See LICENSE.

0BSD is a “public-domain equivalent” license. This is same license that code examples in the Python documentation are offered under to ensure they can always be reused without impediment.

In addition, it is our intention that the 0BSD license applies retroactively to all commits in the past history of this repository, from before licensing information was added. The same permission, and warranty disclaimer, applies.

The most useful code and documentation is usually at the tip of the main branch. But the process of developing the exercises, and various approaches to working them—including exploration of bugs, both intentional and accidental—may be of interest. Although that older content may be less useful, we want to make clear that its use is in no way restricted.

Authors

palgoviz is written by David Vassallo and Eliah Kagan.

Installation

palgoviz should be installed using conda/mamba or using poetry. There is also an experimental dev container.

(Although there’s a PyPI package, it should rarely be used.)

If you have no preference, conda/mamba is suggested. Condensed conda instructions follow.

Getting conda

If you don’t have conda already, we suggest Miniforge, which is what we’re using.

Creating and using the environment

Clone the repository, go into its top-level directory, and create the conda environment:

git clone https://github.com/EliahKagan/palgoviz.git
cd palgoviz
conda env create

Activate the environment:

conda activate palgoviz

You must activate the environment each time you use the project in a new shell (or after deactivating it).

Create an “editable install” in the environment:

pip install -e .

That command only has to be run once, not each time you use the project.

What’s here?

The most important and interesting parts of this project are the palgoviz/, tests/, and notebooks/ directories.

Here’s the full list of directories and what each one is for.

Usage

You can open the top-level directory (the directory that contains this README.md file) in an IDE or editor of your choice.

Visual Studio Code is suggested, and .vscode/ has some useful configuration, including for running tests using its test runner interface (the “beaker” icon on the activity bar on the left). This configuration uses the pytest test runner, which is capable of running all tests in the project.

If you use an IDE (which for this purpose includes VS Code), make sure to tell it that this project uses the palgoviz environment, or verify that it has detected this.

Running tests

Tests can be run from VS Code or another IDE, but you may want to run them from a terminal (and they may run faster that way, too).

To do that, first activate the palgoviz environment in your terminal if you haven’t already. Assuming you’re using conda:

conda activate palgoviz

Make sure you are in the top-level directory (the directory that contains this README.md file). Then run:

pytest --doctest-modules

If you want to use other test runners, including the unittest test runner, the more detailed documentation on running tests has information about that.

Using the notebooks

JupyterLab is installed as a dependency of the project, and all notebooks are tested in it. First activate the palgoviz environment in your terminal if you haven’t already. Assuming you’re using conda:

conda activate palgoviz

It is best to run JupyterLab from the top-level directory (the directory that contains this README.md file).

To run JupyterLab:

jupyter lab

Click here for more info about using notebooks, and real-time collaboration for notebooks and modules.

Quality

palgoviz is a work in progress.

Most functions and classes in modules (.py files) inside the palgoviz/ package are intended to be suitable for use as exercises, if you remove their implementations other than the header and docstring. For a few, the suggested way to “reset” them as exercises is different, and documented.

On the main branch, nearly all functions and classes in modules in palgoviz/ have been reviewed, and fully tested as exercises, by each of us. We usually do not merge module code to main until this has been done.

The major exception, as of this writing, is sll.py, which has not yet been doubly vetted in this way. The “alr” exercises in recursion.py have also not been through this process (but the others there have).

See Code Quality Considerations for more details.

Related work

This project is slightly related to a previous, less ambitious project, algorithms-suggestions.

Of interest

We are not affiliated with the following books in any way, and this project does not adapt from or otherwise tie into them, but people interested in this project may be interested in them as well:

• Problem Solving with Algorithms and Data Structures using Python by Brad Miller and David Ranum
• Fluent Python, Second Edition by Luciano Ramalho