Metadata-Version: 1.0
Name: freestuffs
Version: 0.1
Summary: Find free stuff near you!
Home-page: https://github.com/polypmer/freestuffs
Author: Fenimore Love
Author-email: UNKNOWN
License: MIT
Description: ============
        Introduction
        ============
        
        Free Stuffs!
        ------------
        
        This is a python 3.x package which scrapes free stuff from Craigslist. 
        freestuffs is under the MIT license. Check out the `source code <https://github.com/polypmer/freestuff-bot>`_
        and the `docs <http://freestuffs.readthedocs.io/en/latest>`_.
        
        * Using StuffScraper one can gather a list of free stuffs. 
        * Using StuffCharter, one can create an HTML map of the free stuffs.
        
        This library can be used to create a simple web application, such as the
        `Treasure map <https://github.com/polypmer/treasure-map>`_, or a simple
        `Twitter bot <https://github.com/polypmer/freestuff-bot>`_
        
        Installation
        ------------
        
        Install using pip, requires python 3 and these dependences:
        
        * requests
        * geopy
        * folium
        * BeautifulSoup4
        * unidecode
        
        Install::
        
            pip install freestuffs
        
        Or, with virtualenvwrapper installed:
        
        .. code-block:: bash
        
            mkvirtualenv freestuffs
            pip install freestuffs
        
        Getting Started
        ---------------
        
        Stuffs
        ******
        
        The stuff class corresponds to a `Craiglist <https://www.craigslist.org>`_
        free stuff posting. It's basic characteristics include title and location.
        Notably, there is no price attribute. If the posting has no image, the 
        `Wikipedia <https://www.wikipedia.org>`_ no-image image is used in it's place.
        
        ::
            
            >>> from freestuffs.stuff_scraper import StuffScraper
            >>> stuffs = StuffScraper('montreal', 5).stuffs
            >>> print(stuffs[0])
            what: free shelves 
             where: Workman St, montreal 
             link: http://montreal.craigslist.ca/zip/5629811181.html 
             image: https://images.craigslist.org/00r0r_4p06sM5Hn4O_300x300.jpg
        
        Scape Stuffs
        ************
        
        The StuffScraper class will scrape Craiglist for
        free stuff. 
        
        ::
        
            >>> from freestuffs.stuff_scraper import StuffScraper
            >>> stuffs = StuffScraper('montreal', 5).stuffs # precise=False
            >>> print(stuffs[0].thing)  # Title
            Meubles / furniture
        
        In order for the scraper to automatically
        scrape for latitude and longitude coordinates, pass in the
        parameter precise=True into the constructor.
        
        ::
        
            >>> from freestuffs.stuff_scraper import StuffScraper
            >>> stuffs = StuffScraper('montreal', 5, precise=True).stuffs
            >>> print(stuffs[0].coordinates)
            ['45.617854', '-73.633931']
        
        Chart Stuffs
        ************
        
        The StuffCharter class will produce a folium Map object populated
        with free stuff from the StuffScraper.
        
        ::
        
            >>> from freestuffs.stuff_scraper import StuffScraper
            >>> from freestuffs.stuff_charter import StuffCharter
            >>> stuffs = StuffScraper('montreal', 5, precise=True).stuffs
            >>> stuffs_chart = StuffCharter(stuffs)
            call save_map(path) generate html map
            >>> type(map.treasure_map)
            <class 'folium.folium.Map'>
        
        The StuffCharter object is a wrapper around the folium.Map.
        Call :code:`save_map(HTML_PATH, CSS_PATH)`
        
        ::
        
            >>> stuffs_chart.save_map('webmap', 'static/style.css')
            
        This function creates a directory if it is not found in the path. Call instead
        :code:`save_test_map()` to generate an HTML map in the current directory.
        
        Chart Legend
        ------------
        
        Diminishing Order
        +++++++++++++++++
        
        - The smaller the posting, the older it is.
        - The darker the border, the higher the amount of overlap.
        
        Triage
        ++++++
        
        The triage checks for regex search in this order:
         
        #. Red are furniture "(wood|shelf|shelves|table|chair|scrap|desk)".
        #. Blue are electronics "(tv|sony|écran|speakers|wire|electronic|saw|headphones|arduino)". 
        #. Black are the "desired" stuffs "(book|games|cool|guide|box)". 
        #. White is default (no regex search matches).
        
        
        Support
        -------
        
        The easiest way to get support is to open an issue on Github_.
        
        .. _Github: http://github.com/polypmer/freestuff-bot/issues
        
Platform: UNKNOWN
