Making keyword arguments required

linsomniac · linsomniac · commit 3b56efe98441 · 2023-12-20T08:23:14.000-07:00
diff --git a/README.md b/README.md
@@ -119,11 +119,11 @@ Enable an Apache module:
 ```python
 from uplaybook import fs, core, pyinfra
 
-core.playbook_args(
+core.playbook_args(options=[
         core.Argument(name="module_name", description="Name of module"),
         core.Argument(name="remove", type="bool", default=False,
                       description="Remove the module rather than install it"),
-        )
+        ])
 
 def restart_and_enable_apache():
     pyinfra.systemd.service(service="apache2", restarted=True, enabled=True)
diff --git a/docs/index.md b/docs/index.md
@@ -19,7 +19,7 @@ uPlaybook playbooks are written in Python but follow some specific conventions:
 - Declare desired state rather than imperatively defining steps
 - Tasks communicate if they changed something
 - Changed tasks can trigger handlers
-- Jinja2 templating with
+- Jinja2 templating of many argument values
 - Status output
 
 To get started, see the [Getting Started Guide](getting_started.md)
diff --git a/docs/playbooks/basics.md b/docs/playbooks/basics.md
@@ -178,7 +178,7 @@ fs.cp(src="site.conf.j2", path="/etc/apache2/sites-available/site.conf").notify(
 Playbooks can include arguments and options for customizing the playbook run.  For
 example:
 
-    core.playbook_args(
+    core.playbook_args(options=[
             core.Argument(name="playbook_name",
                           description="Name of playbook to create, creates directory of this name."),
             core.Argument(name="git", default=False, type="bool",
@@ -188,7 +188,7 @@ example:
             core.Argument(name="force", default=False, type="bool",
                           description="Reset the playbook back to the default if it "
                           "already exists (default is to abort if playbook already exists)."),
-            )
+            ])
 
 This set up an argument of "playbook_name" and options of "--git", "--single-file", and
 "--force".
diff --git a/docs/tutorial.md b/docs/tutorial.md
@@ -173,9 +173,9 @@ specified on the command-line:
 ```python
 from uplaybook import pyinfra, fs, core, ARGS   # <-- Need "core, ARGS" now
 
-core.playbook_args(
+core.playbook_args(options=[
     core.Argument(name="module_name"),
-)
+])
 
 def restart_apache():
     pyinfra.systemd.service(service="apache2", restarted=True)
@@ -343,7 +343,7 @@ fs.cp(dst="{{ dirname | default('/var/lib/my_project') }}/my_project.config")
 
 ### Keyword Arguments
 
