Files explicit fact imports (#613)

* Rename files fact arguments from `name` -> `path`.

Previously (with "magic" facts) only positional arguments were used,
the move to explicit imports switches to explicit kwargs, so this
updates that to match the file operations which use `path`.

* Rename `server.Which` argument `name` -> `command`.

* Handle kwargs properly in `Host.{create,delete}_fact`.

* Use explicit fact imports in files operations.

* Implement `create_fact` & `delete_fact` in the test `FakeHost`.

* Update all the operations tests using file facts for explicit imports.

* Rename files fact tests to be explicit style.

* Accept positional arguments on `Host.get_fact`.

* Update fact examples in docs to be explicit style.

Author: Fizzadar

docs/api/facts.rst

@@ -8,7 +8,14 @@ passed (as a ``list`` of lines) to the ``process`` handler to generate fact data
 Importing & Using Facts
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Facts are available in a global namespace as attributes on host objects: ``host.fact.X``. Custom fact classes will automatically be added to the namespace when the module containing them is imported. Note that the class name is converted to snake case, so ``MyFact`` becomes ``my_fact``, available as ``host.fact.my_fact``.
+Like operations, facts are imported from Python modules and executed by calling `Host.get_fact`. For example:
+
+.. code:: python
+
+    from pyinfra import host
+    from pyinfra.facts.server import Which
+
+    host.get_fact(Which, command='htop')
 
 
 Example: getting swap status
@@ -34,7 +41,7 @@ This fact could then be used like so:
 
 .. code:: python
 
-    is_swap_enabled = host.fact.swap_enabled
+    is_swap_enabled = host.get_fact(SwapEnabled)
 
 
 Example: getting the list of files in a directory
@@ -51,9 +58,9 @@ This fact returns a list of files found in a given directory. For this fact the
         Returns a list of files from a start point, recursively using find.
         '''
 
-        def command(self, name):
+        def command(self, path):
             # Find files in the given location
-            return 'find {0} -type f'.format(name)
+            return 'find {0} -type f'.format(path)
 
         def process(self, output):
             return output  # return the list of lines (files) as-is
@@ -62,7 +69,7 @@ This fact could then be used like so:
 
 .. code:: python
 
-    list_of_files = host.fact.find_files('/some/path')
+    list_of_files = host.get_fact(FindFiles, path='/somewhere')
 
 
 Example: getting any output from a command
@@ -89,4 +96,4 @@ This fact could then be used like so:
 
 .. code:: python
 
-    command_output = host.fact.raw_command_output('execute my command')
+    command_output = host.get_fact(RawCommandOutput, command='execute this command')

docs/facts.rst

@@ -8,28 +8,29 @@ Facts can be executed/tested via the command line:
 .. code:: sh
 
     # Example how to get multiple facts from a server myhost.com
-    pyinfra myhost.com fact date another_fact ...
+    pyinfra myhost.com fact server.Date server.Hostname ...
 
-If you want to see all facts:
+If you want to pass an argument to a fact, pass it with ``key=value``. For example:
 
 .. code:: sh
 
-    # Show all of the facts from myhost.com
-    pyinfra myhost.com all-facts
+    # See if the package 'openssh-server' is installed servers myhost.com and myhost2.com
+    pyinfra myhost.com,myhost2.com fact deb.DebPackage name=openssh-server
 
-If you want to pass an argument to a fact, use `:` then the argument. For example:
+Multiple facts with arguments may be called like so:
 
 .. code:: sh
 
-    # See if the package 'openssh-server' is installed servers myhost.com and myhost2.com
-    pyinfra myhost.com,myhost2.com fact deb_package:openssh-server
+    pyinfra @local fact files.File path=setup.py files.File path=anotherfile.txt
 
 You can leverage facts as part of :doc:`a deploy <deploys>` like this:
 
 .. code:: py
 
-    # If this is an Ubuntu server
-    if host.fact.linux_name == 'Ubuntu':
+    from pyinfra import host
+    from pyinfra.facts.server import LinuxName
+
+    if host.get_fact(LinuxName) == 'Ubuntu':
         apt.packages(...)
 
 **Want a new fact?** Check out :doc:`the writing facts guide <./api/facts>`.

pyinfra/api/facts.py

@@ -337,11 +337,11 @@ def get_host_fact(state, host, name, args=None, kwargs=None):
     return fact_data.get(host)
 
 
-def create_host_fact(state, host, name, data, args=None):
-    fact_data = get_facts(state, name, args=args, ensure_hosts=(host,))
+def create_host_fact(state, host, name, data, args=None, kwargs=None):
+    fact_data = get_facts(state, name, args=args, kwargs=kwargs, ensure_hosts=(host,))
     fact_data[host] = data
 
 
-def delete_host_fact(state, host, name, args=None):
-    fact_data = get_facts(state, name, args=args, ensure_hosts=(host,))
+def delete_host_fact(state, host, name, args=None, kwargs=None):
+    fact_data = get_facts(state, name, args=args, kwargs=kwargs, ensure_hosts=(host,))
     fact_data.pop(host, None)

pyinfra/api/host.py

@@ -134,14 +134,14 @@ def noop(self, description):
     # Host facts
     #
 
-    def get_fact(self, name_or_cls, **kwargs):
-        return get_host_fact(self.state, self, name_or_cls, kwargs=kwargs)
+    def get_fact(self, name_or_cls, *args, **kwargs):
+        return get_host_fact(self.state, self, name_or_cls, args=args, kwargs=kwargs)
 
-    def create_fact(self, name_or_cls, data=None, args=None):
-        return create_host_fact(self.state, self, name_or_cls, data, args)
+    def create_fact(self, name_or_cls, data=None, kwargs=None):
+        return create_host_fact(self.state, self, name_or_cls, data, kwargs=kwargs)
 
-    def delete_fact(self, name_or_cls, args=None):
-        return delete_host_fact(self.state, self, name_or_cls, args)
+    def delete_fact(self, name_or_cls, kwargs=None):
+        return delete_host_fact(self.state, self, name_or_cls, kwargs=kwargs)
 
     # Connector proxy
     #

pyinfra/facts/files.py

@@ -139,17 +139,17 @@ class Sha1File(FactBase):
         r'^SHA1\s+\(%s\)\s+=\s+([a-zA-Z0-9]{40})$',
     ]
 
-    def command(self, name):
-        self.name = name
+    def command(self, path):
+        self.path = path
         return make_formatted_string_command((
             'test -e {0} && ( '
             'sha1sum {0} 2> /dev/null || shasum {0} 2> /dev/null || sha1 {0} '
             ') || true'
-        ), QuoteString(name))
+        ), QuoteString(path))
 
     def process(self, output):
         for regex in self._regexes:
-            regex = regex % re.escape(self.name)
+            regex = regex % re.escape(self.path)
             matches = re.match(regex, output[0])
             if matches:
                 return matches.group(1)
@@ -165,19 +165,19 @@ class Sha256File(FactBase):
         r'^SHA256\s+\(%s\)\s+=\s+([a-zA-Z0-9]{64})$',
     ]
 
-    def command(self, name):
-        self.name = name
+    def command(self, path):
+        self.path = path
         return make_formatted_string_command((
             'test -e {0} && ( '
             'sha256sum {0} 2> /dev/null '
             '|| shasum -a 256 {0} 2> /dev/null '
             '|| sha256 {0} '
             ') || true'
-        ), QuoteString(name))
+        ), QuoteString(path))
 
     def process(self, output):
         for regex in self._regexes:
-            regex = regex % re.escape(self.name)
+            regex = regex % re.escape(self.path)
             matches = re.match(regex, output[0])
             if matches:
                 return matches.group(1)
@@ -193,16 +193,16 @@ class Md5File(FactBase):
         r'^SHA256\s+\(%s\)\s+=\s+([a-zA-Z0-9]{32})$',
     ]
 
-    def command(self, name):
-        self.name = name
+    def command(self, path):
+        self.path = path
         return make_formatted_string_command(
             'test -e {0} && ( md5sum {0} 2> /dev/null || md5 {0} ) || true',
-            QuoteString(name),
+            QuoteString(path),
         )
 
     def process(self, output):
         for regex in self._regexes:
-            regex = regex % re.escape(self.name)
+            regex = regex % re.escape(self.path)
             matches = re.match(regex, output[0])
             if matches:
                 return matches.group(1)
@@ -214,21 +214,19 @@ class FindInFile(FactBase):
     lines if the file exists, and ``None`` if the file does not.
     '''
 
-    def command(self, name, pattern):
-        self.exists_name = '__pyinfra_exists_{0}'.format(name)
-
-        # TODO: remove special charts from __pyinfra_exists thing
+    def command(self, path, pattern):
+        self.exists_flag = '__pyinfra_exists_{0}'.format(path)
 
         return make_formatted_string_command((
             'grep -e {0} {1} 2> /dev/null || '
             '( find {1} -type f > /dev/null && echo {2} || true )'
-        ), QuoteString(pattern), QuoteString(name), QuoteString(self.exists_name))
+        ), QuoteString(pattern), QuoteString(path), QuoteString(self.exists_flag))
 
     def process(self, output):
         # If output is the special string: no matches, so return an empty list;
         # this allows us to differentiate between no matches in an existing file
         # or a file not existing.
