diff --git a/README.md b/README.md index 7e5962e..8217cb9 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,14 @@ Each lecture has its own screenshot in `docs/images/` (made by `docs/images/capt ![Lecture 4: __name__ and __main__](docs/images/lecture-04.png) +**Lecture 5: functions are first-class objects.** A function can be passed as an argument (`calculate(add, 2, 3)`), defined inside another function and returned from it. See `flask_day_54.domain.first_class_functions`; run it with `python -m flask_day_54.domain.first_class_functions`. + +![Lecture 5: functions as first-class objects](docs/images/lecture-05.png) + +**Lecture 6: decorators and the `@` syntax.** `@make_bold` above a function is shorthand for `say_hello = make_bold(say_hello)`. See `flask_day_54.domain.decorators`; run it with `python -m flask_day_54.domain.decorators`. + +![Lecture 6: decorators](docs/images/lecture-06.png) + ## 📋 Requirements - Python 3.13 or newer, because the project sets `requires-python = ">=3.13"` in `pyproject.toml`. diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index 4235e9a..818301f 100644 --- a/docs/artifact-registry.md +++ b/docs/artifact-registry.md @@ -18,7 +18,7 @@ document of a type. `Primary File` may contain a glob (e.g. | ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0002 | | DICT | Domain Dictionary | docs/dictionary.md | 002 | | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | -| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 018 | +| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 019 | ## Languages diff --git a/docs/images/lecture-05.png b/docs/images/lecture-05.png new file mode 100644 index 0000000..5bff5ca Binary files /dev/null and b/docs/images/lecture-05.png differ diff --git a/docs/images/lecture-06.png b/docs/images/lecture-06.png new file mode 100644 index 0000000..c23fdfe Binary files /dev/null and b/docs/images/lecture-06.png differ diff --git a/docs/images/sources/lecture-05.html b/docs/images/sources/lecture-05.html new file mode 100644 index 0000000..0c60d8c --- /dev/null +++ b/docs/images/sources/lecture-05.html @@ -0,0 +1,10 @@ +
Terminal - lecture 5: functions as first-class objects
$ python -m flask_day_54.domain.first_class_functions
+calculate(add, 2, 3) = 5
+calculate(subtract, 5, 3) = 2
+outer_function() = Hello from the nested function
+returned nested function() = Hello from the nested function
\ No newline at end of file diff --git a/docs/images/sources/lecture-06.html b/docs/images/sources/lecture-06.html new file mode 100644 index 0000000..dc1d74d --- /dev/null +++ b/docs/images/sources/lecture-06.html @@ -0,0 +1,10 @@ +
Terminal - lecture 6: decorators and the @ syntax
$ python -m flask_day_54.domain.decorators
+plain: Hello, World!
+by hand, make_bold(plain_hello)(): <b>Hello, World!</b>
+@ syntax, say_hello(): <b><em><u>Hello, World!</u></em></b>
+say_hello.__name__: say_hello
\ No newline at end of file diff --git a/docs/sqa/reviews/rc-018-code-mil-004-functions-decorators.md b/docs/sqa/reviews/rc-018-code-mil-004-functions-decorators.md new file mode 100644 index 0000000..31e15bd --- /dev/null +++ b/docs/sqa/reviews/rc-018-code-mil-004-functions-decorators.md @@ -0,0 +1,62 @@ +# Review of MIL-004 + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-018 | +| CrossReference | [MIL-004], [QC-PY-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-11-06 | Proposed | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [6dac2be] | + +--- + +## Artifact Under Review + +- Instance reviewed: [MIL-004] +- Checklist used: [QC-PY-001] +- Scope: full review of the source and tests delivered by MIL-004 (src/, tests/) +- Language and domain: n/a +- Language reviewer: none (the reviewer reads English and knows the IT domain) +- Mode: autonomous, not independent (AI as stand-in for S01) + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | Packages, modules, functions, variables, classes and constants follow PEP 8 casing (`snake_case`, `PascalCase`, `UPPER_SNAKE`) | Pass | Modules, functions and constants use snake_case / UPPER_SNAKE; classes none or PascalCase. | +| 2 | Names state purpose in the domain's language; no unexplained abbreviations, no single-letter names outside tiny scopes | Pass | Names follow the lecture and the domain dictionary. | +| 3 | Code is produced by the project's formatter and passes its linter with no unexplained suppressions | Pass | `ruff format` leaves files unchanged and `ruff check` (E, F, I, B, UP) passes; configured in pyproject.toml. | +| 4 | Every function and method signature is type-annotated, including `-> None` | Pass | Every function signature is annotated, including `-> None`. | +| 5 | No bare `except:`, no swallowed exceptions; specific exceptions are raised and the cause is kept (`raise ... from`) | Pass | No bare except and no swallowed exception. | +| 6 | No mutable default arguments and no shadowed builtins | Pass | No mutable defaults; no builtin shadowed. | +| 7 | Files, locks and connections are managed with context managers | N-A | No file, lock or connection is opened. | +| 8 | Public modules, classes and functions have docstrings that say what, not how | Pass | Module and public names carry docstrings plus Doxygen comments. | +| 9 | Logging uses `logging`, not `print`; no secrets or personal data in log output | N-A | Console output of the demo entry points (print under the __main__ guard) is the program's result, not diagnostic logging; no secrets handled. | +| 10 | Classes and operations trace to the Design Class Diagram they implement; deviations are recorded | N-A | No DCD exists in this project; the layered layout is recorded in ADR-0001. | +| 11 | Tests exist for new behaviour, are named for the behaviour, and do not depend on order or the network | Pass | pytest tests named for behaviour; no order or network dependence. | +| 12 | Type checker runs in strict mode without errors; `Any` is justified in a comment | N-A | No type checker is configured (optional criterion). | +| 13 | Dependencies are declared and pinned in the project's dependency file, none unused | Pass | Dependencies are declared in pyproject.toml; none unused (Flask is the optional `web` extra). | +| 14 | Each piece of knowledge (a business rule, constant, format, validation or query) is defined in one place; code is merged only where it expresses the same knowledge, not where it merely looks alike | Pass | Each constant is defined once in the constants.py of its layer. | +| 15 | Imports point inward: business-rule modules import no framework, database, UI or delivery-mechanism code, and there are no import cycles | Pass | `domain` imports no framework or outer layer; imports point inward; no cycles. | +| 16 | SOLID holds: a class or module has one reason to change; new behaviour is added by extension, not by editing a type test in several places; subclasses honour the contract of their base; protocols are narrow; high-level code depends on protocols or abstract types and receives its implementations | Pass | Small modules with one reason to change; no type tests or subclass hierarchies. | +| 17 | Source is laid out in the layers and folders of the clean architecture folder structure (`domain`, `application`, `infrastructure`, `presentation` packages under `src/`, and `unit`, `integration` and `e2e` under `tests/`), in `snake_case`, and imports between the layers point inward | Pass | Layers domain, application, infrastructure, presentation under src/flask_day_54; tests in unit and e2e (ADR-0001); no layer merged. | +| 18 | File and folder names are English, contain no space and no character outside letters, digits, `-`, `_` and `.`, and follow the casing of the language for files | Pass | English snake_case file names without spaces. | + +## Overall Verdict + +Go — All applicable mandatory criteria pass. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| None | S01 | - | + +--- + +[MIL-004]: ../../milestones/mil-004-functions-decorators.md +[QC-PY-001]: ../../../framework/qc/code/qc-programming-python.md +[6dac2be]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/054-flask/commit/6dac2be41a1857a8459520ece1f61c8683f79912 diff --git a/src/flask_day_54/domain/constants.py b/src/flask_day_54/domain/constants.py index 2756463..196a916 100644 --- a/src/flask_day_54/domain/constants.py +++ b/src/flask_day_54/domain/constants.py @@ -38,3 +38,26 @@ CLI_COMMANDS: Final[tuple[tuple[str, str, str, bool, str], ...]] = ( NO_CONFIRMATION_WARNING, ), ) + +## @brief Message returned by the nested function of lecture 5. +NESTED_FUNCTION_MESSAGE: Final[str] = "Hello from the nested function" + +## @brief Demo line templates of lecture 5; `{value}` is the printed result. +ADD_DEMO_LINE: Final[str] = "calculate(add, 2, 3) = {value}" +SUBTRACT_DEMO_LINE: Final[str] = "calculate(subtract, 5, 3) = {value}" +OUTER_DEMO_LINE: Final[str] = "outer_function() = {value}" +RETURNED_DEMO_LINE: Final[str] = "returned nested function() = {value}" + +## @brief HTML tag names used by the lecture 6 decorators. +BOLD_TAG: Final[str] = "b" +EMPHASIS_TAG: Final[str] = "em" +UNDERLINE_TAG: Final[str] = "u" + +## @brief Template wrapping text in an HTML tag. +HTML_TAG_TEMPLATE: Final[str] = "<{tag}>{text}" + +## @brief Demo line templates of lecture 6; `{value}` is the printed result. +PLAIN_DEMO_LINE: Final[str] = "plain: {value}" +BY_HAND_DEMO_LINE: Final[str] = "by hand, make_bold(plain_hello)(): {value}" +AT_SYNTAX_DEMO_LINE: Final[str] = "@ syntax, say_hello(): {value}" +NAME_DEMO_LINE: Final[str] = "say_hello.__name__: {value}" diff --git a/src/flask_day_54/domain/decorators.py b/src/flask_day_54/domain/decorators.py new file mode 100644 index 0000000..faa59f8 --- /dev/null +++ b/src/flask_day_54/domain/decorators.py @@ -0,0 +1,69 @@ +## @file decorators.py +# @brief Lecture 6 demo of decorators and the `@` syntax. +"""A decorator wraps a function to add behaviour without editing it.""" + +from collections.abc import Callable +from functools import wraps + +from flask_day_54.domain.constants import ( + AT_SYNTAX_DEMO_LINE, + BOLD_TAG, + BY_HAND_DEMO_LINE, + EMPHASIS_TAG, + GREETING, + HTML_TAG_TEMPLATE, + NAME_DEMO_LINE, + PLAIN_DEMO_LINE, + UNDERLINE_TAG, +) + + +def _tag_decorator(tag: str) -> Callable[[Callable[[], str]], Callable[[], str]]: + """Build a decorator that wraps the returned text in the given HTML tag.""" + + def decorator(func: Callable[[], str]) -> Callable[[], str]: + @wraps(func) + def wrapper() -> str: + return HTML_TAG_TEMPLATE.format(tag=tag, text=func()) + + return wrapper + + return decorator + + +## @brief Wrap the text of a function in `` tags. +make_bold = _tag_decorator(BOLD_TAG) + +## @brief Wrap the text of a function in `` tags. +make_emphasis = _tag_decorator(EMPHASIS_TAG) + +## @brief Wrap the text of a function in `` tags. +make_underlined = _tag_decorator(UNDERLINE_TAG) + + +## @brief Greeting with the three decorators stacked; the nearest applies first. +@make_bold +@make_emphasis +@make_underlined +def say_hello() -> str: + """Return the greeting.""" + return GREETING + + +## @brief The same greeting without any decorator. +def plain_hello() -> str: + """Return the greeting.""" + return GREETING + + +## @brief Print the lecture 6 demo. +def main() -> None: + """Print the plain, hand-decorated and `@` decorated greeting.""" + print(PLAIN_DEMO_LINE.format(value=plain_hello())) + print(BY_HAND_DEMO_LINE.format(value=make_bold(plain_hello)())) + print(AT_SYNTAX_DEMO_LINE.format(value=say_hello())) + print(NAME_DEMO_LINE.format(value=say_hello.__name__)) + + +if __name__ == "__main__": + main() diff --git a/src/flask_day_54/domain/first_class_functions.py b/src/flask_day_54/domain/first_class_functions.py new file mode 100644 index 0000000..2bcd6f9 --- /dev/null +++ b/src/flask_day_54/domain/first_class_functions.py @@ -0,0 +1,66 @@ +## @file first_class_functions.py +# @brief Lecture 5 demo of functions as first-class objects. +"""Functions can be passed as arguments, nested and returned like any value.""" + +from collections.abc import Callable + +from flask_day_54.domain.constants import ( + ADD_DEMO_LINE, + NESTED_FUNCTION_MESSAGE, + OUTER_DEMO_LINE, + RETURNED_DEMO_LINE, + SUBTRACT_DEMO_LINE, +) + + +## @brief Add two numbers. +def add(n1: float, n2: float) -> float: + """Return the sum of the two numbers.""" + return n1 + n2 + + +## @brief Subtract the second number from the first. +def subtract(n1: float, n2: float) -> float: + """Return the first number minus the second.""" + return n1 - n2 + + +## @brief Apply a function passed as argument to two numbers. +# @param func The function to call with `n1` and `n2`. +def calculate(n1: float, n2: float, func: Callable[[float, float], float]) -> float: + """Return `func(n1, n2)`.""" + return func(n1, n2) + + +## @brief Call a function that is defined inside this one. +def outer_function() -> str: + """Return the result of the nested function, reachable only in here.""" + + def nested_function() -> str: + return NESTED_FUNCTION_MESSAGE + + return nested_function() + + +## @brief Hand the nested function to the caller. +def returns_nested_function() -> Callable[[], str]: + """Return the nested function so it can be stored and called later.""" + + def nested_function() -> str: + return NESTED_FUNCTION_MESSAGE + + return nested_function + + +## @brief Print the lecture 5 demo. +def main() -> None: + """Print the results of the first-class function examples.""" + print(ADD_DEMO_LINE.format(value=calculate(2, 3, add))) + print(SUBTRACT_DEMO_LINE.format(value=calculate(5, 3, subtract))) + print(OUTER_DEMO_LINE.format(value=outer_function())) + stored = returns_nested_function() + print(RETURNED_DEMO_LINE.format(value=stored())) + + +if __name__ == "__main__": + main() diff --git a/tests/unit/test_decorators.py b/tests/unit/test_decorators.py new file mode 100644 index 0000000..79e3323 --- /dev/null +++ b/tests/unit/test_decorators.py @@ -0,0 +1,43 @@ +from collections.abc import Callable + +from flask_day_54.domain.decorators import ( + make_bold, + make_emphasis, + make_underlined, + plain_hello, + say_hello, +) + + +def test_make_bold_wraps_text_in_b_tags() -> None: + assert make_bold(plain_hello)() == "Hello, World!" + + +def test_make_emphasis_wraps_text_in_em_tags() -> None: + assert make_emphasis(plain_hello)() == "Hello, World!" + + +def test_make_underlined_wraps_text_in_u_tags() -> None: + assert make_underlined(plain_hello)() == "Hello, World!" + + +def test_say_hello_applies_stacked_decorators_nearest_first() -> None: + assert say_hello() == "Hello, World!" + + +def test_plain_hello_is_not_decorated() -> None: + assert plain_hello() == "Hello, World!" + + +def test_decorator_keeps_name_and_docstring_of_wrapped_function() -> None: + assert say_hello.__name__ == "say_hello" + assert say_hello.__doc__ == "Return the greeting." + + +def test_decorator_wraps_function_returning_another_string() -> None: + def goodbye() -> str: + return "Bye" + + decorated: Callable[[], str] = make_bold(goodbye) + + assert decorated() == "Bye" diff --git a/tests/unit/test_first_class_functions.py b/tests/unit/test_first_class_functions.py new file mode 100644 index 0000000..52ee485 --- /dev/null +++ b/tests/unit/test_first_class_functions.py @@ -0,0 +1,42 @@ +from flask_day_54.domain import first_class_functions +from flask_day_54.domain.first_class_functions import ( + add, + calculate, + outer_function, + returns_nested_function, + subtract, +) + + +def test_add_returns_sum_of_two_numbers() -> None: + assert add(2, 3) == 5 + + +def test_subtract_returns_difference_of_two_numbers() -> None: + assert subtract(5, 3) == 2 + + +def test_calculate_applies_add_when_add_is_passed() -> None: + assert calculate(2, 3, add) == 5 + + +def test_calculate_applies_subtract_when_subtract_is_passed() -> None: + assert calculate(5, 3, subtract) == 2 + + +def test_calculate_applies_lambda_when_lambda_is_passed() -> None: + assert calculate(4, 3, lambda n1, n2: n1 * n2) == 12 + + +def test_outer_function_returns_nested_function_result() -> None: + assert outer_function() == "Hello from the nested function" + + +def test_returned_nested_function_is_callable_independently() -> None: + stored = returns_nested_function() + + assert stored() == "Hello from the nested function" + + +def test_nested_function_is_not_a_module_attribute() -> None: + assert not hasattr(first_class_functions, "nested_function")