-To make playbooks more clear, it's a convention to always use the argument keyword name:
+To make playbooks more clear, it's required to always use the argument keyword name:
 
 ```python
 fs.cp(src="foo", dst="bar")
@@ -391,6 +391,7 @@ to the blog webserver.
 
 from uplaybook import core
 
+#  this is needed for "--help" to work
 core.playbook_args()
 
 [...]
diff --git a/examples/apt-thirdparty-install/playbook b/examples/apt-thirdparty-install/playbook
@@ -11,9 +11,13 @@ from uplaybook import fs, core, pyinfra, ARGS
 import sys
 
 core.playbook_args(
-    core.Argument(
-        name="package-name", description="Name of the package to install.", default=None
-    ),
+    options=[
+        core.Argument(
+            name="package-name",
+            description="Name of the package to install.",
+            default=None,
+        ),
+    ]
 )
 
 packages = {
diff --git a/examples/install-apache-module/playbook b/examples/install-apache-module/playbook
@@ -7,16 +7,18 @@ Apache modules need to be installed, configured, and Apache restarted to
 take effect.  This does all of that.
 """
 
-from uplaybook import fs, core, pyinfra
+from uplaybook import fs, core, pyinfra, ARGS
 
 core.playbook_args(
-    core.Argument(name="module_name", description="Name of module"),
-    core.Argument(
-        name="remove",
-        type="bool",
-        default=False,
-        description="Remove the module rather than install it",
-    ),
+    options=[
+        core.Argument(name="module_name", description="Name of module"),
+        core.Argument(
+            name="remove",
+            type="bool",
+            default=False,
+            description="Remove the module rather than install it",
+        ),
+    ]
 )
 
 
diff --git a/examples/new-uplaybook/playbook b/examples/new-uplaybook/playbook
@@ -9,7 +9,7 @@ used as a skeleton to create new uplaybooks.
 
 from uplaybook import fs, core, ARGS
 
-core.playbook_args(
+core.playbook_args(options=[
         core.Argument(name="playbook_name",
                       description="Name of playbook to create, creates directory of this name."),
         core.Argument(name="git", default=False, type="bool",
@@ -19,7 +19,7 @@ core.playbook_args(
         core.Argument(name="force", default=False, type="bool",
                       description="Reset the playbook back to the default if it already "
                       "exists (default is to abort if playbook already exists)."),
-        )
+        ])
 
 if ARGS.git and ARGS.single_file:
     core.fail(msg="*** ERROR: Cannot do '--git' with '--single-file'.")
diff --git a/examples/new-uplaybook/playbook.j2 b/examples/new-uplaybook/playbook.j2
@@ -10,8 +10,8 @@ from uplaybook import fs, core
 
 #  example arguments
 #  This sets up the playbook to be called as "up playbook <NAME> [--force] [--optional=foo]"
-core.playbook_args(
+core.playbook_args(options=[
         core.Argument(name="name", description="Name of subdirectory"),
         core.Argument(name="force", default=False, type="bool", description="Reset if already exists?"),
         core.Argument(name="optional", default="default", description="Optional argument"),
-        )
+        ])
diff --git a/tests/test_basics/args.pb b/tests/test_basics/args.pb
@@ -1,17 +1,17 @@
 #!/usr/bin/env -S python3 -m uplaybook.cli
 
-from uplaybook import fs, core
+from uplaybook import fs, core, ARGS
 
-core.playbook_args(
+core.playbook_args(options=[
         core.Argument(name="release_name"),
         core.Argument(name="arg1", default=False, type="bool"),
         core.Argument(name="arg2", default="default"),
         core.Argument(name="arg3", default="default"),
         core.Argument(name="is_owner", default=False, type="bool"),
-        )
+        ])
 #eval "$UP2 args.pb" release --arg1 --arg2=value || RETCODE=$?
 
-core.debug("{{ARGS}}")
+core.debug(msg="{{ARGS}}")
 assert ARGS.release_name == "release"
 assert ARGS.arg1 == True
 assert ARGS.arg2 == "value"
diff --git a/tests/test_basics/basics.pb b/tests/test_basics/basics.pb
@@ -6,7 +6,7 @@ fs.rm(path="testdir", recursive=True)
 fs.mkdir(path="testdir")
 with fs.cd(path="testdir"):
     fs.cp(path="testfile")
-    assert fs.exists("testfile")
+    assert fs.exists(path="testfile")
 
 core.run(command="date")
 r = core.run(command="true")
@@ -15,7 +15,7 @@ r = core.run(command="false", ignore_failure=True)
 assert not r
 
 var = "bar"
-r = core.render("foo{{ var }}")
+r = core.render(s="foo{{ var }}")
 assert r == "foobar"
 core.debug(msg="Expanding template: {{var}}")
 core.print(msg="Expanding template: {{var}}")
@@ -35,5 +35,5 @@ assert not test_handler.ran
 core.flush_handlers()
 assert test_handler.ran
 
-core.exit(0)
-core.run("false")   #  if control gets here, the exit above didn't work
+core.exit(returncode=0)
+core.run(command="false")   #  if control gets here, the exit above didn't work
diff --git a/tests/test_basics/include.pb b/tests/test_basics/include.pb
@@ -5,10 +5,10 @@ import jinja2
 
 include_test_main = "xyzzy"
 core.include(playbook="sub1.pb")
-assert core.render("{{ include_test_sub1 }}") == "xyzzy1"
+assert core.render(s="{{ include_test_sub1 }}") == "xyzzy1"
 core.include(playbook="sub2.pb", hoist_vars=False)
 try:
-    core.render("{{ include_test_sub2 }}")
+    core.render(s="{{ include_test_sub2 }}")
     raise AssertionError("Variable 'include_test_sub2' was hoisted when hoist_vars=False")
 except jinja2.exceptions.UndefinedError:
     pass
diff --git a/tests/test_basics/notify.pb b/tests/test_basics/notify.pb
@@ -6,25 +6,25 @@ from uplaybook import fs, core
 fs.rm(path="testdir", recursive=True)
 fs.mkdir(path="testdir")
 
-core.notify(lambda: fs.rm(path="testdir", recursive=True))
+core.notify(handler=lambda: fs.rm(path="testdir", recursive=True))
 fs.cp(path="testdir/testfile")
-assert fs.exists("testdir/testfile")
+assert fs.exists(path="testdir/testfile")
 core.flush_handlers()
-assert not fs.exists("testdir/testfile")
+assert not fs.exists(path="testdir/testfile")
 
 #  list of handlers
 fs.rm(path="testdir", recursive=True)
 fs.mkdir(path="testdir")
 
-fs.mkfile(path="testdir/remove_me").notify([
+fs.mkfile(path="testdir/remove_me").notify(handler=[
     lambda: fs.rm(path="testdir/remove_me"),
     lambda: fs.mkfile(path="testdir/create_me")
     ])
-assert fs.exists("testdir/remove_me")
-assert not fs.exists("testdir/create_me")
+assert fs.exists(path="testdir/remove_me")
+assert not fs.exists(path="testdir/create_me")
 core.flush_handlers()
-assert not fs.exists("testdir/remove_me")
-assert fs.exists("testdir/create_me")
+assert not fs.exists(path="testdir/remove_me")
+assert fs.exists(path="testdir/create_me")
 
 #  clean up
 fs.rm(path="testdir", recursive=True)
diff --git a/tests/test_basics/sub1.pb b/tests/test_basics/sub1.pb
@@ -2,6 +2,6 @@
 
 from uplaybook import fs, core
 
-assert core.render("{{ include_test_main }}") == "xyzzy"
+assert core.render(s="{{ include_test_main }}") == "xyzzy"
 include_test_sub1 = "xyzzy1"
-assert core.render("{{ include_test_sub1 }}") == "xyzzy1"
+assert core.render(s="{{ include_test_sub1 }}") == "xyzzy1"
diff --git a/tests/test_basics/sub2.pb b/tests/test_basics/sub2.pb
@@ -2,6 +2,6 @@
 
 from uplaybook import fs, core, up_context
 
-assert core.render("{{ include_test_main }}") == "xyzzy"
+assert core.render(s="{{ include_test_main }}") == "xyzzy"
 include_test_sub2 = "xyzzy2"
-assert core.render("{{ include_test_sub2 }}") == "xyzzy2"
+assert core.render(s="{{ include_test_sub2 }}") == "xyzzy2"
diff --git a/tests/test_copy/recursive.pb b/tests/test_copy/recursive.pb
@@ -8,4 +8,4 @@ fs.rm(path="testdir", recursive=True)
 fs.mkdir(path="testdir")
 with fs.cd(path="testdir"):
     fs.cp(src="src", path=".", recursive=True)
-assert core.grep("testdir/src_template", "secret=xyzzy")
+assert core.grep(path="testdir/src_template", search="secret=xyzzy")
diff --git a/tests/test_fs/fs.pb b/tests/test_fs/fs.pb
@@ -9,29 +9,29 @@ with fs.cd(path="testdir"):
     with open("srcfile", "w") as fp:
         fp.write("Hello!")
     fs.mv(src="srcfile", path="dest")
-    core.run("ls")
-    assert not os.path.exists("srcfile")
+    core.run(command="ls")
+    assert not os.path.exists(path="srcfile")
 
     #  moving when dest exists
     with open("srcfile", "w") as fp:
         fp.write("Hello!")
     fs.mv(src="srcfile", path="dest")
-    assert os.path.exists("dest")
-    assert not os.path.exists("srcfile")
+    assert os.path.exists(path="dest")
+    assert not os.path.exists(path="srcfile")
 
     #  moving when src does not exist
     fs.mv(src="srcfile", path="dest")
-    assert os.path.exists("dest")
+    assert os.path.exists(path="dest")
 
     #  test templating file names
     project_name = "my_project"
     fs.cp(src="project", path=".")
-    assert os.path.exists("my_project/my_project_test")
+    assert os.path.exists(path="my_project/my_project_test")
     core.grep(path="my_project/my_project_test", search="This is a test")
     core.grep(path="my_project/my_project_subdir/my_project_subfile", search="Another test")
-    assert not os.path.exists("{{project_name}}/{{project_name}}_subdir/{{project_name}}_subfile")
+    assert not os.path.exists(path="{{project_name}}/{{project_name}}_subdir/{{project_name}}_subfile")
 
     #  test NOT-templating file names
     project_name = "my_project"
     fs.cp(src="project", path=".", template_filenames=False)
-    assert os.path.exists("{{project_name}}/{{project_name}}_subdir/{{project_name}}_subfile")
+    assert os.path.exists(path="{{project_name}}/{{project_name}}_subdir/{{project_name}}_subfile")
diff --git a/uplaybook/core.py b/uplaybook/core.py
@@ -281,11 +281,11 @@ class Argument:
     Examples:
 
     ```python
