Merge pull request #79 from AdaGold/ar/optional-doesnt-mean-optional

anselrognlie · web-flow · commit a3585de19adc · 2025-02-26T10:47:37.000-08:00
Update verbiage in Task List optional enhancements
diff --git a/ada-project-docs/optional-enhancements.md b/ada-project-docs/optional-enhancements.md
@@ -28,36 +28,16 @@ How would you write tests for it? How would you implement it?
 
 Your decisions should not break the other tests.
 
-### Model Instance Methods
-
-We can define instance methods in our model classes.
-
-Consider places in your code that deal with one model at a time. Is there any repeated logic or behavior?
-
-Here are some ideas to start:
-
-- Create an instance method in `Task` named `to_dict()`
-    - Converts a `Task` instance into JSON
-    - Returns a Python dictionary in the shape of the JSON our API returns in the `GET` `/tasks` route
-- Create a class method in `Task` named `from_json()`
-    - Converts JSON into a new instance of `Task`
-    - Takes in a dictionary in the shape of the JSON our API receives in the create and update routes
-    - Returns an instance of `Task` 
-
 ### Use List Comprehensions
 
 Use list comprehensions in your route functions where applicable.
 
-### Route Helper Methods
-
-If you have not already refactored your route files to use helper methods, do so now!
-
-Consider code with complex or repetitive logic, and refactor it into helper methods. Watch your route files become cleaner and more readable!
-
 ### More Query Params
 
 Create the tests and implementation so that the user may
 
 - filter tasks by title
 - sort tasks by id
 - sort goals by title
+
+Remember that Wave 2 already has a sorting feature for tasks by title, so we might practice creating another route helper method that can be used for sorting across multiple model types. Such a method could even be extended to perform the filtering as well!
diff --git a/ada-project-docs/wave_01.md b/ada-project-docs/wave_01.md
@@ -36,12 +36,30 @@ Tasks should contain these attributes. **The tests require the following columns
 - We can assume that the value of each task's `completed_at` attribute will be `None`, until wave 3. (Read below for examples)
 - We can assume that the API will designate `is_complete` as `false`, until wave 3. (Read below for examples)
 
+## Model Helper Methods
+
+We have seen that we can define instance methods in our model classes. We should practice those skills here by including model helper methods that can:
+
+- Return a Python dictionary in the shape of the JSON our API expects to return for a model instance.
+- Create a new model instance from a dictionary, typically retrieved from the JSON sent as a request body.
+
+## Route Helper Methods
+
+Beyond model helper methods, we should also practice creating route helper methods. Especially in this wave, we should consider creating a route helper method that can:
+
+- Retrieve a model instance by its ID.
+
+We might also consider creating a route helper method that can:
+
+- Handle the creation of new instances of a model from a dictionary, returning the expected responses.
+
 ## CRUD for Tasks
 
 ### Tips
 
-- Pay attention to the exact shape of the expected JSON. Double-check nested data structures and the names of the keys for any mispellings.
-  - That said, remember that dictionaries do not have an implied order. This is still true in JSON with objects. When you make Postman requests, the order of the key/value pairings within the response JSON object does not need to match the order specified in this document. (The term "object" in JSON is analagous to "dictionary" in Python.)
+- Pay attention to the exact shape of the expected JSON. Double-check nested data structures and the names of the keys for any misspellings.
+  - That said, remember that dictionaries do not have an implied order. This is still true in JSON with objects. When you make Postman requests, the order of the key/value pairings within the response JSON object does not need to match the order specified in this document. (The term "object" in JSON is analogous to "dictionary" in Python.)
+  - Notice that the details for a Task in the response is shared across all the endpoints that return Task details. Rather than repeating the same literal `dict` structure in each response, we should create a helper method that returns the `dict` structure for a Task, and use it in each relevant endpoint. This will ensure that all our responses are consistent.
 - Use the tests in `tests/test_wave_01.py` to guide your implementation.
 - You may feel that there are missing tests and missing edge cases considered in this wave. This is intentional.
   - You have fulfilled wave 1 requirements if all of the wave 1 tests pass.
@@ -87,6 +105,10 @@ and get this response:
 
 so that I know I successfully created a Task that is saved in the database.
 
