[109] Disallow passing arguments to data functions (#123)

* changes

* doc

* version bump

* trying to change the size of headers

Co-authored-by: Tim Hunter <tjhunter@cs.stanford.edu>

Author: tjhunter

dds/_annotations.py

@@ -4,7 +4,7 @@
 from typing import Any, Callable, TypeVar, cast, Union
 
 from ._api import keep as _keep
-from .structures import DDSPath
+from .structures import DDSPath, DDSErrorCode, DDSException
 
 F = TypeVar("F", bound=Callable[..., Any])
 
@@ -55,6 +55,16 @@ def function():
     def decorator_(func: F) -> F:
         @functools.wraps(func)
         def wrapper(*args, **kwargs):
+            if len(args) > 0 or len(kwargs) > 0:
+                raise DDSException(
+                    f"@data_function cannot be used with arguments. "
+                    f"Arguments were passed to the function {func}, but this function "
+                    f"also has a dds.data_function annotation, which is not allowed (see "
+                    f"user guide of DDS). "
+                    f"Suggestion: write a wrapper function that does not take arguments itself, "
+                    f"or use dds.keep to pass arguments",
+                    DDSErrorCode.ARG_IN_DATA_FUNCTION,
+                )
             return _keep(path, func, *args, **kwargs)
 
         return cast(F, wrapper)

dds/_version.py

@@ -1 +1 @@
-version = "0.7.3"
+version = "0.8.0"

dds/fun_args.py

@@ -168,10 +168,19 @@ def get_arg_ctx(
             elif p.kind == Parameter.VAR_KEYWORD:
                 # kwargs: for now, just ignored
                 h = None
+            elif p.kind == Parameter.POSITIONAL_OR_KEYWORD:
+                # We are expecting a positional arguments, but no positional arguments
+                # was provided. This is a programming error on the user side.
+                raise DDSException(
+                    f"Missing argument {n} for function {f}. "
+                    f"DDS detected that the function {f} is missing the argument "
+                    f"{n} of type {p.kind}. This would trigger an error during the "
+                    f"execution of the code, aborting."
+                )
             else:
                 raise NotImplementedError(
                     f"Cannot deal with argument name {n} of function {f}:"
-                    f"The argument kind {p.kind} is not understood (see exact definition in"
+                    f"The argument kind {p.kind} is not understood (see exact definition in "
                     f"the module {Parameter}). Suggestion: your function is probably "
                     f"using non-standard arguments. Use arguments of a simpler sort "
                     f"(no kargs or kwargs). "

dds/structures.py

@@ -55,6 +55,7 @@ class DDSErrorCode(IntEnum):
     OBJECT_PATH_NOT_FOUND = 12
     CONSTRUCT_NOT_SUPPORTED = 13
     STORE_PATH_NOT_SUPPORTED = 14
+    ARG_IN_DATA_FUNCTION = 15
 
 
 class DDSException(BaseException):

dds_tests/test_annot_basic.py

@@ -1,6 +1,7 @@
 import dds
 import pytest
-from .utils import cleandir, Counter, spath
+from .utils import cleandir, Counter
+from dds.structures import DDSException, DDSErrorCode
 
 _ = cleandir
 
@@ -30,3 +31,22 @@ def test():
     assert _c.value == 1
     assert dds.eval(f1) == "a"
     assert _c.value == 1
+
+
+@dds.data_function("/p")
+def f2(x):
+    return "a"
+
+
+def f2_1():
+    f2(3)
+
+
+@pytest.mark.usefixtures("cleandir")
+def test_args():
+    with pytest.raises(DDSException) as e:
+        f2(3)
+    assert e.value.error_code == DDSErrorCode.ARG_IN_DATA_FUNCTION
+    with pytest.raises(DDSException) as e:
+        dds.eval(f2_1)
+    assert e.value.error_code == DDSErrorCode.ARG_IN_DATA_FUNCTION

doc_source/changelog.md

@@ -12,6 +12,9 @@ A number of small improvements in ergonomics to this release:
 * the error messages are more complete and include more contextual information
 * more types are supported by default during the analysis phase: lists, dictionaries, 
 dates (`datetime` objects), arbitrary named tuples and arbitrary data classes.
+* the input for `@data_function` has been tightened to reflect the fact that data functions
+should not take arguments (`dds.keep` should be used instead). Passing arguments
+now triggers an error.
 
 ## v0.7.2
 

doc_source/user_guide.ipynb

@@ -41,7 +41,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## User guide\n",
+    "# User guide\n",
     "\n",
     "The `dds` package solves the data integration problem in data science codebases. By using the `dds` package, you can safely assume that:\n",
     "\n",
@@ -286,7 +286,7 @@
     "As we said, the `data_function` annotation requires little code change but only works for functions that do not have arguments. How to deal with more complicated functions?\n",
     "This is the object of the next section.\n",
     "\n",
-    "## Functions with arguments: keep() and eval()\n",
+    "# Functions with arguments: keep() and eval()\n",
     "\n",
     "`dds` can also wrap functions that have arguments using the `dds.keep()` function. Here is a simple example, in which the `hello` function expects an extra word to be provided:"
    ]
@@ -405,7 +405,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Indirect references: load()\n",
+    "# Indirect references: load()\n",
     "\n",
     "So far, we have seen only one way to access data: using `dds.keep` (or its shortcut `@data_function`). \n",
     "It is not always convenient to refer to the data function that created the piece of data in the first place.\n",

docs/changelog/changelog.md

@@ -12,6 +12,9 @@ A number of small improvements in ergonomics to this release:
 * the error messages are more complete and include more contextual information
 * more types are supported by default during the analysis phase: lists, dictionaries, 
 dates (`datetime` objects), arbitrary named tuples and arbitrary data classes.
+* the input for `@data_function` has been tightened to reflect the fact that data functions
+should not take arguments (`dds.keep` should be used instead). Passing arguments
+now triggers an error.
 
 ## v0.7.2
 

docs/changelog/index.html

@@ -142,6 +142,9 @@ <h2 id="v080-unreleased">v0.8.0 (unreleased)</h2>
 <li>the error messages are more complete and include more contextual information</li>
 <li>more types are supported by default during the analysis phase: lists, dictionaries, 
 dates (<code>datetime</code> objects), arbitrary named tuples and arbitrary data classes.</li>
+<li>the input for <code>@data_function</code> has been tightened to reflect the fact that data functions
+should not take arguments (<code>dds.keep</code> should be used instead). Passing arguments
+now triggers an error.</li>
 </ul>
 <h2 id="v072">v0.7.2</h2>
 <p>Small usability fixes in this release:</p>

docs/dds-reference/index.html

@@ -198,6 +198,16 @@ <h2 class="doc doc-heading" id="dds._annotations.data_function">
     <span class="k">def</span> <span class="nf">decorator_</span><span class="p">(</span><span class="n">func</span><span class="p">:</span> <span class="n">F</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">F</span><span class="p">:</span>
         <span class="nd">@functools</span><span class="o">.</span><span class="n">wraps</span><span class="p">(</span><span class="n">func</span><span class="p">)</span>
         <span class="k">def</span> <span class="nf">wrapper</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
+            <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">args</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">0</span> <span class="ow">or</span> <span class="nb">len</span><span class="p">(</span><span class="n">kwargs</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">:</span>
+                <span class="k">raise</span> <span class="n">DDSException</span><span class="p">(</span>
+                    <span class="sa">f</span><span class="s2">"@data_function cannot be used with arguments. "</span>
+                    <span class="sa">f</span><span class="s2">"Arguments were passed to the function </span><span class="si">{</span><span class="n">func</span><span class="si">}</span><span class="s2">, but this function "</span>
+                    <span class="sa">f</span><span class="s2">"also has a dds.data_function annotation, which is not allowed (see "</span>
+                    <span class="sa">f</span><span class="s2">"user guide of DDS). "</span>
+                    <span class="sa">f</span><span class="s2">"Suggestion: write a wrapper function that does not take arguments itself, "</span>
+                    <span class="sa">f</span><span class="s2">"or use dds.keep to pass arguments"</span><span class="p">,</span>
+                    <span class="n">DDSErrorCode</span><span class="o">.</span><span class="n">ARG_IN_DATA_FUNCTION</span><span class="p">,</span>
+                <span class="p">)</span>
             <span class="k">return</span> <span class="n">_keep</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">func</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
 
         <span class="k">return</span> <span class="n">cast</span><span class="p">(</span><span class="n">F</span><span class="p">,</span> <span class="n">wrapper</span><span class="p">)</span>