{"id":16220711,"url":"https://github.com/elc/python-assignment-template","last_synced_at":"2026-02-21T17:37:41.046Z","repository":{"id":98145215,"uuid":"395486034","full_name":"ELC/python-assignment-template","owner":"ELC","description":"A template repository to create assignments in Github Classroom","archived":false,"fork":false,"pushed_at":"2025-02-03T21:36:50.000Z","size":22,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-03T02:11:44.490Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ELC.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-13T01:23:31.000Z","updated_at":"2023-01-30T02:49:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"9745d837-0ee3-43fa-a65a-029a5a2a0fa4","html_url":"https://github.com/ELC/python-assignment-template","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/ELC/python-assignment-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ELC%2Fpython-assignment-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ELC%2Fpython-assignment-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ELC%2Fpython-assignment-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ELC%2Fpython-assignment-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ELC","download_url":"https://codeload.github.com/ELC/python-assignment-template/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ELC%2Fpython-assignment-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29688442,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T15:51:39.154Z","status":"ssl_error","status_checked_at":"2026-02-21T15:49:03.425Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-10T11:59:24.274Z","updated_at":"2026-02-21T17:37:36.032Z","avatar_url":"https://github.com/ELC.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Autograding Python Assignments\nA template repository to create assignments in Github Classroom\n\nThis README is all the documentation you need to get started. Jump to the\nsection of interest:\n\n- [Structure of the template](#structure-of-the-template)\n- [Methodology](#methodology)\n- [Github Classroom Configuration](#github-classroom-configuration)\n- [Code Style](#code-style)\n- [Docstrings](#docstrings)\n\n\n## Structure of the template\n\nThe template provides examples of different approaches to Github Classroom\nAssignments:\n\n- Doctests\n- Assertion Tests\n- Doctests and Assertion Tests\n- Hidden Tests\n- Property Testing\n\nEach has its features:\n\n**Doctests** are tests that are part of the docstring (i.e. the string one line\nbelow the function/class declaration). The purpose is twofold, on one hand,\nthey show the developer exactly what is the expected behavior, on the other\nhand, they also encourage good and updated documentation and provide useful\nexamples to the consumer of the functions/classes. As a drawback, the developer\ncould be tempted to \"just pass the test\" and thus not providing an\nimplementation that fulfills the requirement. The **Exercise 1** is an example.\n\n**Assertion Tests** are tests that validate a given expression is **True**,\nthey usually are of the form \"expected vs actual\". This idea is similar to the\none expressed in the doctest, there are some differences though. **Assertion\nTests** are not part of the function/class *per se* and hence they require\nexternal code statements. They are not reflected in the documentation of the\nfunction/class and could lead the developer to the same \"just pass the test\"\ntemptation. That being said, using them provides more flexible workflows since\nmocking components is usually too verbose for doctests. The **Exercise 2** is\nan example.\n\n**Doctests and Assertion Tests** is the combination of the two above-mentioned\ntests. The **Exercise 3** is an example.\n\n**Hidden Tests** refers to the separation of developer code and test code\nrather than a test methodology. These tests are in a separate folder than the\ncode they are testing and are usually **assertion tests**. The main advantage\nis that, although the developer has still access to them, it is much more\ncomplicated to modify them or alter them by accident. These tests are well\nsuited to mock complex steps and processes and therefore allow not only unit\ntests but also integration tests. The **Exercise 4** is an example.\n\n**Property Testing** is a methodology for testing functionality where instead\nof using examples of \"expected vs actual\", properties the code should have been\ntested. This is trivial for math-related code since properties arise naturally\nin the context of math. However, for enterprise software with several layers of\nabstractions, this is not transparent. For more information and examples there\nis the [talk by Zac\nHatfield-Dodds](https://www.youtube.com/watch?v=uN6JjpzVsAo) from PyCon 2021.\nThe **Exercise 5** is an example of how to use them with a toy example, here,\nthe Hypothesis test framework is used (i.e it should also be installed in the\nsetup command).\n\n## Methodology\n\nThere are multiple ways to implement assignments, below are some ideas, divided\nby the level of experience\n\n### Begginer\n\n- **Complete the code**: A function/class **with** signature and docstring is\n  given but without a body, the student must write the body so that the tests\n  pass.\n\n- **Find the bug**: A function/class **with** signature, docstring and **body**\n  is given but the tests are currently failing, the student must find the cause\n  and fix it so that tests pass.\n\n### Intermediate\n\n- **Refactor**: A function/class that is working and whose tests are passing\n  are given but, a new style decision is posed and the student should refactor\n  the code to meet that new requirement and keep the code working, passing the\n  test. For instance: one style decision might be \"No loops allow\" so it would\n  be expected that recursion is used instead without explicitly saying that to\n  the student.\n\n- **Add Functionality**: A function/class that is working and whose tests are\n  passing is given but, a new requirement is provided, the student then needs\n  to add that functionality for which tests are given and should make sure old\n  test keep passing.\n\n- **Add Test**: A function/class with the necessary docstring is given that is\n  not properly working but there are no tests to show it. The student should\n  write tests, identify the problem and fix it so that tests pass.\n\n### Advanced\n\n- **Architecture Design**: Only a text description of a system is given and the\n  student should write all the code and tests to fulfill the requirements.\n\n## Github Classroom Configuration\n\nTo create assignments follow these steps:\n\n1. Fork this repo and modify it to add the necessary exercise. Including\n   **modifying** this README page\n1. Make the forked repo a template repo.\n1. Create an assignment once logged in to Github Classroom.\n1. Select the forked repo.\n1. Add a Test of type \"Run Python\". One globally or one for each exercise (see\n   below).\n1. Share the link with the students.\n\n### Test Details\n\nTo configure the \"Run Python\" test\n\nTo set up a Github Classroom assignment, 5 fields should be specified:\n\n- **Title**: Choose a descriptive title for your exercise.\n- **Setup Command**: Install all necessary dependencies, if using the standard\n  library only, running  `sudo -H pip3 install pytest` should suffice. Pip's\n  install path is not included in the PATH var by default, so without\n  installing via `sudo -H`, pytest would be inaccessible.\n- **Run Command**: Specify a test command to run either one particular file or\n  a whole directory of files. In the most basic configuration `python -m pytest\n  -vvv tests/exercise1_test.py` will suffice. (Explanation below)\n- **Timeout**: This is the execution timeout for the tests.\n- **Points**: How many points are this particular exercise worth.\n\n\n#### Run Command Details\n\nThe command might seem arbitrary but each part has its purpose\n\n\n```bash\npython -m pytest -vvv tests/exercise1_test.py\n```\n\nThe `python -m` ensures the files are executed as modules, this is necessary to\nproperly handle imports inside tests; `pytest -vvv` defines the command to run\nthe tests, pytest is the name of the testing library, and the flag `-vvv` means\nthat the output should include as many details as possible; then comes the\nspecific file `tests/exercise1_test.py`, in this case, it is for a single file\nbut if one-test assignments are preferred, it could have been replaced with\n`tests`, meaning that the whole directory will be scanned for tests.\n\n## Code Style\n\nIn addition to the tests described in the previous section, this repo includes\na pre-commit test that has no points assigned but that ensures the same style\n(Flake8) is applied to all files in the repo. This serves as a static style\ncheck for the students' code. However, its importance should be assessed by the\nteacher in the PR.\n\nIf this style check should be graded, then add a test with:\n\n- **Setup Command**: `sudo -H pip3 install flake8`\n- **Run Command**: `flake8`\n\n## Docstrings\n\nHaving your code well documented is crucial in any production project. The\nstyle guide for Python is defined in the [PEP\n257](https://www.python.org/dev/peps/pep-0257/) but, some industry conventions\nare shown below. It is **recommended** that whenever applicable, one of these\nconventions is used in the exercise so that the student gets familiar with\ndocstrings.\n\nSince docstring writing could be a repetitive task, it is **recommended** to\nuse some extension to automate the process. In VS Code the [Autodocstring\nExtension](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring)\nserves this purpose.\n\n**Note**: The examples below do not deserve a docstring because the\nfunctionality is something trivial, that being said, it is useful to show a\ncommon scenario with types, return types, and raising exceptions. In production\ncode, such functions should not have docstrings.\n\n### Sphinx\n\nThe full guide can be found in the [official\ndocumentation](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html)\n\n```python\ndef function(key: str, dictionary: Dict[str, str]) -\u003e str:\n    \"\"\"This is a dummy function that returns the value of a dictionary given a\n    key.\n\n    :param key: The key to look for in the dictionary\n    :type key: str\n    :param dictionary: The dictionary where the key will be looked for\n    :type dictionary: Dict[str, str]\n    :return: The value of the dictionary at the given key\n    :rtype: str\n    :raises KeyError: If key is not in the dictionary.\n    \"\"\"\n    return dictionary[key]\n```\n\n### Google\nThe full guide can be found in the [official\ndocumentation](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings).\nMoreover, [comprehensive\nexample](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)\nis shown in the Napoleon Sphinx Plugin\n```python\ndef function(key: str, dictionary: Dict[str, str]) -\u003e str:\n    \"\"\"This is a dummy function that returns the value of a dictionary given a\n    key.\n\n    Args:\n        key (str): The key to look for in the dictionary.\n        dictionary (Dict[str, str]): The dictionary where the key will be\n            looked for.\n\n    Returns:\n        str: The value of the dictionary at the given key.\n\n    Raises:\n        KeyError: If key is not in the dictionary.\n    \"\"\"\n    return dictionary[key]\n```\n\n### Numpydoc\n\nThe full guide can be found in the [official\ndocumentation](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard).\nMoreover, [comprehensive\nexample](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html)\nis shown in the Napoleon Sphinx Plugin\n\n```python\ndef function(key: str, dictionary: Dict[str, str]) -\u003e str:\n    \"\"\"This is a dummy function that returns the value of a dictionary given a\n    key.\n\n    Parameters\n    ----------\n    key : str\n        The key to look for in the dictionary.\n    dictionary : Dict[str, str]\n        The dictionary where the key will be looked for.\n\n    Returns\n    -------\n    str\n        The value of the dictionary at the given key.\n\n    Raises\n    ------\n    KeyError\n        If key is not in the dictionary.\n    \"\"\"\n    return dictionary[key]\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felc%2Fpython-assignment-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felc%2Fpython-assignment-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felc%2Fpython-assignment-template/lists"}