+Remember that the knowledge of how to initialize a new model instance from the request dictionary is often left to the model itself, as it allows the model to control which fields are required and how they are initialized. We could add a class method to the Task model that initializes a new instance from a dictionary, and use this method in the route. If all of our models have this method, we could create a route helper method that initializes a new model instance from a dictionary, and use it in this route and any other route that creates a new model instance.
+
+Further, notice that the data nested under the `"task"` key is a dictionary representation of the task that was created. Creating a model helper method to return this dictionary, which we can then use to help build this route response, will improve the consistency of our endpoints.
+
 #### Get Tasks: Getting Saved Tasks
 
 As a client, I want to be able to make a `GET` request to `/tasks` when there is at least one saved task and get this response:
@@ -110,6 +132,8 @@ As a client, I want to be able to make a `GET` request to `/tasks` when there is
 ]
 ```
 
+Notice that each data item in the list is a dictionary representation of a task. Creating a model helper method to return this dictionary, which we can then use to help build this route response, will improve the consistency of our endpoints.
+
 #### Get Tasks: No Saved Tasks
 
 As a client, I want to be able to make a `GET` request to `/tasks` when there are zero saved tasks and get this response:
@@ -137,6 +161,10 @@ As a client, I want to be able to make a `GET` request to `/tasks/1` when there
 }
 ```
 
+Notice that the data nested under the `"task"` key is a dictionary representation of the task that was retrieved. Creating a model helper method to return this dictionary, which we can then use to help build this route response, will improve the consistency of our endpoints.
+
+Further, we should remember that retrieving a model by its ID is a common operation. We should consider creating a route helper method that can retrieve a model by its ID, and use it in this route. This method could start out only working for Task models. But knowing that we'll be working with Goal models later on, it might be worth generalizing this method to work with any model.
+
 #### Update Task
 
 As a client, I want to be able to make a `PUT` request to `/tasks/1` when there is at least one saved task with this request body:
@@ -156,6 +184,8 @@ The response should have a mimetype of "application/json" to keep our API respon
 
 Note that the update endpoint does update the `completed_at` attribute. This will be updated with custom endpoints implemented in Wave 3.
 
+We should remember that retrieving a model by its ID is a common operation. We should consider creating a route helper method that can retrieve a model by its ID, and use it in this route. This method could start out only working for Task models. But knowing that we'll be working with Goal models later on, it might be worth generalizing this method to work with any model.
+
 #### Delete Task: Deleting a Task
 
 As a client, I want to be able to make a `DELETE` request to `/tasks/1` when there is at least one saved task and get this response:
@@ -164,6 +194,8 @@ As a client, I want to be able to make a `DELETE` request to `/tasks/1` when the
 
 The response should have a mimetype of "application/json" to keep our API response type consistent.
 
+We should remember that retrieving a model by its ID is a common operation. We should consider creating a route helper method that can retrieve a model by its ID, and use it in this route. This method could start out only working for Task models. But knowing that we'll be working with Goal models later on, it might be worth generalizing this method to work with any model.
+
 #### No Matching Task: Get, Update, and Delete
 
 As a client, if I make any of the following requests:
@@ -179,7 +211,8 @@ The response code should be `404`.
 You may choose the response body.
 
 Make sure to complete the tests for non-existing tasks to check that the correct response body is returned.
- 
+
+By using a helper method to retrieve a model by its ID, we could ensure that the response for a non-existing model is consistent across all these routes.
 
 #### Create a Task: Invalid Task With Missing Data
 
diff --git a/ada-project-docs/wave_02.md b/ada-project-docs/wave_02.md
@@ -10,7 +10,7 @@ The following are required routes for wave 2. Feel free to implement the routes
 
 ### Tips
 
-- Pay attention to the exact shape of the expected JSON. Double-check nested data structures and the names of the keys for any mispellings.
+- Pay attention to the exact shape of the expected JSON. Double-check nested data structures and the names of the keys for any misspellings.
 - Use the tests in `tests/test_wave_02.py` to guide your implementation.
 - You may feel that there are missing tests and missing edge cases considered in this wave. This is intentional.
   - You have fulfilled wave 2 requirements if all of the wave 2 tests pass.