-        if output and output[0] == self.exists_name:
+        if output and output[0] == self.exists_flag:
             return []
 
         return output
@@ -240,10 +238,10 @@ class FindFiles(FactBase):
     '''
 
     @staticmethod
-    def command(name):
+    def command(path):
         return make_formatted_string_command(
             'find {0} -type f || true',
-            QuoteString(name),
+            QuoteString(path),
         )
 
     @staticmethod
@@ -257,10 +255,10 @@ class FindLinks(FindFiles):
     '''
 
     @staticmethod
-    def command(name):
+    def command(path):
         return make_formatted_string_command(
             'find {0} -type l || true',
-            QuoteString(name),
+            QuoteString(path),
         )
 
 
@@ -270,8 +268,8 @@ class FindDirectories(FindFiles):
     '''
 
     @staticmethod
-    def command(name):
+    def command(path):
         return make_formatted_string_command(
             'find {0} -type d || true',
-            QuoteString(name),
+            QuoteString(path),
         )

pyinfra/facts/server.py

@@ -110,8 +110,8 @@ class Which(FactBase):
     '''
 
     @staticmethod
-    def command(name):
-        return 'which {0} || true'.format(name)
+    def command(command):
+        return 'which {0} || true'.format(command)
 
 
 class Date(FactBase):