facterpy 1.0.0__py3-none-any.whl

facter/__init__.py

@@ -0,0 +1,218 @@
+import json
+import logging
+import os
+import subprocess
+from typing import Any, Dict, Generator, Iterator, Optional, Tuple, Union
+
+log = logging.getLogger("facter")
+
+
+def _parse_cli_facter_results(
+    facter_results: str,
+) -> Generator[Tuple[str, str], None, None]:
+    '''Parse key value pairs printed with "=>" separators.
+    Used as fallback when JSON output is not available.
+
+    >>> list(_parse_cli_facter_results("""foo => bar
+    ... baz => 1
+    ... foo_bar => True"""))
+    [('foo', 'bar'), ('baz', '1'), ('foo_bar', 'True')]
+    >>> list(_parse_cli_facter_results("""foo => bar
+    ... babababababababab
+    ... baz => 2"""))
+    [('foo', 'bar\nbabababababababab'), ('baz', '2')]
+    >>> list(_parse_cli_facter_results("""3434"""))
+    Traceback (most recent call last):
+        ...
+    ValueError: parse error
+
+
+    Uses a generator interface:
+    >>> _parse_cli_facter_results("foo => bar").next()
+    ('foo', 'bar')
+    '''
+    last_key, last_value = None, []
+    for line in filter(None, facter_results.splitlines()):
+        res = line.split(" => ", 1)
+        if len(res) == 1:
+            if not last_key:
+                raise ValueError("parse error")
+            # Continue multiline value
+            last_value.append(res[0])  # type: ignore[unreachable] # mypy 3.8 compat
+        else:
+            if last_key:
+                yield last_key, os.linesep.join(last_value)  # type: ignore[unreachable] # mypy 3.8 compat
+            last_key, last_value = res[0], [res[1]]
+
+    # Yield final key-value pair if exists
+    if last_key:
+        yield last_key, os.linesep.join(last_value)
+
+
+class Facter:
+    def __init__(
+        self,
+        facter_path: str = "facter",
+        external_dir: Optional[str] = None,
+        cache_enabled: bool = True,
+        puppet_facts: bool = False,
+        legacy_facts: bool = False,
+        # Deprecated - kept for backward compatibility
+        use_yaml: Optional[bool] = None,
+    ) -> None:
+        self.facter_path = facter_path
+        self.external_dir = external_dir
+        self.cache_enabled = cache_enabled
+        self.puppet_facts = puppet_facts
+        self.legacy_facts = legacy_facts
+        self._cache: Optional[Dict[str, Any]] = None
+
+        # Handle deprecated use_yaml parameter
+        if use_yaml is not None:
+            log.warning(
+                "The 'use_yaml' parameter is deprecated. "
+                "facterpy now uses JSON by default with text fallback."
+            )
+
+    @property
+    def uses_yaml(self) -> bool:
+        """Deprecated property. facterpy now uses JSON by default."""
+        log.warning(
+            "The 'uses_yaml' property is deprecated. "
+            "facterpy now uses JSON by default with text fallback."
+        )
+        return False
+
+    def run_facter(self, key: Optional[str] = None) -> Union[Dict[str, Any], Any]:
+        """Run the facter executable with an optional specific fact.
+
+        Uses JSON output by default (facter 3.0+) with fallback to plain text parsing.
+        Returns a dictionary if no key is given, and the value if a key is passed.
+
+        If legacy_facts=True, includes legacy facts (like facter --show-legacy).
+        This is required for lookup() to find legacy facts like 'architecture' that
+        don't appear in modern structured fact output but work with individual
+        facter commands (e.g., 'facter architecture').
+        """
+        base_args = [self.facter_path]
+
+        # Add common arguments
+        if self.puppet_facts:
+            base_args.append("--puppet")
+        if self.external_dir is not None:
+            base_args.extend(["--external-dir", self.external_dir])
+        if self.legacy_facts:
+            base_args.append("--show-legacy")
+        if key is not None:
+            base_args.append(key)
+
+        # Try JSON first (preferred)
+        json_args = base_args + ["--json"]
+        try:
+            proc = subprocess.Popen(
+                json_args, stdout=subprocess.PIPE, stderr=subprocess.PIPE
+            )
+            stdout, stderr = proc.communicate()
+            if proc.returncode == 0:
+                results = stdout.decode()
+                parsed_results = json.loads(results)
+                if key is not None:
+                    return parsed_results.get(key)
+                return parsed_results
+        except (json.JSONDecodeError, FileNotFoundError, subprocess.SubprocessError):
+            # Fall back to text parsing
+            pass
+
+        # Fallback to plain text output
+        try:
+            proc = subprocess.Popen(
+                base_args, stdout=subprocess.PIPE, stderr=subprocess.PIPE
+            )
+            stdout, stderr = proc.communicate()
+            if proc.returncode != 0:
+                raise RuntimeError(f"facter command failed: {stderr.decode()}")
+            results = stdout.decode()
+            if key is not None:
+                return results.strip()
+            return dict(_parse_cli_facter_results(results))
+        except (FileNotFoundError, subprocess.SubprocessError):
+            log.exception("Facter execution failed")
+            raise
+
+    def build_cache(self) -> None:
+        """run facter and save the results to `_cache`"""
+        cache = self.run_facter()
+        self._cache = cache if isinstance(cache, dict) else {}
+
+    def clear_cache(self) -> None:
+        self._cache = None
+
+    def has_cache(self) -> bool:
+        """Intended to be called before any call that might access the
+        cache. If the cache is not selected, then returns False,
+        otherwise the cache is build if needed and returns True."""
+        if not self.cache_enabled:
+            return False
+        if self._cache is None:
+            self.build_cache()
+        return True
+
+    def lookup(self, fact: str, cache: bool = True) -> Any:
+        """Return the value of a given fact and raise a KeyError if
+        it is not available. If `cache` is False, force the lookup of
+        the fact."""
+        if (not cache) or (not self.has_cache()):
+            val = self.run_facter(fact)
+            if val is None or val == "":
+                raise KeyError(fact)
+            return val
+        if self._cache is None:
+            raise RuntimeError("Cache is None but has_cache returned True")
+        return self._cache[fact]
+
+    def get(self, k: str, d: Any = None) -> Any:
+        """Dictionary-like `get` method with a default value"""
+        try:
+            return self.lookup(k)
+        except KeyError:
+            return d
+
+    @property
+    def all(self) -> Dict[str, Any]:
+        """Dictionary representation of all facts"""
+        if not self.has_cache():
+            result = self.run_facter()
+            return result if isinstance(result, dict) else {}
+        return self._cache or {}
+
+    def keys(self) -> Iterator[str]:
+        return iter(self.all.keys())
+
+    def values(self) -> Iterator[Any]:
+        return iter(self.all.values())
+
+    def items(self) -> Iterator[Tuple[str, Any]]:
+        return iter(self.all.items())
+
+    def __getitem__(self, key: str) -> Any:
+        return self.lookup(key)
+
+    def __iter__(self) -> Iterator[str]:
+        return self.keys()
+
+    def __repr__(self) -> str:
+        return (
+            f"<Facter cache_enabled={self.cache_enabled!r} "
+            f"cache_active={self._cache is not None!r}>"
+        )
+
+    def json(self) -> str:
+        """Return a json dump of all facts"""
+        return json.dumps(self.all)
+
+
+_FACTER = Facter()
+
+
+def get_fact(fact: str, default: Any = None) -> Any:
+    return _FACTER.get(fact, default)

facterpy-1.0.0.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: facterpy
+Version: 1.0.0
+Summary: Python library to provide a cached and dictionary-like interface to Puppet's facter utility
+Author: Kali Norby
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/knorby/facterpy
+Project-URL: Repository, https://github.com/knorby/facterpy
+Project-URL: Issues, https://github.com/knorby/facterpy/issues
+Keywords: facter,puppet,ruby,system,facts
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Topic :: System :: Systems Administration
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: tox; extra == "dev"
+Dynamic: license-file
+
+facterpy
+========
+
+Python library to provide a cached and dictionary-like interface to [Puppet's facter utility](http://puppetlabs.com/puppet/related-projects/facter).
+
+The library uses JSON output by default (facter 3.0+) with automatic fallback to plain text parsing for maximum compatibility and performance.
+
+Usage
+-----
+
+```python
+>>> import facter
+>>> f = facter.Facter()
+>>> f["architecture"]
+'x86_64'
+>>> f.lookup("uptime_seconds")
+195106
+>>> f.lookup("uptime_seconds")  # cached result
+195106
+>>> f.lookup("uptime_seconds", cache=False)  # force refresh
+195234
+>>> f.get("not_a_fact", "default_value")
+'default_value'
+>>> f.all  # get all facts as dictionary
+{'architecture': 'x86_64', 'uptime_seconds': 195234, ...}
+```
+
+### Advanced Usage
+
+```python
+# Custom facter path
+f = facter.Facter(facter_path="/usr/local/bin/facter")
+
+# External facts directory
+f = facter.Facter(external_dir="/etc/puppetlabs/facter/facts.d")
+
+# Include Puppet facts
+f = facter.Facter(puppet_facts=True)
+
+# Disable caching
+f = facter.Facter(cache_enabled=False)
+
+# Enable legacy facts (equivalent to facter --show-legacy)
+f = facter.Facter(legacy_facts=True)
+f.lookup("architecture")  # Works with legacy facts enabled
+f["operatingsystem"]      # Legacy facts appear in f.all
+```
+
+Install
+-------
+
+```bash
+pip install facterpy
+```
+
+Requirements
+------------
+
+**Required:**
+- Python 3.8+
+- `facter` command-line utility (install via system packages or Puppet)
+
+**No external Python dependencies** - uses only Python standard library.
+
+Compatibility
+-------------
+
+- **Python**: 3.8+ (Python 2 support removed in v0.2.0)
+- **Facter**: 3.0+ (JSON output), with fallback support for older versions
+- **Platforms**: Linux, macOS, and other POSIX systems
+
+### Legacy Facts
+
+Modern facter (4.x+) uses structured facts, so legacy top-level facts like `architecture` are nested under structured facts like `os.architecture`. To access legacy facts that were available in older facter versions:
+
+```python
+# Modern behavior (default) - structured facts only
+f = facter.Facter()
+f.lookup("architecture")  # Raises KeyError - not in structured output
+f.all["os"]["architecture"]  # Works - nested in structured facts
+
+# Legacy behavior - includes legacy facts (like facter --show-legacy)
+f = facter.Facter(legacy_facts=True)
+f.lookup("architecture")  # Works - legacy fact available
+f["architecture"]  # Works - appears in f.all output
+```
+
+Migration from v0.1.x
+---------------------
+
+**Version 1.0.0 represents a major modernization** while maintaining API compatibility. This version bump reflects the significant gap since the last release (12+ years) and commitment to not breaking existing code.
+
+- **Breaking changes**: Python 2 support removed, PyYAML dependency removed
+- **Modernization**: Complete rewrite with JSON-first approach, type hints, modern tooling
+- **API stability**: Core API unchanged to preserve compatibility with existing code
+
+**Migration notes:**
+
+```python
+# Old (deprecated, shows warning)
+f = facter.Facter(use_yaml=False)
+
+# New (recommended)
+f = facter.Facter()  # Automatically uses JSON with text fallback
+
+# For legacy fact compatibility (if needed)
+f = facter.Facter(legacy_facts=True)  # Includes pre-4.x style facts
+```
+
+Project State
+-------------
+
+I wrote this library in 2013 and did very little maintenance since then, despite some apparent usage. The library is simple and focused, which has helped it remain functional. This 1.0.0 modernization brings it up to current standards while preserving the original API. I haven't used Puppet in quite some time, so I'm not an active user of this library, but the comprehensive test suite should help ensure reliability.

facterpy-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+facter/__init__.py,sha256=iFF4EOHKfMkuvLAOm5xGuyIVBBdnRE33Kk3HowN_iRo,7556
+facterpy-1.0.0.dist-info/licenses/LICENSE,sha256=goHNs7xDDii7xgwaX1TPhEAKGIb7KdvkouwGQlF7Lsc,1283
+facterpy-1.0.0.dist-info/METADATA,sha256=2ZfN9GguL5GBk2oxxrp8DQ3W5G8T6BYnlpCG0eu-Fn8,5139
+facterpy-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+facterpy-1.0.0.dist-info/top_level.txt,sha256=-x6G-A1aImWfM5qqTno8sLrEugOXqvSmXbOrq7bgfwk,7
+facterpy-1.0.0.dist-info/RECORD,,

facterpy-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

facterpy-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2013, Kali Norby
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.  Redistributions
+in binary form must reproduce the above copyright notice, this list of
+conditions and the following disclaimer in the documentation and/or
+other materials provided with the distribution.  THIS SOFTWARE IS
+PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

facterpy-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+facter