Documentation: https://pytudes.readthedocs.io
Source Code: https://github.com/TeoZosa/pytudes
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.
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
The workflow I've found that has worked best for me:
- Create a file adhering to project structure rules.
- Define the necessary type-annotated module functions, classes, etc. stubs for the given problem.
- Generate docstring stubs and add problem-specific information into corresponding
fields.
- i.e.,
Argsfor problem-specific parameters,Returnsfor the return value.
- i.e.,
- Iteratively implement the solution, alternating between adding/updating doctests in
the
Examplessection 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.
For convenience, implementation details of the below processes are abstracted away and encapsulated in single Make targets.
🔥 Tip
Invokingmakewithout any arguments will display auto-generated documentation on available commands.
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 withoutpoetryinstalled will emit a helpful error message letting you know how you can install Poetry.
We use tox
and pytest for our test automation and testing
frameworks, respectively.
To invoke the tests, run:
make testWe 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.
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.
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.
Hopefully this project inspires you to integrate programming-etudes in your daily life as well!
- LeetCode
- Grokking the Coding Interview: Patterns for Coding Questions
- Decode the Coding Interview in Python: Real-World Examples
Pytudes is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.
This project was generated from
@TeoZosa's
cookiecutter-cruft-poetry-tox-pre-commit-ci-cd
template.