-    core.playbook_args(
+    core.playbook_args(options=[
             core.Argument(name="user"),
             core.Argument(name="hostname", default=None)
             core.Argument(name="enable", type="bool", default=True)
-            )
+            ])
     core.debug(msg="Arguments: user={{ARGS.user}}  hostname={{ARGS.hostname}} enable={{ARGS.enable}}")
 
     #  Run with "up2 playbookname --hostname=localhost --no-enable username
@@ -307,7 +307,7 @@ def __init__(
 
 @task
 def playbook_args(
-    *options: List[Argument],
+    options: List[Argument],
 ) -> None:
     """
     Specify arguments for a playbook.
@@ -319,11 +319,11 @@ def playbook_args(
     Examples:
 
     ```python
-    core.playbook_args(
+    core.playbook_args(options=[
             core.Argument(name="is_owner", default=False, type="bool"),
             core.Argument(name="user"),
             core.Argument(name="hostname", default="localhost")
-            )
+            ])
     core.debug(msg="Arguments: user={{playbook_args.user}}  hostname={{playbook_args.hostname}}")
     core.debug(msg="Arguments: is_owner={{playbook_args.is_owner}}")
     #  run examples:
diff --git a/uplaybook/fs.py b/uplaybook/fs.py
@@ -224,7 +224,7 @@ def cd(path: TemplateStr) -> Return:
     return Return(
         changed=False,
         extra=SimpleNamespace(old_dir=old_dir),
-        context_manager=lambda: cd(old_dir),
+        context_manager=lambda: cd(path=old_dir),
     )
 
 
@@ -314,7 +314,7 @@ def mkdir(
         return Return(changed=True)
 
     with CallDepth():
-        chmod(path, mode, is_directory=True)
+        chmod(path=path, mode=mode, is_directory=True)
 
     return Return(changed=False)
 
@@ -748,12 +748,12 @@ def fs(
             raise ValueError(f"Unknown action: {action}")
 
         if mode is not None:
-            chmod(path, mode)
+            chmod(path=path, mode=mode)
         if owner is not None or group is not None:
-            chown(path, owner, group)
+            chown(path=path, owner=owner, group=group)
 
     if notify is not None:
-        r = r.notify(notify)
+        r = r.notify(handler=notify)
 
     return Return(changed=r.changed)
 
diff --git a/uplaybook/internals.py b/uplaybook/internals.py
