Metadata-Version: 1.1
Name: awake
Version: 1.0
Summary: Command and library to "wake on lan" a remote host.
Home-page: http://github.com/cyraxjoe/awake
Author: Joel Rivera
Author-email: rivera@joel.mx
License: Copyright (C) 2012  Joel Juvenal Rivera Rivera rivera@joel.mx

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3
as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

Download-URL: https://github.com/cyraxjoe/awake/archive/v1.0.zip
Description: Awake
        ======
        *Command and library to "wake on lan" a remote host.*
        
        If you  want to know something more about the WoL stuff check 
        `the wikipedia page`_.
        ::
        
            Usage: awake [options] MAC1 [MAC2 MAC3 MAC...]
        
                Options:
                  --version             show program's version number and exit
                  -h, --help            show this help message and exit
                  -p PORT, --port=PORT  Destination port. (Default 9)
                  -b BROADCAST, --broadcast=BROADCAST
                                        Broadcast ip of the network. (Default 255.255.255.255)
                  -d DESTINATION, --destination=DESTINATION
                                        Destination ip/domain to connect and send the packet,
                                        by default use broadcast.
                  -f FILE, --file=FILE  Use a file with the list of macs, separated with -s,
                                        by default \n. If any mac (line where -s \n), have the
                                        "#" character, any following character is considered a
                                        comment. Can be used multiple times for multiple
                                        files.
                  -s SEPARATOR, --separator=SEPARATOR
                                        Pattern to be use as a separator with the -f option.
        				(Default \n)
                  -q, --quiet           Do not output informative messages.
        
        
        Requirements
        -------------
        
        Any cpython (common python) implementation  from 2.4 to 3.X.
        
        Probably it also works with jython, ironpython and pypy but I haven't
        personally tested on those implementations.
                
        
        Installation
        ------------
        
        ::
        
            pip install awake
        
        
        Or with the old `easy_install`
        
        ::
        
        
            easy_install awake
        
        Or with the source
        
        ::
        
        
            python setup.py install
        
        
        
        Upgrading from 0.X to 1.0
        --------------------------
        
        Make sure the previous CLI script `awake.py` gets removed from the script installation
        path after the upgrading, e.g. in linux `/usr/bin/` the new cli interface is
        just `awake` and  if the file `awake.py` exists at the same level of the script 
        then the new `awake` going to try to fetch the required modules from the 
        old cli script `awake.py`.
        
        
        CLI Examples
        ------------
        
        **Wake-on-lan a group of computers in the current network**::
        
            awake 1c:6f:65:31:aa:5f 1c6c2531e051 3f.6c.25.31.e0.55 3b-6c-21-31-e0-41
        
        which is equivalent to::
        
            awake -f ~/list_of_macs
        
        and in the file ``list_of_macs`` have one MAC per line or use the ``-s`` option.
        
        ``list_of_macs`` content::
        
            1c:6f:65:31:aa:5f # web1
            1c6c2531e051      # web2
            # The rest
            3f.6c.25.31.e0.55
            3b-6c-21-31-e0-41
        
        The format of the MAC is flexible in the sense that can use any character to group
        the digits of the MAC, except for the reserved character *#* for comments.
        
        
        **Wake-on-lan a computer or group of computers in a external network**
        
        For this situation, you need to forward a port in your router, for example to
        forward 9999 to 9 in the local network o 7777 to 7, check the documentation if 
        your router or modem. After the port has been configured you can use `DDNS`_
        to have a reference to the current ip address of your router/modem and use awake
        in this way::
        
            awake -a myhouse.homedns.com -p 9999 -f ~/file_with_my_macs 
           
        or use any other option, the important here is to use the ``-a`` and ``-p`` options 
        to specify the destination to send the magic packet.
        
        **Alternative method to invoke awake**
        
        Awake can be used calling the module directly from python::
        
            python -m awake 
        
        Is the same interface as the installed script ``awake``, this is very useful in
        platforms like windows, when the `PythonXX/Scripts` is not set in the `PATH`.
        
        
        As a library
        ------------
        
        The real functionality of the wake-on-lan is provided from a small function 
        that is implemented in the provided module ``awake.wol``::
        
            send_magic_packet(mac, broadcast='255.255.255.255', dest=None, port=9)
                Send  a "magic packet" to the given destination mac to wake up 
                the host, if `dest` is not specified then the packed is broadcasted.
        
        
        Apart from the awake script the WOL functionality can be easily integrated
        in your python programs with a simple call to the function like::
        
            from awake import wol
        
            def sysadmin_function_x(mac, *args):
                # some stuff...
                wol.send_magic_packet(mac)
                # some more stuff...
            
        
        Tests
        -----
        
        The tests are designed to be executed with the python unittest module,
        you can run the tests from the folder `test`::
        
            cd test
            python -m unittest discover 
        
        
        In case that you want to run the tests in python < 2.7, you will need the 
        `unittest2`_ module.
        
        The general recommended process to develop is using `virtualenv`_ and after creating the
        environ just run::
        
            ./environ/bin/python setup.py install
            ./environ/bin/python -m unittest discover 
        
        
        
        Improvements, bugs?
        -------------------
        
        For any improvement or bug, feel free to create an `issue`_ in the github project.
        
        .. _the wikipedia page: http://en.wikipedia.org/wiki/Wake-on-LAN
        .. _DDNS: http://en.wikipedia.org/wiki/DDNS
        .. _issue: http://github.com/cyraxjoe/awake/issues
        .. _pypi: http://pypi.python.org/pypi/awake
        .. _unittest2: http://pypi.python.org/pypi/unittest2
        .. _virtualenv: http://pypi.python.org/pypi/virtualenv
        
Platform: linux2
Platform: win32
Platform: cygwin
Platform: darwin
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 2.4
Classifier: Programming Language :: Python :: 2.5
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.0
Classifier: Programming Language :: Python :: 3.1
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Provides: awake
