Pytudes

CI codecov Documentation Status License pre-commit Code style: black powered by semgrep

Documentation: https://pytudes.readthedocs.io

Source Code: https://github.com/TeoZosa/pytudes

πŸ§‘β€πŸ« Overview

Miscellaneous programming challenges for the purpose of personal/professional edification, inspired by Peter Norvig’s pytudes repository:

β€œAn Γ©tude (a French word meaning study) is an instrumental musical composition, usually short, of considerable difficulty, and designed to provide practice material for perfecting a particular musical skill.” β€” Wikipedia

This project contains pytudesβ€”Python programs, usually short, for perfecting particular programming skills

Solutions strive towards a balance of both optimality and β€œelegance” (in other words, simple enough to understand and remember/easily triangulate) with sufficiently succinct, collocated documentation and tests.

πŸ“ Note
Given the strictly pedagogical nature of this endeavor, final solutions are always informed by preexisting implementations. As such, I make no explicit claims of originality.

πŸ—ΊοΈ Project Structure

The project files are organized under problem source namespaces (i.e., educative.io, leetcode, etc.) and further organized into ad-hoc categories.

At the module level, files are:

  • Prefixed with their problem number (the canonical number if one exists, by order of introduction otherwise)

  • [Optionally] Postfixed by a salient non-redundant characteristic (i.e., advertised difficulty level if not otherwise evident from superordinate directory names)

Within each module, Google-style (ish) docstrings and doctests are used to document and test the code, respectively.

Documentation and tests are designed to serve the learning process, not the other way around, so there is not an enforced standard. However, in general:

  • Self-evident fields are excluded

    • Ex. β€œarr: the array to sort”

  • Non-standard fields are included ad-hoc to communicate salient information

    • E.g., time/space complexity, diagrams, etc.

  • Attributions, links, and qualified file paths are included whenever possible

Table of Contents

πŸš€ Usage

🚸 Running The Project

The workflow I’ve found that has worked best for me:

  1. Create a file adhering to project structure rules.

  2. Define the necessary type-annotated module functions, classes, etc. stubs for the given problem.

  3. Generate docstring stubs and add problem-specific information into corresponding fields.

    • i.e., Args for problem-specific parameters, Returns for the return value.

  4. Iteratively implement the solution, alternating between adding/updating doctests in the Examples section and writing code, ala TDD .

    • Development cycles can be made extremely fast when running in an IDE with built-in doctest support, e.g., using Pycharm and hitting the β€œRun Doctests” keyboard shortcut on significant changes.

πŸ“ Note
As much as possible, try not to import anything from any other project modules.

  • This way, we maintain maximum flexibility regarding problem-specific implementations by removing the opportunity to mistake incidental duplication for true systemic duplication (see: The software engineering rule of 3).

  • As an added bonus, it also prevents the code from becoming abstruse due to excessive indirection.

πŸ”§ Development

For convenience, implementation details of the below processes are abstracted away and encapsulated in single Make targets.

πŸ”₯ Tip
Invoking make without any arguments will display auto-generated documentation on available commands.

πŸ—οΈ Package and Dependencies Installation

Make sure you have Python 3.9+ and poetry installed and configured.

To install the package and all dev dependencies, run:

make provision-environment

πŸ”₯ Tip
Invoking the above without poetry installed will emit a helpful error message letting you know how you can install Poetry.

βœ…οΈ Testing

We use tox and pytest for our test automation and testing frameworks, respectively.

To invoke the tests, run:

make test

🚨 Code Quality

We use pre-commit for our static analysis automation and management framework.

To invoke the analyses and auto-formatting over all version-controlled files, run:

make lint

🚨 Danger
CI will fail if either testing or code quality fail, so it is recommended to automatically run the above locally prior to every commit that is pushed.

πŸ”„ Automate via Git Pre-Commit Hooks

To automatically run code quality validation on every commit (over to-be-committed files), run:

make install-pre-commit-hooks

⚠️️ Warning
This will prevent commits if any single pre-commit hook fails (unless it is allowed to fail) or a file is modified by an auto-formatting job; in the latter case, you may simply repeat the commit and it should pass.

πŸ“ Documentation

make docs-clean docs-html

πŸ“ Note
For faster feedback loops, this will attempt to automatically open the newly built documentation static HTML in your browser.

πŸ“‹οΈ Summary

Hopefully this project inspires you to integrate programming-etudes in your daily life as well!

πŸ“šοΈ Further Reading