Merge pull request #75 from mikez/main

Update docstrings: remove redundant ones and tweak spelling on others.

Author: mikez

docs/things/database.html

@@ -581,12 +581,12 @@ <h1 class="modulename">
     <span class="c1"># -------- Utility methods --------</span>
 
     <span class="k">def</span> <span class="nf">last_modified</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot;Get last modified time.&quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;Get last modified time of database filepath.&quot;&quot;&quot;</span>
         <span class="n">mtime_seconds</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">getmtime</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">filepath</span><span class="p">)</span>
         <span class="k">return</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">fromtimestamp</span><span class="p">(</span><span class="n">mtime_seconds</span><span class="p">)</span>
 
     <span class="k">def</span> <span class="nf">was_modified_today</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot;Return true of modification date is `&gt;=` that todays date.&quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;Return True if database filepath was last modified today.&quot;&quot;&quot;</span>
         <span class="n">last_modified_date</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">last_modified</span><span class="p">()</span><span class="o">.</span><span class="n">date</span><span class="p">()</span>
         <span class="n">todays_date</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span><span class="o">.</span><span class="n">date</span><span class="p">()</span>
         <span class="k">return</span> <span class="n">last_modified_date</span> <span class="o">&gt;=</span> <span class="n">todays_date</span>
@@ -756,7 +756,7 @@ <h1 class="modulename">
 
 <span class="k">def</span> <span class="nf">make_date_filter</span><span class="p">(</span><span class="n">date_column</span><span class="p">,</span> <span class="n">offset</span><span class="p">):</span>
     <span class="sd">&quot;&quot;&quot;</span>
-<span class="sd">    Return an SQL filter to limit the date range of the SQL query.</span>
+<span class="sd">    Return a SQL filter to limit the date range of the SQL query.</span>
 
 <span class="sd">    Parameters</span>
 <span class="sd">    ----------</span>
@@ -806,7 +806,7 @@ <h1 class="modulename">
 
 <span class="k">def</span> <span class="nf">make_truthy_filter</span><span class="p">(</span><span class="n">column</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
     <span class="sd">&quot;&quot;&quot;</span>
-<span class="sd">    Return an SQL filter adding a boolean column that is set to truthy or falsy.</span>
+<span class="sd">    Return a SQL filter that matches if a column is truthy or falsy.</span>
 
 <span class="sd">    Truthy means TRUE. Falsy means FALSE or NULL. This is akin</span>
 <span class="sd">    to how Python defines it natively.</span>
@@ -835,7 +835,7 @@ <h1 class="modulename">
 
 <span class="k">def</span> <span class="nf">make_search_filter</span><span class="p">(</span><span class="n">query</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
     <span class="sd">&quot;&quot;&quot;</span>
-<span class="sd">    Return an SQL filter that filters titles and notes by a string.</span>
+<span class="sd">    Return a SQL filter to search tasks by a string query.</span>
 
 <span class="sd">    Example:</span>
 <span class="sd">    --------</span>
@@ -1267,12 +1267,12 @@ <h1 class="modulename">
     <span class="c1"># -------- Utility methods --------</span>
 
     <span class="k">def</span> <span class="nf">last_modified</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot;Get last modified time.&quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;Get last modified time of database filepath.&quot;&quot;&quot;</span>
         <span class="n">mtime_seconds</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">getmtime</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">filepath</span><span class="p">)</span>
         <span class="k">return</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">fromtimestamp</span><span class="p">(</span><span class="n">mtime_seconds</span><span class="p">)</span>
 
     <span class="k">def</span> <span class="nf">was_modified_today</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot;Return true of modification date is `&gt;=` that todays date.&quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;Return True if database filepath was last modified today.&quot;&quot;&quot;</span>
         <span class="n">last_modified_date</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">last_modified</span><span class="p">()</span><span class="o">.</span><span class="n">date</span><span class="p">()</span>
         <span class="n">todays_date</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span><span class="o">.</span><span class="n">date</span><span class="p">()</span>
         <span class="k">return</span> <span class="n">last_modified_date</span> <span class="o">&gt;=</span> <span class="n">todays_date</span>
@@ -1829,14 +1829,14 @@ <h6 id="parameters">Parameters</h6>
                 <details>
             <summary>View Source</summary>
             <div class="codehilite"><pre><span></span>    <span class="k">def</span> <span class="nf">last_modified</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot;Get last modified time.&quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;Get last modified time of database filepath.&quot;&quot;&quot;</span>
         <span class="n">mtime_seconds</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">getmtime</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">filepath</span><span class="p">)</span>
         <span class="k">return</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">fromtimestamp</span><span class="p">(</span><span class="n">mtime_seconds</span><span class="p">)</span>
 </pre></div>
 
         </details>
 
