Metadata-Version: 1.1
Name: ratom
Version: 1.0.0
Summary: Rage Against The Outdated Machine
Home-page: https://github.com/qtfkwk/ratom
Author: qtfkwk
Author-email: qtfkwk+ratom@gmail.com
License: UNKNOWN
Description: Description
        -----------
        
        RATOM stands for "Rage Against The Outdated Machine".
        
        Its purpose is to simply update all the things that need updating.
        
        The primary use for RATOM is under current Python 2.x on a supported
        operating system that uses one or more of the supported software.
        
        Features
        --------
        
        * Supports Mac OSX, FreeBSD (freebsd-update, portsnap, pkg),
          ClamAV/freshclam, Homebrew, Cask, Perlbrew, CPAN Minus, pyenv, pip,
          rbenv, gem, npm, Metasploit Framework, Git repositories, and
          Microsoft AutoUpdate via a plugin architecture
        * Markdown-formatted output with all update and informational commands
          shown with their output and in pretty terminal colors via the
          `blessings <https://pypi.python.org/pypi/blessings>`_ package; also
          allows subsequent processing by redirecting or piping
        * Dry run mode (``-n``) processes configuration file and command line
          arguments, performs checks and intermediate processing, prints
          commands to show what will run given configuration and system
          settings, but doesn't actually update anything
        * Configuration via ``~/.ratom/config.json`` or an argument to ``-c``
          option; allows switching the ordering of plugins (not recommended),
          explicit enabling or disabling of plugins, and specifying a
          different path for the log file
        * Logs intermediate processing commands and other informational
          messages to the configured log location (``~/.ratom/ratom.log`` by
          default) or an argument to ``-l`` option
        * Shows full configuration details if ``--show-config`` option is used
        * Each plugin provides a ``check`` function to determine whether to
          run and a ``main`` function that performs the update
        * Full documentation `online <http://pythonhosted.org/ratom>`_, or as
          HTML (gzipped tar) or PDF via `Sphinx <http://www.sphinx-doc.org/>`_
        
        Design
        ------
        
        * Show all configuration, commands, and output
        
            * intermediate commands are shown in the log versus the output for
              brevity's sake
        
        * Use a modular plugin architecture, not only for code organization,
          but to easily support more software
        * Generating a report should be easy
        * Run sequentially to avoid issues
        * Halt when a command fails
        
        Installation
        ------------
        
        ::
        
            pip install ratom
        
        Can also install from either the binary distribution (or "wheel") or
        source distribution files::
        
            pip install ratom-1.0.0-py2-none-any.whl
            pip install ratom-1.0.0.zip
        
        Usage
        -----
        
        ::
        
            usage: all.py [-h] [-n] [-c PATH] [-l PATH] [--show-config]
                          [plugin [plugin ...]]
            
            optional arguments:
              -h, --help     show this help message and exit
            
            ratom options:
              -n             Dry run; don't actually update anything
              -c PATH        Use alternate configuration file; default:
                             ~/.ratom/config.json
              -l PATH        Log to PATH; default: ~/.ratom/ratom.log
              --show-config  Show full configuration details
              plugin         Specific plugin(s) to run in the specified order; default:
                             "macosx freebsd clamav homebrew cask perlbrew cpanm pyenv pip
                             rbenv gem npm msf git microsoft"; ignored if running a plugin
                             directly
        
        Examples
        --------
        
        RATOM can be used in a few ways...
        
        1. Install with pip and run via the installed ``ratom`` shim
        2. Clone the Git repository or unzip the source distribution and run
           either ``ratom/all.py`` or one of the plugins directly
        3. Do #2 but also add symlinks to somewhere in your PATH::
        
                cd ~/bin
                ln -s path/to/ratom/ratom/all.py ratom
        
        4. Use the Python REPL (or programtically from other Python code).
           Import ``ratom.all`` or a specific plugin, then call a ``main``
           function and pass any arguments in command-line fashion via the
           ``argv`` argument or a configuration dictionary via the ``cfg``
           argument.
           Note that if you want to call a ``check`` function, you'll need to
           import ``raton.common``.
           See also the `API Reference`_.
        
           ::
        
                $ python
                >>> import ratom.all
                >>> ratom.all.main()
                ...
                >>> ratom.clamav.main()
                ...
                >>> import ratom.clamav
                >>> ratom.clamav.main()
                ...
                >>> ratom.clamav.main(['-n'])
                ...
                >>> import ratom.common
                >>> ratom.clamav.check()
                True
        
        Plugins
        -------
        
        The subsections below list details about each individual plugin.
        
        In general, it is the user's responsibility to handle various side
        effects of individual plugins, for example some plugins may require
        reprocessing terminal startup scripts (``.bashrc``, etc) or even
        rebooting.
        Reprocessing startup scripts can be acheived by restarting the
        terminal session either by issuing ``exit`` or Ctrl+D and reopening a
        terminal or logging in again, or perhaps running ``exec $SHELL``.
        
        Also note that RATOM runs as the user that runs it, upon the
        assumption that the user has the appropriate permissions, etc.
        Of course, if a plugin passes its ``check`` function, but lacks
        permissions to perform the update then the command *should* fail, but
        this depends on the individual update utility.
        If it fails (exits with a non-zero value), RATOM will halt.
        If this occurs, you might have an issue of this kind, and your courses
        of action include fixing permissions of the item and its files for
        your user, disabling the plugin in the configuration file, or
        modifying the plugin's ``check`` or ``main`` functions to work
        correctly.
        Some ideas for the last fix might be to check if the user has proper
        permissions, has a particular UID/EUID/GID/EGID, or to run the
        command(s) via ``su`` or ``sudo``.
        
        all
        '''
        
        Attempts to run all plugins listed as command line arguments, in the
        plugins list in the configuration file, or in the plugins list in the
        ``common.defaults`` dictionary (``common.defaults['plugins']``).
        Regardless where the list of plugins is found, the plugins are run in
        the order given.
        The default order is designed to update operating systems first, then
        any other security-related items, followed by development tools and
        personal tools/repositories, and finally any GUI-based update
        mechanisms.
        Of course, each plugin must also pass its respective ``check``
        function in order to actually perform the update.
        This process prevents blindly attempting to run plugins on systems
        that either don't have the software they update or more importantly,
        when the user doesn't want RATOM to update them.
        
        apple
        '''''
        
        Updates Apple Mac OSX via the ``softwareupdate`` utility.
        An update may require reboot and the output will indicate this; the
        rest of the update process will continue and it is the user's
        responsibility to perform the reboot.
        
        cask
        ''''
        
        Updates Homebrew casks by running ``brew cask info`` for each
        installed cask package as an intermediate command to determine whether
        there is an update available.
        If so, it runs ``brew cask install`` to install the updated cask.
        Finally, ``brew cask cleanup`` is run to remove temporary files and
        perform general maintainance tasks.
        
        clamav
        ''''''
        
        Manually updates Clam AntiVirus signatures via ``freshclam``.
        This is in contrast to using the ``freshclamd`` daemon which can
        likely do a better job of keeping the signatures up-to-date.
        However, running freshclam manually confirms that the signatures are
        up-to-date whether the system uses the daemon or not.
        
        cpanm
        '''''
        
        Uses cpan-outdated, which is installable via
        ``cpanm App::cpanoutdated``, to check for outdated Perl/CPAN modules
        (``cpan-outdated -p``), then updates each via ``cpanm``.
        This plugin runs against the "current" Perl, without regard for or
        knowledge of things like Perlbrew.
        
        freebsd
        '''''''
        
        Actually attempts to update several individual FreeBSD-specific items
        as a single plugin.
        Supported items are freebsd-update, portsnap, pkg, and a custom
        utility called ckver, that queries the freebsd.org website to compare
        the latest release version to the current running version on the
        system.
        This plugin only updates the currently-tracked branch of FreeBSD; it
        does not upgrade your system to the current release branch; i.e. if
        your system has 10.2-RELEASE and 10.3-RELEASE is available, it will
        not upgrade to 10.3-RELEASE for you, but ckver will tell you if a new
        release is avaiable.
        
        gem
        '''
        
        Runs ``gem update`` to update globally-installed gems for the
        "current" selected Ruby, without regard for or knowledge of things
        like rbenv.
        
        git
        '''
        
        Performs a ``git pull`` for each repository or symlink to a repository
        in ``~/.ratom/git/`` after first showing where the symlink points (if
        it's a symlink) and the set of tracked repositories via
        ``git remote -v``.
        The ``check`` function fails if either the ``~/.ratom/git`` directory
        does not exist or it does not contain any repositories.
        
        homebrew
        ''''''''
        
        Updates Homebrew via ``brew update; brew upgrade --all``, then
        performs clean up via ``brew cleanup``.
        
        It also attempts to avoid specific issues encountered when upgrading
        vim by restoring the "system" version of Python via pyenv before
        running the upgrade command.
        This has had mixed success, has some unintentional temporary
        system-wide side effects, and should be considered a work-in-progress.
        
        microsoft
        '''''''''
        
        Runs the GUI-based Microsoft AutoUpdate utility, which updates
        Microsoft software installed on a Mac OSX system.
        Unfortunately, this appears to be the only way to confirm that the
        software is up-to-date, since searching for a command-line utility has
        so far been fruitless.
        This plugin blocks while the user clicks the "Check for Updates"
        button, installs any updates, then closes the GUI.
        
        msf
        '''
        
        Updates Metasploit Framework via ``msfupdate``.
        
        npm
        '''
        
        Checks for updates, attempts to update, and confirms updates of global
        NPM (Node.js) modules.
        
        perlbrew
        ''''''''
        
        Updates Perlbrew and shows the installed versions of Perl and
        available versions of Perl; does not install any version of Perl for
        you.
        
        pip
        '''
        
        Upgrades the ``pip`` package first, then attempts upgrading all other
        installed packages.
        
        pyenv
        '''''
        
        Shows the installed versions of Python and the latest versions in the
        2.7 and 3.5 branches; does not install any version of Python for you.
        
        rbenv
        '''''
        
        Show the installed versions of Ruby and the latest version in the 2.3
        branch; does not install any version of Ruby for you.
        
        Versions
        --------
        
        +---------+------------+-----------------+
        | Version | Date       | Comments        |
        +=========+============+=================+
        | 1.0.0   | 2016-05-25 | Initial release |
        +---------+------------+-----------------+
        
        Issues
        ------
        
        Please report issues via
        `Github Issues <https://github.com/qtfkwk/ratom/issues>`_.
        
        Better yet, fork the Github repository, fix the issue, and send a PR
        (pull request)!
        
        Contact
        -------
        
        * `Github <https://github.com/qtfkwk/ratom>`_
        * `PyPI <https://pypi.python.org/pypi/ratom>`_
        * `Documentation <http://pythonhosted.org/ratom>`_
        
        To do
        -----
        
        * support Debian/Ubuntu (apt-get), Red Hat/Fedora/CentOS (yum)...
        * run ``brew upgrade --all`` with the pyenv version set to
          'system' without using ``pyenv global``
        * update Perl modules via CPANM for all perlbrew perls?
        * update Python modules via pip for all pyenv pythons?
        * update Ruby gems for all rbenv rubys?
        
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: BSD License
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 2.7
