Metadata-Version: 1.0
Name: pywinservicemanager
Version: 1.0.5
Summary: Windows Service Manager Module that wraps for the win32service api
Home-page: https://github.com/belvedere-trading/pywinservicemanager
Author: Team Belvedere, LLC
Author-email: opensource@belvederetrading.com
License: PyWinServiceManager - Wrapper for the win32service api

   Copyright 2015 Team Belvedere, LLC

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
Description: **************************
        python-pywinservicemanager
        **************************
        
        Python Windows Service Manager is a python package that helps to easily manage
        windows services, mirroring the functionality of the Windows Service
        Controller Utility (sc.exe). It allows to easily manage both Driver and Win32
        services. The following can be achieved using this package:
        
         * Create, Remove, or Update a service configuration
         * Query a specific or all Service Statuses
         * Get a service configuration
         * Verify a service exists
         * Start, Stop, Pause, Continue, Interrogate a service
        
        ==============
        Pre-requisites
        ==============
            pypiwin32>=219
        
        ============
        Installation
        ============
         * Clone this repository
         * Put the repo dir in your PYTHONPATH
         * Run:
        
        .. code:: python
        
            python setup.py install
        
        =====================
        How to Run Unit Tests
        =====================
        1.  pip install nose, mock
        2.  From the module's root directory, run 'nosetests .'
        
        ======================
        How to Run the Example
        ======================
        1.  Download the package
        2.  From the module's root directory, run 'python example.py'
        
          * **Note**: Due to the way Windows Services work, you need to
            have the powershell scipt, testService.ps1, in the same
            directory as the example.py
        
        =====
        Usage
        =====
        This module attempts to follow the ORM design Pattern, where the Class
        WindowsServiceConfigurationManager would be your context, and object that
        represents the data store is a ServiceEntity.
        
        WindowsServiceConfigurationManager
        ----------------------------------
        This is the entry point for all operations. This module has static methods that:
        - Creates or Gets a Service, and returns a Entity object that represents that service
        - Query All Service Statuses
        - Verify a service exists
        - Gets a specific service's status
        
        The following Describes these operations in detail:
        
          **Create a New Service:**
        
            The CreateService() function takes a parameter of Type NewServiceDefinition. The following describes the NewServiceDefinition constructor and its arguments:
        
            **NewServiceDefinition:**
        
            1.  **serviceName *(Required)***: The name of the service.
                  Valid Values: Any non empty string
            2.  **displayName *(Required)***: Indicates the friendly name that identifies the service to the user
                  Valid Values: Any non empty string
            3.  **binaryPathName *(Required)***: Specifies the path to the executable file for the service.
                  Validate Values: Any non empty string that points to an executable
            4.  **startType**: Indicates how and when the service is started
                  Valid String Values: AUTO_START, DEMAND_START, BOOT_START, DISABLED, SYSTEM_START, INTERACTIVE_SHARE_PROCESS,  INTERACTIVE_OWN_PROCESS
                  Default Value:  DEMAND_START
            5.  **serviceType**: Represents the type of the service
                  Valid String Values: WIN32_SHARE_PROCESS, WIN32_OWN_PROCESS, KERNEL_DRIVER, FILE_SYSTEM_DRIVER
                  Default Value:  WIN32_OWN_PROCESS
            6.  **errorControl**: Specifies how to proceed if the driver for the service or device fails to load or initialize properly
                  Valid String Values: ERROR_CRITICAL, ERROR_IGNORE, ERROR_NORMAL, ERROR_SEVERE
                  Default Value:  ERROR_NORMAL
            7.  **loadOrderGroup**: The name of the load ordering group of which this service is a member
                  Valid Value: String of Group Name
                  Default Value: None
            8.  **dependencies**:
                  Valid Value: Array of Existing Service Names
                  Default Value: None
            9.  **serviceStartName**: Name of the account in which the service runs
                  Valid Value: A valid user account as a string
                  Default Value: The System Account
            10.  **description**: The description of the service
                  Valid Value: Any string
                  Default Value: An empty string
            11.  **failureActions**: Represents the action the service controller should take on each failure of a service
                  Valid Value: FailureActionConfigurationType
                  Default Value: None
        
                  ***See 'Complex Example for Creating Service' for an example, or the Section that describes the 'FailureActionConfigurationType'**
            12.  **failureFlag**: Specifies whether recovery actions will be triggered when a service stops as the result of an error
                  Valid Value: Boolean
                  Default Value: False
            13. **preShutdownInfo**: The time-out value, in milliseconds.
                  Valid Value: long or int
                  Default Value: 180,000 milliseconds
            14. **serviceSIDInfo**: Represents a service security identifier
                  Valid String Value: SID_TYPE_NONE, SID_TYPE_RESTRICTED, SID_TYPE_UNRESTRICTED
                  Default Value: SID_TYPE_UNRESTRICTED
            15. **delayedAutoStartInfo**: The value that indicates whether the service should be delayed from starting until other automatically started services are running.
                  Valid Value: Boolean
                  Default Value: False
        
        
        .. code:: python
        
            #Most simplistic example of creating a service
        
            from pywinservicemanager.WindowsServiceConfigurationManager import CreateService
            from pywinservicemanager.NewServiceDefinition import NewServiceDefinition
        
            serviceName = 'TestService'
            displayName = 'MyTestService'
            binaryPathName = 'c:\\myBinary.exe'
        
            newServiceDefinition = NewServiceDefinition(serviceName=serviceName,
                                                        displayName=displayName,
                                                        binaryPathName=binaryPathName)
        
            myService = CreateService(newServiceDefinition)
        
            # Note that the Create Service Method just creates the entity in memeory.
            # To save it to the 'DataStore', you must call Save()
            myService.Save()
        
            #Most complex example of creating a service
        
        .. code:: python
        
            from pywinservicemanager.WindowsServiceConfigurationManager import CreateService
            from pywinservicemanager.NewServiceDefinition import NewServiceDefinition
            import pywinservicemanager.ConfigurationTypes as ConfigurationTypes
        
            serviceName = 'TestService'
            displayName = 'MyTestService'
            binaryPathName = 'c:\\myBinary.exe'
            startType = 'DEMAND_START'
            serviceType= 'WIN32_OWN_PROCESS'
            errorControl= 'ERROR_IGNORE'
            loadOrderGroup = None
            dependencies= ['nsi']
            description= 'This is a test Service'
            failureFlag = False
            preShutdownInfo= 18000
            serviceSIDInfo = 'SID_TYPE_UNRESTRICTED'
            userName = None
            password = None
            delayedAutoStartInfo = False
        
            failureActionList = []
            delay = 1000
            failureActionList.append(ConfigurationTypes.FailureActionTypeFactory.CreateRestartAction(delay))
            failureActionList.append(ConfigurationTypes.FailureActionTypeFactory.CreateRunCommandAction(delay))
            resetPeriod = 1
            rebootMsg = 'MyRebootMessage'
            commandLine = 'MyCommandLine'
            failureActions = FailureActionConfigurationType(failureActionList, resetPeriod, rebootMsg, commandLine)
        
            newServiceDefinition = NewServiceDefinition(serviceName=serviceName,
                                                        displayName=displayName,
                                                        binaryPathName=binaryPathName,
                                                        startType=startType,
                                                        serviceType=serviceType,
                                                        errorControl=errorControl,
                                                        loadOrderGroup=loadOrderGroup,
                                                        dependencies=dependencies,
                                                        serviceStartName=userName,
                                                        description=description,
                                                        failureActions=failureActions,
                                                        failureFlag=failureFlag,
                                                        preShutdownInfo=preShutdownInfo,
                                                        serviceSIDInfo=serviceSIDInfo,
                                                        delayedAutoStartInfo=delayedAutoStartInfo)
        
            myService = CreateService(newServiceDefinition)
        
            # Note that the Create Service Method just creates the entity in memeory.
            # To save it to the 'DataStore', you must call Save()
            myService.Save(password)
        
        
        * **Delete a Service:**
        
        .. code:: python
        
            from pywinservicemanager.WindowsServiceConfigurationManager import GetService
            serviceName = "TestService"
            myService = GetService(serviceName)
        
            # Note that the GetService Method reads for the data store and creates the entity in memeory.
            # To delete it from the 'DataStore', you must call Delete()
            myService.Delete()
        
        
        * **Query All Services Statuses**:
          Returns a list of each installed service's status. (Please see status definition below for more details)
        
        .. code:: python
        
            from pywinservicemanager.WindowsServiceConfigurationManager import QueryAllServicesStatus
        
            statuses = QueryAllServicesStatus()
            print statuses
        
        * **Service Exists**:
        
        .. code:: python
        
            from pywinservicemanager.WindowsServiceConfigurationManager import ServiceExists
        
            serviceName = 'TestService'
            serviceExists = ServiceExists(serviceName)
            print serviceExists
        
        
        
        * **Get Service Status**:
          Returns a single service's status (Please see status definition below for more details)
        
        .. code:: python
        
            from pywinservicemanager.WindowsServiceConfigurationManager import GetServiceStatus
            serviceName = 'TestService'
            serviceStatus = GetServiceStatus(serviceName)
            print serviceStatus
        
        ServiceEntity
        -------------
        This is the object that maps to the service.
        
        The object contains the following commands for each service:
          * Save
          * Delete
          * Start
          * Stop
          * Pause
          * Continue
          * Interrogate
          * GetServiceStatus
          * UpdateConfiguration
          * Exists
        
        You need to make sure that the commands Pause, Continue, and Interrogate are
        able to be excepted by the service. The accepted commands are dependent on 2
        things. First, if the service is configurated to accept such commands, and
        second, if the current state of the service allows that command to be called on
        the service. The code examples below shows how to deal with this. Furthermore,
        if a service is not in a "Running" state, than Stop cannot be called.
        Vis-a-versa, if a service is not in a "Stopped" state, then Start cannot be
        called.
        
        * **UpdateConfiguration**: Used to update a service's configuration in memeory.
          You must call the save method to persist the service.
        
        .. code:: python
        
            from pywinservicemanager.WindowsServiceConfigurationManager import GetService
        
            serviceName = 'TestService'
            myService = GetService(serviceName)
            myService.UpdateConfiguration('StartType', 'DEMAND_START')
            myService.Save()
        
        
        * **Save**: Saves the current state of the ServiceEntity as a service in the OS.
          You can pass a password as an argument to this function if one is needed, the
          default value is 'None'
        
        .. code:: python
        
            from pywinservicemanager.WindowsServiceConfigurationManager import GetService
        
            serviceName = 'TestService'
            myService = GetService(serviceName)
            myService.UpdateConfiguration('ServiceStartName', 'MyDomain\\MyNewUser')
            myService.Save('MyNewPassword')
        
        
        * **Delete**: Deletes the Service
          Deletes a service. Please note that you if your service is running, you will
          need to stop the service for it to be deleted. Also, if anything has a handle
          open to the service, those need to be closed as well. If Delete() is called
          on service in which a handle is open, then it will be 'Marked for Deletion'
          and will not be deleted until all handles are closed.
        
        .. code:: python
        
           from pywinservicemanager.WindowsServiceConfigurationManager import GetService
        
           serviceName = 'TestService'
           myService = GetService(serviceName)
           myService.Delete()
        
        
        * **Start**: Deletes the Service
          Starts a given service that has is stopped. If the service is running, the
          function will just return. Also, if the service does not return from the Start
          command within 30 seconds, a TimeoutException is thrown
        
        .. code:: python
        
           from pywinservicemanager.WindowsServiceConfigurationManager import GetService
        
           serviceName = 'TestService'
           myService = WindowsServiceConfigurationManager.GetService(serviceName)
           myService.Start()
        
        
        * **Stop**: Stops the Service
          Stops a given service that is started. If the service is stopped, the function
          will just return. Also, if the service does not return from the Stop
          command within 30 seconds, a TimeoutException is thrown
        
        .. code:: python
        
           from pywinservicemanager.WindowsServiceConfigurationManager import GetService
        
           serviceName = 'TestService'
           myService = WindowsServiceConfigurationManager.GetService(serviceName)
           myService.Stop()
        
        * **Restart**: Restart the Service
          Restarts a given service that is started. If the service is stopped, this is
          equivelent to just calling start. If the service is running, then service will
          be stopped and then started. Also, if the service does not return from the
          Stop or Start command within 30 seconds, a TimeoutException is thrown
        
        .. code:: python
        
           from pywinservicemanager.WindowsServiceConfigurationManager import GetService
        
           serviceName = 'TestService'
           myService = WindowsServiceConfigurationManager.GetService(serviceName)
           myService.Restart()
        
        * **Continue**: Continues the Service after it was paused
          Stops a given service that is Paused and/or has the value
          ACCEPT_PAUSE_CONTINUE in ControlsAccepted. If not, an exception will be
          thrown. Also, if the service does not return from the Continue command
          within 30 seconds, a TimeoutException is thrown
        
        .. code:: python
        
            from pywinservicemanager.WindowsServiceConfigurationManager import GetService
        
            serviceName = 'TestService'
            myService = GetService(serviceName)
            status = myService.GetServiceStatus()
            if 'ACCEPT_PAUSE_CONTINUE' in status['ControlsAccepted']:
                myService.Continue()
        
        
        * **Pause**: Pauses the Service
          Pauses a given service that is Paused and/or has the value
          ACCEPT_PAUSE_CONTINUE in ControlsAccepted. If not, an exception will be
          thrown. Also, if the service does not return from the Pause command within
          30 seconds, a TimeoutException is thrown
        
        .. code:: python
        
            from pywinservicemanager.WindowsServiceConfigurationManager import GetService
        
            serviceName = 'TestService'
            myService = GetService(serviceName)
            myServiceStatus = myService.GetServiceStatus().Status
            if 'ACCEPT_PAUSE_CONTINUE' in status['ControlsAccepted']:
                myService.Pause()
        
        
        * **Interrogate**: Interrogates the Service
        
        .. code:: python
        
            from pywinservicemanager.WindowsServiceConfigurationManager import GetService
        
            serviceName = 'TestService'
            myService = GetService(serviceName)
            myService.Interrogate()
        
        
        * **GetServiceStatus**: Deletes the Service
          Returns a the service's status
          (Please see status definition below for more details)
        
        .. code:: python
        
           from pywinservicemanager.WindowsServiceConfigurationManager import GetService
        
           serviceName = 'TestService'
           myService = WindowsServiceConfigurationManager.GetService(serviceName)
           status = myService.GetServiceStatus()
           print status
        
        
        * **Exists**: Deletes the Service
          Returns if the service exists
        
        .. code:: python
        
           from pywinservicemanager.WindowsServiceConfigurationManager import Exists
        
           serviceName = 'TestService'
           myService = WindowsServiceConfigurationManager.GetService(serviceName)
           print myService.Exists()
        
        
        
        FailureActionConfigurationType
        ------------------------------
        Represents the action the service controller should take on each failure of a
        service. A service is considered failed when it terminates without reporting a
        status of SERVICE_STOPPED to the service controller
        
        The constructor of this object takes the following parameters:
          1. *failureActionsTypeList*: List of FailureActionType Objects
              - Valid Value: List of FailureActionType Objects (see below)
              - Default:Value None
          2. *resetPeriodType*: The time after which to reset the failure count to zero if there are no failures, in seconds
              - Valid Value: int or ResetPeriodType(see below)
              - Default:Value None
          3. *rebootMessageType*: The message to be broadcast to server users before rebooting in response to the SC_ACTION_REBOOT service controller action
              - Valid Value: string or RebootMessageType (see below)
              - Default:Value None
          4. *commandLineType*: The command line of the process for the CreateProcess function to execute in response to the SC_ACTION_RUN_COMMAND service controller action. This process runs under the same account as the service.
              - Valid Value: string or CommandLineType (see below)
              - Default:Value None
        
        
        Example:
        
        .. code:: python
        
            import pywinservicemanager.ConfigurationTypes as ConfigurationTypes
        
            failureActionList = []
            delay = 1000
        
            failureActionList.append(ConfigurationTypes.FailureActionTypeFactory.CreateRestartAction(delay))
            failureActionList.append(ConfigurationTypes.FailureActionTypeFactory.CreateRunCommandAction(delay))
            resetPeriod = ConfigurationTypes.FailureActionConfigurationResetPeriodType(1)
            rebootMsg = ConfigurationTypes.FailureActionConfigurationRebootMessageType('MyRebootMessage')
            commandLine = ConfigurationTypes.FailureActionConfigurationCommandLineType('MyCommandLineCommand')
        
            failureActions = ConfigurationTypes.FailureActionConfigurationType(failureActionList, resetPeriod, rebootMsg, commandLine)
        
            #or
            failureActionList = []
            delay = 1000
        
            failureActionList.append(ConfigurationTypes.FailureActionTypeFactory.CreateRestartAction(delay))
            failureActionList.append(ConfigurationTypes.FailureActionTypeFactory.CreateRunCommandAction(delay))
        
            resetPeriod = 1
            rebootMsg = 'MyRebootMessage'
            commandLine = 'MyCommandLine'
        
            failureActions = ConfigurationTypes.FailureActionConfigurationType(failureActionList, resetPeriod, rebootMsg, commandLine)
        
        
        `More information about FailureActionConfiguration Mapping
        <https://msdn.microsoft.com/en-us/library/windows/desktop/ms685939(v=VS.85).aspx>`_.
        
        
        FailureActionType
        -----------------
        Represents an action that the service control manager can perform.
        
        A FailureAction type can be reurned by the factory object FailureActionTypeFactory, where there are 4 methods defined and an int which represents the delaly as the input parameter:
          1. Factory Methods:
              - FailureActionTypeFactory.CreateNoAction(delay): No action.
              - FailureActionTypeFactory.CreateRestartAction(delay): Restart the service.
              - FailureActionTypeFactory.CreateRebootAction(delay): Reboot the computer. If the service uses the reboot action, the caller must have the SE_SHUTDOWN_NAME `privilege <https://msdn.microsoft.com/en-us/library/windows/desktop/aa379306(v=vs.85).aspx>`_. For more information, see `Running with Special Privileges <https://msdn.microsoft.com/en-us/library/windows/desktop/ms717802(v=vs.85).aspx>`_.
              - FailureActionTypeFactory.CreateRunCommandAction(delay):  Run a command.
          2. delay: The time to wait before performing the specified action, in milliseconds.
        
        Example:
        
        .. code:: python
        
            import pywinservicemanager.ConfigurationTypes as ConfigurationTypes
            myAction = ConfigurationTypes.FailureActionTypeFactory.CreateRestartAction(300)
        
        `More information about FailureAction
        <https://msdn.microsoft.com/en-us/library/windows/desktop/ms685126(v=vs.85).aspx>`_.
        
        
        ResetPeriodType
        ---------------
        The time after which to reset the failure count to zero if there are no failures, in seconds.
        The input is of time int
        
        Example:
        
        .. code:: python
        
            import pywinservicemanager.ConfigurationTypes as ConfigurationTypes
            resetPeriod = ConfigurationTypes.FailureActionConfigurationResetPeriodType(1)
        
        
        FailureActionConfigurationRebootMessageType
        -------------------------------------------
        The message to be broadcast to server users before rebooting in response to the SC_ACTION_REBOOT service controller action.
        If this value is None, the reboot message is unchanged. If the value is an empty string (""), the reboot message is deleted and no message is broadcast.
        
        Example:
        
        .. code:: python
        
            import pywinservicemanager.ConfigurationTypes as ConfigurationTypes
            rebootMessage = ConfigurationTypes.FailureActionConfigurationRebootMessageType("My Reboot Message")
        
        
        FailureActionConfigurationRebootMessageType
        -------------------------------------------
        The message to be broadcast to server users before rebooting in response to the SC_ACTION_REBOOT service controller action.
        If this value is None, the reboot message is unchanged. If the value is an empty string (""), the reboot message is deleted and no message is broadcast.
        
        Example:
        
        .. code:: python
        
            import pywinservicemanager.ConfigurationTypes as ConfigurationTypes
            rebootMessage = ConfigurationTypes.FailureActionConfigurationRebootMessageType("My Reboot Message")
        
        
        FailureActionConfigurationRebootMessageType
        -------------------------------------------
        The command line of the process for the CreateProcess function to execute in response to the SC_ACTION_RUN_COMMAND service controller action. This process runs under the same account as the service.
        If this value is None, the command is unchanged. If the value is an empty string (""), the command is deleted and no program is run when the service fails.
        
        Example:
        
        .. code:: python
        
            import pywinservicemanager.ConfigurationTypes as ConfigurationTypes
            commandLine = ConfigurationTypes.FailureActionConfigurationCommandLineType("myCmd.exe")
        
        
        ===================
        Further Information
        ===================
        For more information the windows API implemented in the package and/or how the service controller utility works, please consult the `win32service documentation
        <http://docs.activestate.com/activepython/2.6/pywin32/win32service.html>`_.
Platform: UNKNOWN