-            <div class="docstring"><p>Get last modified time.</p>
+            <div class="docstring"><p>Get last modified time of database filepath.</p>
 </div>
 
 
@@ -1852,15 +1852,15 @@ <h6 id="parameters">Parameters</h6>
                 <details>
             <summary>View Source</summary>
             <div class="codehilite"><pre><span></span>    <span class="k">def</span> <span class="nf">was_modified_today</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot;Return true of modification date is `&gt;=` that todays date.&quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;Return True if database filepath was last modified today.&quot;&quot;&quot;</span>
         <span class="n">last_modified_date</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">last_modified</span><span class="p">()</span><span class="o">.</span><span class="n">date</span><span class="p">()</span>
         <span class="n">todays_date</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span><span class="o">.</span><span class="n">date</span><span class="p">()</span>
         <span class="k">return</span> <span class="n">last_modified_date</span> <span class="o">&gt;=</span> <span class="n">todays_date</span>
 </pre></div>
 
         </details>
 
-            <div class="docstring"><p>Return true of modification date is <code>&gt;=</code> that todays date.</p>
+            <div class="docstring"><p>Return True if database filepath was last modified today.</p>
 </div>
 
 
@@ -2162,7 +2162,7 @@ <h6 id="examples">Examples</h6>
             <summary>View Source</summary>
             <div class="codehilite"><pre><span></span><span class="k">def</span> <span class="nf">make_date_filter</span><span class="p">(</span><span class="n">date_column</span><span class="p">,</span> <span class="n">offset</span><span class="p">):</span>
     <span class="sd">&quot;&quot;&quot;</span>
-<span class="sd">    Return an SQL filter to limit the date range of the SQL query.</span>
+<span class="sd">    Return a SQL filter to limit the date range of the SQL query.</span>
 
 <span class="sd">    Parameters</span>
 <span class="sd">    ----------</span>
@@ -2212,7 +2212,7 @@ <h6 id="examples">Examples</h6>
 
         </details>
 
-            <div class="docstring"><p>Return an SQL filter to limit the date range of the SQL query.</p>
+            <div class="docstring"><p>Return a SQL filter to limit the date range of the SQL query.</p>
 
 <h6 id="parameters">Parameters</h6>
 
@@ -2257,7 +2257,7 @@ <h6 id="examples">Examples</h6>
             <summary>View Source</summary>
             <div class="codehilite"><pre><span></span><span class="k">def</span> <span class="nf">make_truthy_filter</span><span class="p">(</span><span class="n">column</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
     <span class="sd">&quot;&quot;&quot;</span>
-<span class="sd">    Return an SQL filter adding a boolean column that is set to truthy or falsy.</span>
+<span class="sd">    Return a SQL filter that matches if a column is truthy or falsy.</span>
 
 <span class="sd">    Truthy means TRUE. Falsy means FALSE or NULL. This is akin</span>
 <span class="sd">    to how Python defines it natively.</span>
@@ -2286,7 +2286,7 @@ <h6 id="examples">Examples</h6>
 
         </details>
 
-            <div class="docstring"><p>Return an SQL filter adding a boolean column that is set to truthy or falsy.</p>
+            <div class="docstring"><p>Return a SQL filter that matches if a column is truthy or falsy.</p>
 
 <p>Truthy means TRUE. Falsy means FALSE or NULL. This is akin
 to how Python defines it natively.</p>
@@ -2322,7 +2322,7 @@ <h6 id="examples">Examples</h6>
             <summary>View Source</summary>
             <div class="codehilite"><pre><span></span><span class="k">def</span> <span class="nf">make_search_filter</span><span class="p">(</span><span class="n">query</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
     <span class="sd">&quot;&quot;&quot;</span>
-<span class="sd">    Return an SQL filter that filters titles and notes by a string.</span>
+<span class="sd">    Return a SQL filter to search tasks by a string query.</span>
 
 <span class="sd">    Example:</span>
 <span class="sd">    --------</span>
@@ -2348,7 +2348,7 @@ <h6 id="examples">Examples</h6>
 
         </details>
 
-            <div class="docstring"><p>Return an SQL filter that filters titles and notes by a string.</p>
+            <div class="docstring"><p>Return a SQL filter to search tasks by a string query.</p>
 
 <h2 id="example">Example:</h2>
 

tests/test_things.py

@@ -20,13 +20,11 @@ class ThingsCase(unittest.TestCase):  # noqa: V103 pylint: disable=R0904
     """Class documentation goes here."""
 
     def setUp(self):
-        """Set up environment variables."""
         # Set environment variable to test database
         self.saved_filepath = os.getenv(THINGSDB)
         os.environ[THINGSDB] = TEST_DATABASE_FILEPATH
 
     def tearDown(self):
-        """Restore environment variables."""
         # Restore environment variable to its previous value
         # or delete it if it wasn't set before running the test.
         if self.saved_filepath is None:
@@ -36,20 +34,17 @@ def tearDown(self):
             os.environ[THINGSDB] = self.saved_filepath
 
     def test_get_tag_by_database_filepath(self):
-        """Test get tag by database filepath."""
         del os.environ[THINGSDB]
         tag_uuid = "Qt2AY87x2QDdowSn9HKTt1"
         tag = things.get(tag_uuid, filepath=TEST_DATABASE_FILEPATH)
         self.assertEqual(tag["uuid"], tag_uuid)  # type: ignore
 
     def test_get_url_scheme_auth_token(self):
-        """Test get url scheme auth token."""
         expected = "vKkylosuSuGwxrz7qcklOw"
         token = things.token()
         self.assertEqual(token, expected)
 
     def test_search(self):
-        """Test search."""
         tasks = things.search("wrong_query")
         self.assertEqual(0, len(tasks))
 
@@ -71,12 +66,10 @@ def test_search(self):
         self.assertEqual(3, len(todos))
 
     def test_inbox(self):
-        """Test inbox."""
         tasks = things.inbox()
         self.assertEqual(2, len(tasks))
 
     def test_trashed(self):
-        """Test getting trashed tasks."""
         tasks = things.trash()
         self.assertEqual(5, len(tasks))
         todos = things.todos(trashed=True)
@@ -102,55 +95,45 @@ def test_trashed(self):
         self.assertEqual(0, len(tasks))
 
     def test_upcoming(self):
-        """Test upcoming."""
         tasks = things.upcoming()
         self.assertEqual(1, len(tasks))
 
     def test_deadlines(self):
-        """Test deadlines."""
         tasks = things.deadlines()
         self.assertEqual(1, len(tasks))
 
     def test_today(self):
-        """Test today."""
         tasks = things.today()
         self.assertEqual(3, len(tasks))
 
     def test_checklist(self):
-        """Test checklist."""
         checklist_items = things.checklist_items("3Eva4XFof6zWb9iSfYy4ej")
         self.assertEqual(3, len(checklist_items))
         checklist_items = things.checklist_items("K9bx7h1xCJdevvyWardZDq")
         self.assertEqual(0, len(checklist_items))
 
     def test_anytime(self):
-        """Test anytime."""
         tasks = things.anytime()
         self.assertEqual(12, len(tasks))
         self.assertTrue(any(task.get("area_title") == "Area 1" for task in tasks))
 
     def test_logbook(self):
-        """Test logbook."""
         tasks = things.logbook()
         self.assertEqual(21, len(tasks))
 
     def test_canceled(self):
-        """Test canceled."""
         tasks = things.canceled()
         self.assertEqual(11, len(tasks))
 
     def test_completed(self):
-        """Test completed."""
         tasks = things.completed()
         self.assertEqual(10, len(tasks))
 
     def test_someday(self):
-        """Test someday."""
         tasks = things.someday()
         self.assertEqual(1, len(tasks))
 
-    def test_get(self):
-        """Test the function to find an object by `uuid`."""
+    def test_get_by_uuid(self):
         task = things.get("wrong_uuid")
         self.assertEqual(None, task)
         task = things.get("wrong_uuid", "NOT FOUND")
@@ -159,7 +142,6 @@ def test_get(self):
         self.assertEqual(4, len(task.keys()))  # type: ignore
 
     def test_todos(self):
-        """Test all to-dos."""
         todos = things.todos(start="Anytime")
         self.assertEqual(8, len(todos))
         todos = things.todos(start="Anytime", status="completed")
@@ -176,7 +158,6 @@ def test_todos(self):
         self.assertEqual(16, len(todo.keys()))  # type: ignore
 
     def test_tags(self):
-        """Test all tags."""
         tags = things.tags()
         self.assertEqual(5, len(tags))
         tags = things.tags(include_items=True)
@@ -187,19 +168,16 @@ def test_tags(self):
         self.assertEqual("Errand", tag["title"])  # type: ignore
 
     def test_get_link(self):
-        """Test get link."""
         link = things.link("uuid")
         self.assertEqual("things:///show?id=uuid", link)
 
     def test_projects(self):
-        """Test all projects."""
         projects = things.projects()
         self.assertEqual(3, len(projects))
         projects = things.projects(include_items=True)
         self.assertEqual(2, len(projects[0]["items"]))
 
     def test_areas(self):
-        """Test all test_areas."""
         areas = things.areas()
         self.assertEqual(3, len(areas))
         areas = things.areas(include_items=True)
@@ -212,12 +190,10 @@ def test_areas(self):
         self.assertEqual("Area 3", area["title"])  # type: ignore
 
     def test_database_version(self):
-        """Test database version."""
         version = things.Database().get_version()
         self.assertEqual(18, version)
 
     def test_last(self):
-        """Test last parameter."""
         last_tasks = things.last("0d")
         self.assertEqual(len(last_tasks), 0)
 
@@ -243,7 +219,6 @@ def test_last(self):
             things.last("3X")
 
     def test_tasks(self):
-        """Test tasks."""
         count = things.tasks(status="completed", last="100y", count_only=True)
         self.assertEqual(count, 10)
         # special characters
@@ -256,8 +231,7 @@ def test_tasks(self):
         with self.assertRaises(ValueError):
             things.tasks(area="\0")
 
-    def test_database(self):
-        """Test some database details."""
+    def test_database_details(self):
         output = io.StringIO()
         with contextlib.redirect_stdout(output):
             things.areas(print_sql=True)

things/database.py

@@ -451,12 +451,12 @@ def execute_query(self, sql_query, parameters=(), row_factory=None):
     # -------- Utility methods --------
 
     def last_modified(self):
-        """Get last modified time."""
+        """Get last modified time of database filepath."""
         mtime_seconds = os.path.getmtime(self.filepath)
         return datetime.datetime.fromtimestamp(mtime_seconds)
 
     def was_modified_today(self):
-        """Return true of modification date is `>=` that todays date."""
+        """Return True if database filepath was last modified today."""
         last_modified_date = self.last_modified().date()
         todays_date = datetime.datetime.now().date()
         return last_modified_date >= todays_date
@@ -626,7 +626,7 @@ def make_filter(column, value):
 
 def make_date_filter(date_column, offset):
     """
-    Return an SQL filter to limit the date range of the SQL query.
+    Return a SQL filter to limit the date range of the SQL query.
 
     Parameters
     ----------
@@ -676,7 +676,7 @@ def make_date_filter(date_column, offset):
 
 def make_truthy_filter(column: str, value) -> str:
     """
-    Return an SQL filter adding a boolean column that is set to truthy or falsy.
+    Return a SQL filter that matches if a column is truthy or falsy.
 
     Truthy means TRUE. Falsy means FALSE or NULL. This is akin
     to how Python defines it natively.
@@ -705,7 +705,7 @@ def make_truthy_filter(column: str, value) -> str:
 
 def make_search_filter(query: str) -> str:
     """
-    Return an SQL filter that filters titles and notes by a string.
+    Return a SQL filter to search tasks by a string query.
 
     Example:
     --------