diff --git a/ada-project-docs/wave_03.md b/ada-project-docs/wave_03.md
@@ -23,7 +23,7 @@ The following are required routes for wave 3. Feel free to implement the routes
 - SQL's value of `null` is similar to Python's value of `None`.
 - Python has a [datetime library](https://docs.python.org/3/library/datetime.html#module-datetime) which we recommend using to represent dates in model attributes.
 
-### Mark Complete on an Incompleted Task
+### Mark Complete on an Incomplete Task
 
 Given a task that has:
 
@@ -113,7 +113,11 @@ After I have made the `PATCH` request, I can submit a `GET` request to `/tasks/1
 }
 ```
 
-### Mark Incomplete on an Incompleted Task
+Notice the same dictionary structure for the Task data as in our wave 1 routes. We should be able to use any response model helper that we are using in other Task routes to help build this response.
+
+Also notice that fundamentally, this route requires that we look up a model by its ID, and then update that model. We should be able to reuse the same route helper methods that we have been using in other Task routes to help build this route.
+
+### Mark Incomplete on an Incomplete Task
 
 Given a task that has:
 
@@ -143,6 +147,10 @@ After I have made the `PATCH` request, I can submit a `GET` request to `/tasks/1
 }
 ```
 
+Notice the same dictionary structure for the Task data as in our wave 1 routes. We should be able to use any response model helper that we are using in other Task routes to help build this response.
+
+Also notice that fundamentally, this route requires that we look up a model by its ID, and then update that model. We should be able to reuse the same route helper methods that we have been using in other Task routes to help build this route.
+
 ## Mark Complete and Mark Incomplete for Missing Tasks
 
 Given that there are no tasks with the ID `1`,
@@ -154,3 +162,5 @@ Then I get a `404 Not Found`.
 You may choose the response body.
 
 Make sure to complete the tests for non-existing tasks to check that the correct response body is returned.
+
+Notice that the behavior for a missing Task is consistent with invalid Task IDs in other Task routes. We should be able to use the same route helper methods that we have been using in other Task routes to help build this route.
diff --git a/ada-project-docs/wave_04.md b/ada-project-docs/wave_04.md
@@ -119,7 +119,7 @@ Press the "Test Method" button!
 Scroll down to see the HTTP response. Answer the following questions:
 
 - Did we get a success message? If so, did we see the message in our actual Slack workspace?
-- Did we get an error emssage? If so, why?
+- Did we get an error message? If so, why?
 - What is the shape of this JSON? Is it a JSON object or array? What keys and values are there?
 
 ### Verify with Postman
diff --git a/ada-project-docs/wave_05.md b/ada-project-docs/wave_05.md
@@ -17,7 +17,7 @@ This wave requires more test writing.
 - The tests you need to write are scaffolded in the `test_wave_05.py` file. 
   - These tests are currently skipped with `@pytest.mark.skip(reason="test to be completed by student")` and the function body has `pass` in it. Once you implement these tests you should remove the `skip` decorator and the `pass`.
 - For the tests you write, use the requirements in this document to guide your test writing. 
-  - Pay attention to the exact shape of the expected JSON. Double-check nested data structures and the names of the keys for any mispellings.
+  - Pay attention to the exact shape of the expected JSON. Double-check nested data structures and the names of the keys for any misspellings.
 - You can model your tests off of the Wave 1 tests for Tasks.
 - Some tests use a [fixture](https://docs.pytest.org/en/6.2.x/fixture.html) named `one_goal` that is defined in `tests/conftest.py`. This fixture saves a specific goal to the test database.
 
@@ -68,6 +68,10 @@ and get this response:
 
 so that I know I successfully created a goal that is saved in the database.
 
+Similar to the Task model, we could add a class method to the Goal model that initializes a new instance from a dictionary, and use this method in the route. If all of our models have this method, we could create a route helper method that initializes a new model instance from a dictionary, and use it in this route and any other route that creates a new model instance.
+
+Also like the Task model, notice that the data nested under the `"goal"` key is a dictionary representation of the goal that was created. Creating a model helper method to return this dictionary, which we can then use to help build this route response, will improve the consistency of our endpoints.
+
 ### Get Goals: Getting Saved Goals
 
 As a client, I want to be able to make a `GET` request to `/goals` when there is at least one saved goal and get this response:
@@ -87,6 +91,8 @@ As a client, I want to be able to make a `GET` request to `/goals` when there is
 ]
 ```
 
+Notice that each data item in the list is a dictionary representation of a goal. Creating a model helper method to return this dictionary, which we can then use to help build this route response, will improve the consistency of our endpoints.
+
 ### Get Goals: No Saved Goals
 
 As a client, I want to be able to make a `GET` request to `/goals` when there are zero saved goals and get this response:
@@ -112,6 +118,10 @@ As a client, I want to be able to make a `GET` request to `/goals/1` when there
 }
 ```
 
+Notice that the data nested under the `"goal"` key is a dictionary representation of the goal that was retrieved. Creating a model helper method to return this dictionary, which we can then use to help build this route response, will improve the consistency of our endpoints.
+
+Further, we should remember that retrieving a model by its ID is a common operation. We should consider creating a route helper method that can retrieve a model by its ID, and use it in this route. This method would be very similar in functionality to retrieving a Task model by its ID, so rather than making an entirely new route helper method, we could generalize any similar Task model method to work also work with a Goal (or any other model).
+
 
 ### Update Goal
 
@@ -129,6 +139,8 @@ and get this response:
 
 The response should have a mimetype of "application/json" to keep our API response type consistent.
 
+We should remember that retrieving a model by its ID is a common operation. We should consider creating a route helper method that can retrieve a model by its ID, and use it in this route. This method could be written to work for Goal models, Task models, or any other model.
+
 ### Delete Goal: Deleting a Goal
 
 As a client, I want to be able to make a `DELETE` request to `/goals/1` when there is at least one saved goal and get this response:
@@ -137,6 +149,8 @@ As a client, I want to be able to make a `DELETE` request to `/goals/1` when the
 
 The response should have a mimetype of "application/json" to keep our API response type consistent.
 
+We should remember that retrieving a model by its ID is a common operation. We should consider creating a route helper method that can retrieve a model by its ID, and use it in this route. This method could be written to work for Goal models, Task models, or any other model.
+
 ### No matching Goal: Get, Update, and Delete
 
 As a client, if I make any of the following requests:
@@ -151,7 +165,9 @@ The response code should be `404`.
 
 You may choose the response body.
 
- Make sure to complete the tests for non-existing tasks to check that the correct response body is returned.
+Make sure to complete the tests for non-existing tasks to check that the correct response body is returned.
+
+By using a helper method to retrieve a model by its ID, we could ensure that the response for a non-existing model is consistent across all these routes.
 
 ### Create a Goal: Invalid Goal With Missing Title
 
diff --git a/ada-project-docs/wave_06.md b/ada-project-docs/wave_06.md
@@ -18,7 +18,7 @@ Secondly, we should create our new route, `/goals/<goal_id>/tasks`, so that our
 
 - Use lesson materials and independent research to review how to set up a one-to-many relationship in Flask.
 - Remember to run `flask db migrate` and `flask db upgrade` whenever there is a change to the model.
-- Pay attention to the exact shape of the expected JSON. Double-check nested data structures and the names of the keys for any mispellings.
+- Pay attention to the exact shape of the expected JSON. Double-check nested data structures and the names of the keys for any misspellings.
 - Use the tests in `tests/test_wave_06.py` to guide your implementation.
 - Some tests use a fixture named `one_task_belongs_to_one_goal` that is defined in `tests/conftest.py`. This fixture saves a task and a goal to the test database, and uses SQLAlchemy to associate the goal and task together.
 
@@ -63,6 +63,8 @@ Then the three `Task`s belong to the `Goal` and it gets updated in the database,
 }
 ```
 
+We will need to validate that the Goal ID, as well as each Task ID exists in the database. A route helper method that can resolve a model instance from its ID would help us validate the IDs in the request body.
+
 ### Getting Tasks of One Goal
 
 Given a goal that has:
@@ -100,6 +102,10 @@ then I get this response:
 }
 ```
 
+Notice that if we have been using a model helper method to return a dictionary representation of a Task, we can use this method to help build this route response. However, we must notice that there is an additional key in the data for the Task models that are associated with the Goal. This doesn't necessarily mean that we should abandon the model helper method, but we may need to introduce logic to allow it to work in this context.
+
+This is also true of the Goal model helper method. We may need to introduce logic to allow it to work in this context, or use the existing method to generate the basic dictionary representation of the Goal and then add the additional data for the associated Task models.
+
 ### Getting Tasks of One Goal: No Matching Tasks
 
 Given a goal that has:
