besapi 4.1.4__tar.gz → 4.2.0__tar.gz

{besapi-4.1.4/src/besapi.egg-info → besapi-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: besapi
-Version: 4.1.4
+Version: 4.2.0
 Summary: Library for working with the BigFix REST API
 Home-page: https://github.com/jgstew/besapi
 Author: Matt Hansen, James Stewart
@@ -30,25 +30,38 @@ Dynamic: license-file
 
 # besapi
 
-besapi is a Python library designed to interact with the BigFix [REST API](https://developer.bigfix.com/rest-api/api/).
+[![PyPI version](https://img.shields.io/pypi/v/besapi.svg)](https://pypi.org/project/besapi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.txt)
 
-Installation:
+**besapi** is a Python library that makes it easy to work with the [BigFix REST API](https://developer.bigfix.com/rest-api/api/). It handles authentication, requests, and XML parsing for you, so you can focus on automating your BigFix environment instead of wrangling raw HTTP and XML.
 
-`pip install besapi`
+It also includes **bescli**, an interactive command-line interface for exploring the REST API — great for trying things out before writing any code.
 
-Usage:
+## Installation
 
+```bash
+pip install besapi
 ```
+
+## Quick Start
+
+Connect to your BigFix root server and start making requests:
+
+```python
 import besapi
-b = besapi.besapi.BESConnection('my_username', 'my_password', 'https://rootserver.domain.org:52311')
-rr = b.get('sites')
 
-# rr.request contains the original request object
-# rr.text contains the raw request.text data returned by the server
-# rr.besxml contains the XML string converted from the request.text
-# rr.besobj contains the requested lxml.objectify.ObjectifiedElement
+b = besapi.besapi.BESConnection(
+    "my_username", "my_password", "https://rootserver.domain.org:52311"
+)
+rr = b.get("sites")
+
+# Every request returns a RESTResult with several handy views of the response:
+#   rr.request - the original requests object
+#   rr.text    - the raw text returned by the server
+#   rr.besxml  - the response as an XML string
+#   rr.besobj  - the response as an lxml.objectify.ObjectifiedElement
 
->>>print rr
+print(rr)
 ```
 
 ```xml
@@ -78,48 +91,60 @@ rr = b.get('sites')
 </BESAPI>
 ```
 
-```
->>>rr.besobj.attrib
+### Working with results
+
+The `besobj` attribute lets you navigate the XML response like a regular Python object:
+
+```pycon
+>>> rr.besobj.attrib
 {'{http://www.w3.org/2001/XMLSchema-instance}noNamespaceSchemaLocation': 'BESAPI.xsd'}
 
->>>rr.besobj.ActionSite.attrib
+>>> rr.besobj.ActionSite.attrib
 {'Resource': 'http://rootserver.domain.org:52311/api/site/master'}
 
->>>rr.besobj.ActionSite.attrib['Resource']
+>>> rr.besobj.ActionSite.attrib["Resource"]
 'http://rootserver.domain.org:52311/api/site/master'
 
->>>rr.besobj.ActionSite.Name
+>>> rr.besobj.ActionSite.Name
 'ActionSite'
 
->>>rr.besobj.OperatorSite.Name
+>>> rr.besobj.OperatorSite.Name
 'mah60'
 
->>>for cSite in rr.besobj.CustomSite:
-...     print cSite.Name
+>>> for cSite in rr.besobj.CustomSite:
+...     print(cSite.Name)
+...
 Org
 Org/Mac
 Org/Windows
 ContentDev
-...
+```
 
->>>rr = b.get('task/operator/mah60/823975')
->>>with open('/Users/Shared/Test.bes", "wb") as file:
-...     file.write(rr.text)
+### Downloading, uploading, and deleting content
 
->>>b.delete('task/operator/mah60/823975')
+```python
+# save a task to a file:
+rr = b.get("task/operator/mah60/823975")
+with open("/Users/Shared/Test.bes", "wb") as bes_file:
+    bes_file.write(rr.text.encode("utf-8"))
 
->>> file = open('/Users/Shared/Test.bes')
->>> b.post('tasks/operator/mah60', file)
->>> b.put('task/operator/mah60/823975', file)
+# delete a task:
+b.delete("task/operator/mah60/823975")
+
+# create or update a task from a file:
+with open("/Users/Shared/Test.bes") as bes_file:
+    b.post("tasks/operator/mah60", bes_file)
+    b.put("task/operator/mah60/823975", bes_file)
 ```
 
-# Command-Line Interface
+Looking for more? The [examples folder](https://github.com/jgstew/besapi/tree/master/examples) has ready-to-run scripts for many common tasks — exporting sites, importing content, taking actions, running session relevance, and more.
+
+## Command-Line Interface
+
+The included `bescli` interactive shell is the fastest way to poke around the REST API:
 
 ```
-$ python bescli.py
-OR
->>> import bescli
->>> bescli.main()
+$ python -m bescli
 
 BigFix> login
 User [mah60]: mah60
@@ -141,20 +166,17 @@ BigFix> get fixlets/operator/mah60
 ...
 ```
 
-# BigFix REST API Documentation
+## Requirements
 
-- https://developer.bigfix.com/rest-api/
-- http://bigfix.me/restapi
-
-# Requirements
+- Python 3.9 or later
+  - besapi 1.1.3 was the last version with partial Python 2 support
+- [lxml](https://pypi.org/project/lxml/)
+- [requests](https://pypi.org/project/requests/)
+- [cmd2](https://pypi.org/project/cmd2/) (for the CLI)
 
-- Python 3.6 or later
-  - version 1.1.3 of besapi was the last to have partial python2 support
-- lxml
-- requests
-- cmd2
+All dependencies are installed automatically by pip.
 
-# Examples using BESAPI
+## More Examples Using besapi
 
 - https://github.com/jgstew/besapi/tree/master/examples
 - https://github.com/jgstew/generate_bes_from_template/blob/master/examples/generate_uninstallers.py
@@ -162,12 +184,22 @@ BigFix> get fixlets/operator/mah60
 - https://github.com/jgstew/jgstew-recipes/blob/main/SharedProcessors/BigFixActioner.py
 - https://github.com/jgstew/jgstew-recipes/blob/main/SharedProcessors/BigFixSessionRelevance.py
 
-# Pyinstaller
+## Building a Standalone Binary
+
+You can package the CLI into a single executable with [PyInstaller](https://pyinstaller.org/):
+
+```bash
+pyinstaller --clean --collect-all besapi --onefile .\src\bescli\bescli.py
+```
+
+Note: using UPX to compress the binary only saves about 2MB out of 16MB on Windows.
+
+## BigFix REST API Documentation
 
-- `pyinstaller --clean --collect-all besapi --onefile .\src\bescli\bescli.py`
-- Note: using UPX to compress the binary only saves 2MB out of 16MB on Windows
+- https://developer.bigfix.com/rest-api/
+- http://bigfix.me/restapi
 
-# Related Items
+## Related Items
 
 - https://forum.bigfix.com/t/rest-api-python-module/2170
 - https://gist.github.com/hansen-m/58667f370047af92f634
@@ -176,6 +208,10 @@ BigFix> get fixlets/operator/mah60
 - https://forum.bigfix.com/t/query-for-finding-who-deleted-tasks-fixlets/13668/6
 - https://forum.bigfix.com/t/rest-api-java-wrapper/12693
 
-# LICENSE
+## Contributing
+
+Issues and pull requests are welcome! If you have a script built on besapi that others might find useful, consider adding it to the [examples](https://github.com/jgstew/besapi/tree/master/examples).
+
+## License
 
-- MIT License
+[MIT License](LICENSE.txt)

besapi-4.2.0/README.md

@@ -0,0 +1,187 @@
+# besapi
+
+[![PyPI version](https://img.shields.io/pypi/v/besapi.svg)](https://pypi.org/project/besapi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.txt)
+
+**besapi** is a Python library that makes it easy to work with the [BigFix REST API](https://developer.bigfix.com/rest-api/api/). It handles authentication, requests, and XML parsing for you, so you can focus on automating your BigFix environment instead of wrangling raw HTTP and XML.
+
+It also includes **bescli**, an interactive command-line interface for exploring the REST API — great for trying things out before writing any code.
+
+## Installation
+
+```bash
+pip install besapi
+```
+
+## Quick Start
+
+Connect to your BigFix root server and start making requests:
+
+```python
+import besapi
+
+b = besapi.besapi.BESConnection(
+    "my_username", "my_password", "https://rootserver.domain.org:52311"
+)
+rr = b.get("sites")
+
+# Every request returns a RESTResult with several handy views of the response:
+#   rr.request - the original requests object
+#   rr.text    - the raw text returned by the server
+#   rr.besxml  - the response as an XML string
+#   rr.besobj  - the response as an lxml.objectify.ObjectifiedElement
+
+print(rr)
+```
+
+```xml
+<BESAPI xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="BESAPI.xsd">
+<ExternalSite Resource="http://rootserver.domain.org:52311/api/site/external/BES%20Support">
+<Name>BES Support</Name>
+</ExternalSite>
+<!---...--->
+<CustomSite Resource="http://rootserver.domain.org:52311/api/site/custom/Org">
+<Name>Org</Name>
+</CustomSite>
+<CustomSite Resource="http://rootserver.domain.org:52311/api/site/custom/Org%2fMac">
+<Name>Org/Mac</Name>
+</CustomSite>
+<CustomSite Resource="http://rootserver.domain.org:52311/api/site/custom/Org%2fWindows">
+<Name>Org/Windows</Name>
+</CustomSite>
+<CustomSite Resource="http://rootserver.domain.org:52311/api/site/custom/ContentDev">
+<Name>ContentDev</Name>
+</CustomSite>
+<OperatorSite Resource="http://rootserver.domain.org:52311/api/site/operator/mah60">
+<Name>mah60</Name>
+</OperatorSite>
+<ActionSite Resource="http://rootserver.domain.org:52311/api/site/master">
+<Name>ActionSite</Name>
+</ActionSite>
+</BESAPI>
+```
+
+### Working with results
+
+The `besobj` attribute lets you navigate the XML response like a regular Python object:
+
+```pycon
+>>> rr.besobj.attrib
+{'{http://www.w3.org/2001/XMLSchema-instance}noNamespaceSchemaLocation': 'BESAPI.xsd'}
+
+>>> rr.besobj.ActionSite.attrib
+{'Resource': 'http://rootserver.domain.org:52311/api/site/master'}
+
+>>> rr.besobj.ActionSite.attrib["Resource"]
+'http://rootserver.domain.org:52311/api/site/master'
+
+>>> rr.besobj.ActionSite.Name
+'ActionSite'
+
+>>> rr.besobj.OperatorSite.Name
+'mah60'
+
+>>> for cSite in rr.besobj.CustomSite:
+...     print(cSite.Name)
+...
+Org
+Org/Mac
+Org/Windows
+ContentDev
+```
+
+### Downloading, uploading, and deleting content
+
+```python
+# save a task to a file:
+rr = b.get("task/operator/mah60/823975")
+with open("/Users/Shared/Test.bes", "wb") as bes_file:
+    bes_file.write(rr.text.encode("utf-8"))
+
+# delete a task:
+b.delete("task/operator/mah60/823975")
+
+# create or update a task from a file:
+with open("/Users/Shared/Test.bes") as bes_file:
+    b.post("tasks/operator/mah60", bes_file)
+    b.put("task/operator/mah60/823975", bes_file)
+```
+
+Looking for more? The [examples folder](https://github.com/jgstew/besapi/tree/master/examples) has ready-to-run scripts for many common tasks — exporting sites, importing content, taking actions, running session relevance, and more.
+
+## Command-Line Interface
+
+The included `bescli` interactive shell is the fastest way to poke around the REST API:
+
+```
+$ python -m bescli
+
+BigFix> login
+User [mah60]: mah60
+Root Server (ex. https://server.institution.edu:52311): https://my.company.org:52311
+Password:
+Login Successful!
+BigFix> get help
+...
+BigFix> get sites
+...
+BigFix> get sites.OperatorSite.Name
+mah60
+BigFix> get help/fixlets
+GET:
+/api/fixlets/{site}
+POST:
+/api/fixlets/{site}
+BigFix> get fixlets/operator/mah60
+...
+```
+
+## Requirements
+
+- Python 3.9 or later
+  - besapi 1.1.3 was the last version with partial Python 2 support
+- [lxml](https://pypi.org/project/lxml/)
+- [requests](https://pypi.org/project/requests/)
+- [cmd2](https://pypi.org/project/cmd2/) (for the CLI)
+
+All dependencies are installed automatically by pip.
+
+## More Examples Using besapi
+
+- https://github.com/jgstew/besapi/tree/master/examples
+- https://github.com/jgstew/generate_bes_from_template/blob/master/examples/generate_uninstallers.py
+- https://github.com/jgstew/jgstew-recipes/blob/main/SharedProcessors/BESImport.py
+- https://github.com/jgstew/jgstew-recipes/blob/main/SharedProcessors/BigFixActioner.py
+- https://github.com/jgstew/jgstew-recipes/blob/main/SharedProcessors/BigFixSessionRelevance.py
+
+## Building a Standalone Binary
+
+You can package the CLI into a single executable with [PyInstaller](https://pyinstaller.org/):
+
+```bash
+pyinstaller --clean --collect-all besapi --onefile .\src\bescli\bescli.py
+```
+
+Note: using UPX to compress the binary only saves about 2MB out of 16MB on Windows.
+
+## BigFix REST API Documentation
+
+- https://developer.bigfix.com/rest-api/
+- http://bigfix.me/restapi
+
+## Related Items
+
+- https://forum.bigfix.com/t/rest-api-python-module/2170
+- https://gist.github.com/hansen-m/58667f370047af92f634
+- https://docs.google.com/presentation/d/1pME28wdjkzj9378py9QjFyMOyOHcamB6bk4k8z-c-r0/edit#slide=id.g69e753e75_039
+- https://forum.bigfix.com/t/bigfix-documentation-resources/12540
+- https://forum.bigfix.com/t/query-for-finding-who-deleted-tasks-fixlets/13668/6
+- https://forum.bigfix.com/t/rest-api-java-wrapper/12693
+
+## Contributing
+
+Issues and pull requests are welcome! If you have a script built on besapi that others might find useful, consider adding it to the [examples](https://github.com/jgstew/besapi/tree/master/examples).
+
+## License
+
+[MIT License](LICENSE.txt)

{besapi-4.1.4 → besapi-4.2.0}/src/besapi/besapi.py

@@ -29,7 +29,7 @@ import lxml.objectify
 import requests
 import urllib3.poolmanager
 
-__version__ = "4.1.4"
+__version__ = "4.2.0"
 
 besapi_logger = logging.getLogger("besapi")
 
@@ -249,6 +249,21 @@ def validate_xml_bes_file(file_path):
     return validate_xsd(file_data)
 
 
+def xml_elem_strip_namespace(elem):
+    """Strip namespace."""
+    clean_elem = lxml.etree.Element(elem.tag, attrib=elem.attrib)
+
+    # Move the inner text and children over to the fresh element
+    clean_elem.text = elem.text
+
+    for child in elem:
+        # Create a true, independent copy of the child element
+        child_copy = xml_elem_strip_namespace(child)
+        clean_elem.append(child_copy)
+
+    return clean_elem
+
+
 def action_xml_from_bes_file(file_path, targets="<AllComputers>"):
     """Create action XML from bes file with fixlet or task or singleaction."""
     # default to empty string:
@@ -318,6 +333,21 @@ def action_xml_from_bes_file(file_path, targets="<AllComputers>"):
 
     logging.debug("Relevance Combined: %s", relevance_clauses_combined)
 
+    # get settings if found
+    settings_xml_string = ""
+    try:
+        if bes_type != "SingleAction":
+            settings_xml = tree.xpath(f"//BES/{bes_type}/DefaultAction/Settings")[0]
+        else:
+            settings_xml = tree.xpath(f"//BES/{bes_type}/Settings")[0]
+
+        # get_settings_xml = xml_elem_strip_namespace(get_settings_xml)
+        settings_xml_string = lxml.etree.tostring(
+            settings_xml, encoding="utf-8"
+        ).decode("utf-8")
+    except IndexError:
+        pass
+
     action_xml = f"""<?xml version="1.0" encoding="UTF-8"?>
 <BES xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="BES.xsd">
 	<SingleAction>
@@ -326,7 +356,7 @@ def action_xml_from_bes_file(file_path, targets="<AllComputers>"):
 		<ActionScript MIMEType="application/x-Fixlet-Windows-Shell"><![CDATA[// Start:
 {actionscript}
 // End]]></ActionScript>
-		<SuccessCriteria Option="{success_criteria}">{custom_relevance_xml}</SuccessCriteria>
+		<SuccessCriteria Option="{success_criteria}">{custom_relevance_xml}</SuccessCriteria>{settings_xml_string}
 		<Target>
             {get_target_xml(targets)}
         </Target>

{besapi-4.1.4 → besapi-4.2.0}/src/besapi/plugin_utilities.py

@@ -14,8 +14,24 @@ from typing import Union
 
 import besapi
 
-if os.name == "nt":
-    import besapi.plugin_utilities_win
+# the platform specific root server utilities module, or None if unavailable.
+# NOTE: these are conveniences for plugins running on a root server,
+# so a failure to import must never prevent the other connection methods:
+PLATFORM_UTILITIES = None
+
+try:
+    if os.name == "nt":
+        import besapi.plugin_utilities_win
+
+        PLATFORM_UTILITIES = besapi.plugin_utilities_win
+    # NOTE: linux only, not all posix. macOS is never a root server,
+    # so none of these files will be in place there:
+    elif sys.platform.startswith("linux"):
+        import besapi.plugin_utilities_linux
+
+        PLATFORM_UTILITIES = besapi.plugin_utilities_linux
+except BaseException as import_error:  # pylint: disable=broad-exception-caught
+    logging.debug("platform specific plugin utilities unavailable: %s", import_error)
 
 
 # NOTE: This does not work as expected when run from plugin_utilities
@@ -157,6 +173,64 @@ def get_besapi_connection_env_then_config():
     return bes_conn
 
 
+def _try_platform_utility(function_name: str):
+    """Call a function from the platform specific utilities module, if possible.
+
+    These are best effort conveniences for the case where the plugin happens to
+    be running on a root server. If anything at all goes wrong, this is simply
+    not a usable root server, so the caller falls back to the other methods.
+
+    Args:
+        function_name: The name of the function to call, with no arguments.
+
+    Returns:
+        Whatever the function returned, or None if it could not be used.
+    """
+    if not PLATFORM_UTILITIES:
+        logging.debug("no platform specific plugin utilities available.")
+        return None
+
+    platform_function = getattr(PLATFORM_UTILITIES, function_name, None)
+
+    if not platform_function:
+        logging.debug(
+            "`%s` not found in %s", function_name, PLATFORM_UTILITIES.__name__
+        )
+        return None
+
+    try:
+        return platform_function()
+    except BaseException as err:  # pylint: disable=broad-exception-caught
+        # NOTE: intentionally broad, this must never prevent the other methods:
+        logging.debug("`%s` failed, ignoring: %s", function_name, err)
+        return None
+
+
+def get_root_server_rest_pass() -> Union[str, None]:
+    """Get the REST API password from the local root server, if this is one.
+
+    On Windows this reads the registry, otherwise it reads the
+    MasterOperatorCredentials file. Returns None if this is not a root server,
+    or if the attempt failed for any reason.
+    """
+    if os.name == "nt":
+        return _try_platform_utility("get_win_registry_rest_pass")
+
+    return _try_platform_utility("get_linux_credentials_rest_pass")
+
+
+def get_besconn_root_server() -> Union[besapi.besapi.BESConnection, None]:
+    """Get a connection using local root server credentials, if this is one.
+
+    Returns None if this is not a root server, or if the attempt failed for
+    any reason.
+    """
+    if os.name == "nt":
+        return _try_platform_utility("get_besconn_root_windows_registry")
+
+    return _try_platform_utility("get_besconn_root_linux")
+
+
 def get_besapi_connection_args(
     args: argparse.Namespace,
 ) -> Union[besapi.besapi.BESConnection, None]:
@@ -169,10 +243,9 @@ def get_besapi_connection_args(
 
     # if user was provided as arg but password was not:
     if args.user and not password:
-        if os.name == "nt":
-            # attempt to get password from windows root server registry:
-            # this is specifically for the case where user is provided for a plugin
-            password = besapi.plugin_utilities_win.get_win_registry_rest_pass()
+        # attempt to get password from the local root server:
+        # this is specifically for the case where user is provided for a plugin
+        password = get_root_server_rest_pass()
 
     # if user was provided as arg but password was not:
     if args.user and not password:
@@ -242,6 +315,8 @@ def get_besapi_connection(
     """Get connection to besapi.
 
     If on Windows, will attempt to get connection from Windows Registry first.
+    If not on Windows, will attempt to get connection from the root server
+    MasterOperatorCredentials file first.
     If args provided, will attempt to get connection using provided args.
     If no args provided, will attempt to get connection from env vars.
     If no env vars, will attempt to get connection from config file.
@@ -251,11 +326,11 @@ def get_besapi_connection(
     Returns:
         A BESConnection object if successful, otherwise None.
     """
-    # if windows, try to get connection from windows registry:
-    if os.name == "nt":
-        bes_conn = besapi.plugin_utilities_win.get_besconn_root_windows_registry()
-        if bes_conn:
-            return bes_conn
+    # if this is a root server, try its local credentials first:
+    # (windows registry, or the linux MasterOperatorCredentials file)
+    bes_conn = get_besconn_root_server()
+    if bes_conn:
+        return bes_conn
 
     # if no args provided, try to get connection from env then config file:
     if not args: