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.
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.
palgoviz is written by David Vassallo and Eliah Kagan.
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.
If you don’t have conda already, we suggest
Miniforge, which is what we’re
using.
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 createActivate the environment:
conda activate palgovizYou 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.
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.
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.
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 palgovizMake sure you are in the top-level directory (the directory that contains this
README.md file). Then run:
pytest --doctest-modulesIf you want to use other test runners, including the unittest test runner,
the more detailed documentation on running tests has
information about that.
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 palgovizIt is best to run JupyterLab from the top-level directory (the directory that
contains this README.md file).
To run JupyterLab:
jupyter labpalgoviz 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.
This project is slightly related to a previous, less ambitious project, algorithms-suggestions.
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