Release v3.0.7 (#63)

* resolves the bug in issue #25 by removing id_override, replacing data with params, and adding specific input parameters. * required changes to resolve the bug in issue #25. migrated from updating the url in _get_data to a local _params variable that is updated with the input params var. * added Unreleased section and updated with issue #25 changes. * Fix calls that return a single item. * Return single items without wrapping in list. * added params= to be explicit, and marked a potential bug. * updated CHANGELOG * added docstring * updated CHANGELOG * Resolves Issue 38 (#1) * Resolves issue #38 * Resolves issue #24 - Updated update_device input to accept both name and device_name input (breaking change) - Data is now updated with the inputs - Added validation that data has input - Updated the README with update_device's new inputs * Adding download option to profile * Update CHANGELOG.md * v3.0.7 * adding _get_xml connection * update CHANGELOG * update README * Adding include_awaiting_enrollment option #43 (#44) * Merging dev branch (#46) * Use request params instead of url string in SimpleMDM._get_data() * Fix Devices.delete_device() * Add methods for enabling/disabling remote desktop * Add /devices request rate limiting * Add profile and user listing * Add retry on 5xx errors to GET requests * Updates gitignore and changelog (#47) - Added ignoring egg files - Updated changelog * A little clean up, some fixen, and a few tests. (#48) - Cleaned up my bad merge on Devices.get_device() and adds some help docs - Closes the session on deinit that the Connection class now opens - Resolves issue #45 by preserving input parameters instead of overwriting them - Added setup.cfg and pyproject.toml files for packaging new releases - Added a few basic tests - Updates the changelog and gitignore files * Add script support * Add error handling for update_script * Fix handling of req_params for pagination * Update CHANGELOG.md * Fix handling of req_params for pagination * Update CHANGELOG.md * Add Sample Projects Adding some samples projects for issue #28 * Use monotonic time for rate limit and fix sleep time calc * Update CHANGELOG.md Co-authored-by: Steve <steve.kueng@gmail.com> Co-authored-by: Bryan Heinz <git@bryanheinz.com> Co-authored-by: Jon Crain <joncrain@users.noreply.github.com>
macadmins · Dec 2, 2022 · 2e26fbf · 2e26fbf
1 parent 2bcc71a
commit 2e26fbf
Show file tree

Hide file tree

Showing 17 changed files with 481 additions and 43 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,6 @@
 *.pyc
+*.egg*
 .DS_Store
+settings.py
 
-.vscode
+.vscode
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,42 @@
 # CHANGELOG
 
-## v3.0.6
+## [Unreleased]
+
+### Added
+- setup.cfg - Python package setup file ([#29](https://github.com/macadmins/simpleMDMpy/issues/29)) - TY [@bryanheinz](https://github.com/bryanheinz)
+- pyproject.toml - Python package meta setup file ([#29](https://github.com/macadmins/simpleMDMpy/issues/29)) - TY [@bryanheinz](https://github.com/bryanheinz)
+- tests - Added a few basic tests and including a readme on how to setup testing - TY [@bryanheinz](https://github.com/bryanheinz)
+
+### Changes
+
+- Added ability to update the actual device name via SimpleMDM ([#24](https://github.com/macadmins/simpleMDMpy/issues/24), [#38](https://github.com/macadmins/simpleMDMpy/issues/38)) - TY [@bryanheinz](https://github.com/bryanheinz)
+- Replaced get_logs() `id_override` input parameter with `starting_after` and `limit` ([#25](https://github.com/macadmins/simpleMDMpy/issues/25)) - TY [@bryanheinz](https://github.com/bryanheinz)
+- Fixes calls that return a single item ([#26](https://github.com/macadmins/simpleMDMpy/issues/26)) - TY [@MagerValp](https://github.com/MagerValp)
+- Add method to download profiles ([#40](https://github.com/macadmins/simpleMDMpy/issues/40)) - TY [@joncrain](https://github.com/joncrain)
+- Adds option for get_devices to include_awaiting_enrollment ([#43](https://github.com/macadmins/simpleMDMpy/issues/43)) - TY [@joncrain](https://github.com/joncrain)
+- Fixes `Devices.delete_device()` - TY [@MagerValp](https://github.com/MagerValp)
+- Add Devices methods for enabling/disabling remote desktop, and profile and user listing ([@MagerValp](https://github.com/MagerValp))
+- Add /devices request rate limiting to `_get_data` - TY [@MagerValp](https://github.com/MagerValp)
+- Add retry on 5xx errors to GET requests to `_get_data` - TY [@MagerValp](https://github.com/MagerValp)
+- Fixes `_get_data` so that it properly preserves all input parameters ([#45](https://github.com/macadmins/simpleMDMpy/issues/45)) - TY [@bryanheinz](https://github.com/bryanheinz)
+- Adds help docs to Devices.get_device() - TY [@bryanheinz](https://github.com/bryanheinz)
+- Add Scripts and ScriptJobs - TY [@MagerValp](https://github.com/MagerValp)
+- Fix pagination - TY [@jcfrt](https://github.com/jcfrt)
+- Fix rate limiting - TY [@MagerValp](https://github.com/MagerValp)
+
+### Issues
+
+- Closes issue #24
+- Closes issue #38
+- Closes issue #25
+- Closes issue #26
+- Closes issue #40
+- Closes issue #43
+- Closes issue #29
+- Closes issue #45
+- Closes issue #57
+
+## [v3.0.6]
 
 ### PRs Included
 
@@ -12,7 +48,7 @@
 
 - Add method to get all custom attributes for a device
 
-## v3.0.5
+## [v3.0.5]
 
 ### Issues
 
@@ -22,7 +58,7 @@
 
 - CODEOWNERS
 
-## v3.0.4
+## [v3.0.4]
 
 ### Issues
 
@@ -39,7 +75,7 @@
 - Merged with @MagerValp / simpleMDMpy @ [508540928](https://github.com/MagerValp/simpleMDMpy/commit/50854094bee2ac5306eded7c5614d76f3eab4c25)
 - minor tweaks on the readme
 
-## v3.0.3
+## [v3.0.3]
 
 ### Issues
 
@@ -57,7 +93,7 @@
 - default branch is now `main`
 - remove `data` payload from Devices.delete_device
 
-## v3.0.2
+## [v3.0.2]
 
 ### Issues
 
@@ -73,7 +109,7 @@
 
 - Changed paginaition to work without compounding to a `414`
 
-## v3.0.1
+## [v3.0.1]
 
 ### Issues
 
@@ -84,7 +120,7 @@
 - Changed paginaition to work, now returns obj not response
 - good catch @bryanheinz
 
-## v3.0.0
+## [v3.0.0]
 
 - Closes #3
 
@@ -93,7 +129,7 @@
 - removed forced encoding for `GET` responses
 - added some pylint comments
 
-## v2.1.0
+## [v2.1.0]
 
 ### Issues
 
@@ -103,7 +139,7 @@
 
 - fixed module names
 
-## v2.0.0
+## [v2.0.0]
 
 ### Issues
 

diff --git a/README.md b/README.md
@@ -14,6 +14,11 @@ Your SimpleMDM API key will need to be set as an environmental variable `api_key
 
 Help available via `help(SimpleMDMpy)`
 
+## Sample Projects
+
+* [Making SimpleMDM Complicated](https://github.com/lucasjhall/CONF-2021_MDO_YVR-Making_SimpleMDM_Complicated)
+* [SimpleCLI](https://github.com/MagerValp/SimpleCLI)
+
 ## Available Modules
 
 ### Account
@@ -179,7 +184,6 @@ class CustomAttributes(SimpleMDMpy.SimpleMDM.Connection)
 <!-- TODO: Custom Configuration -->
 
 ### Custom Configuration Profiles
-<!-- TODO: DOWNLOAD PROFILE -->
 ```python
 class CustomConfigurationProfiles(SimpleMDMpy.SimpleMDM.Connection)
  |  work with custom profiles
@@ -197,6 +201,9 @@ class CustomConfigurationProfiles(SimpleMDMpy.SimpleMDM.Connection)
  |  delete_profile(self, profile_id)
  |      deletes custom profile
  |
+ |  download_profile(self, profile_id)
+ |      downloads custom profile
+ |
  |  get_profiles(self)
  |      returns profiles
  |
@@ -258,9 +265,10 @@ class Devices(SimpleMDMpy.SimpleMDM.Connection)
  |  get_custom_attribute(self, device_id, custom_attribute_name)
  |      get a devices custom attributes
  |
- |  get_device(self, device_id='all', search=None)
+ |  get_device(self, device_id='all', search=None, include_awaiting_enrollment=False)
  |      Returns a device specified by id. If no ID or search is
- |      specified all devices will be returned
+ |      specified all devices will be returned. Default does not include devices
+ |      waiting for enrollment
  |
  |  list_installed_apps(self, device_id)
  |      Returns a listing of the apps installed on a device.
@@ -288,7 +296,7 @@ class Devices(SimpleMDMpy.SimpleMDM.Connection)
  |  shutdown_device(self, device_id)
  |      This command sends a shutdown command to the device.
  |
- |  update_device(self, name, device_id)
+ |  update_device(self, device_id, name=None, device_name=None)
  |      Update the SimpleMDM name or device name of a device object.
  |
  |  update_os(self, device_id)
@@ -374,7 +382,7 @@ class Logs(SimpleMDMpy.SimpleMDM.Connection)
  |
  |  __init__(self, api_key)
  |
- |  get_logs(self)
+ |  get_logs(self, starting_after=None, limit=None)
  |      And I mean all the LOGS, before pagination
  |
 

diff --git a/SimpleMDMpy/CustomConfigurationProfiles.py b/SimpleMDMpy/CustomConfigurationProfiles.py
@@ -49,6 +49,11 @@ def delete_profile(self, profile_id):
         url = self.url + "/" + profile_id
         return self._delete_data(url)
 
+    def download_profile(self, profile_id):
+        """downloads custom profile"""
+        url = self.url + "/" + profile_id + "/download/"
+        return self._get_xml(url)
+
     def assign_to_device_group(self, profile_id, device_group_id):
         """assigns custom profile to group"""
         url = self.url + "/" + profile_id + "/device_groups/" + device_group_id

diff --git a/SimpleMDMpy/Devices.py b/SimpleMDMpy/Devices.py
@@ -11,16 +11,32 @@ def __init__(self, api_key):
         SimpleMDMpy.SimpleMDM.Connection.__init__(self, api_key)
         self.url = self._url("/devices")
 
-    def get_device(self, device_id="all", search=None):
-        """Returns a device specified by id. If no ID or search is
-        specified all devices will be returned"""
+    def get_device(self, device_id="all", search=None, include_awaiting_enrollment=False):
+        """
+        Returns a device specified by id. If no ID or search is specified all
+        devices will be returned.
+        
+        Args:
+            device_id (str, optional):  Returns a dictionary of the specified
+                device id. By default, it returns a list of all devices. If a
+                device_id and search is specified, then search will be ignored.
+            search (str, optional): Returns a list of devices that match the
+                search criteria. Defaults to None. Ignored if device_id is set.
+            include_awaiting_enrollment (bool, optional): Returns a list of all
+                devices including devices in the "awaiting_enrollment" state.
+        
+        Returns:
+            dict: A single dictionary object with device information.
+            array: An array of dictionary objects with device information.
+        """
         url = self.url
-        data = None
-        if search:
-            data = {'search': search}
-        elif device_id != 'all':
+        params = {'include_awaiting_enrollment': include_awaiting_enrollment}
+        # if a device ID is specified, then ignore any searches
+        if device_id != 'all':
             url = url + "/" + str(device_id)
-        return self._get_data(url, data)
+        elif search:
+            params['search'] = search
+        return self._get_data(url, params)
 
     def create_device(self, name, group_id):
         """Creates a new device object in SimpleMDM. The response
@@ -29,23 +45,38 @@ def create_device(self, name, group_id):
         data = {'name': name, 'group_id': group_id}
         return self._post_data(self.url, data)
 
-    def update_device(self, name, device_id):
-        """Update the SimpleMDM name or device name of a device object."""
+    def update_device(self, device_id, name=None, device_name=None):
+        """Update the SimpleMDM name and/or device name of a device object."""
         url = self.url + "/" + str(device_id)
-        data = {'name': name}
+        data = {}
+        if name is not None:
+            data.update({'name':name})
+        if device_name is not None:
+            data.update({'device_name':device_name})
+        if data == {}:
+            raise Exception(f"Missing name and/or device_name variables.")
         return self._patch_data(url, data)
 
     def delete_device(self, device_id):
         """Unenroll a device and remove it from the account."""
         url = self.url + "/" + str(device_id)
-        data = {}
-        return self._delete_data(url, data) #pylint: disable=too-many-function-args
+        return self._delete_data(url) #pylint: disable=too-many-function-args
+
+    def list_profiles(self, device_id):
+        """Returns a listing of profiles that are directly assigned to the device."""
+        url = self.url + "/" + str(device_id) + "/profiles"
+        return self._get_data(url)
 
     def list_installed_apps(self, device_id):
         """Returns a listing of the apps installed on a device."""
         url = self.url + "/" + str(device_id) + "/installed_apps"
         return self._get_data(url)
 
+    def list_users(self, device_id):
+        """Returns a listing of the user accounts on a device."""
+        url = self.url + "/" + str(device_id) + "/users"
+        return self._get_data(url)
+
     def push_apps_device(self, device_id):
         """You can use this method to push all assigned apps
         to a device that are not already installed."""
@@ -102,6 +133,17 @@ def update_os(self, device_id):
         data = {}
         return self._post_data(url, data)
 
+    def enable_remote_desktop(self, device_id):
+        """You can use this method to enable remote desktop. Supported by macOS 10.14.4+ devices only."""
+        url = self.url + "/" + str(device_id) + "/remote_desktop"
+        data = {}
+        return self._post_data(url, data)
+
+    def disable_remote_desktop(self, device_id):
+        """You can use this method to disable remote desktop. Supported by macOS 10.14.4+ devices only."""
+        url = self.url + "/" + str(device_id) + "/remote_desktop"
+        return self._delete_data(url)
+
     def refresh_device(self, device_id):
         """Request a refresh of the device information and app inventory.
         SimpleMDM will update the inventory information when the device responds

diff --git a/SimpleMDMpy/Logs.py b/SimpleMDMpy/Logs.py
@@ -10,9 +10,24 @@ class Logs(SimpleMDMpy.SimpleMDM.Connection):
     def __init__(self, api_key):
         SimpleMDMpy.SimpleMDM.Connection.__init__(self, api_key)
         self.url = self._url("/logs")
-
-    def get_logs(self, id_override=0):
-        """And I mean all the LOGS"""
+
+    def get_logs(self, starting_after=None, limit=None):
+        """Returns logs, and I mean all the LOGS
+        
+        Args:
+            starting_after (str, optional):  set to the id of the log object you
+                want to start with. Defaults to the first object.
+            limit (str, optional): A limit on the number of objects that will be
+                returned per API call. Setting this will still return all logs.
+                Defaults to 100.
+        
+        Returns:
+            array: An array of dictionary log objects.
+        """
         url = self.url
-        data = {}
-        return self._get_data(url, data, id_override=id_override)
+        params = {}
+        if starting_after:
+            params['starting_after'] = starting_after
+        if limit:
+            params['limit'] = limit
+        return self._get_data(url, params=params)