Metadata-Version: 1.0
Name: freestuffs
Version: 0.1.2
Summary: Find free stuff near you!
Home-page: https://github.com/fenimore/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 package can be used to create a web application, such as the
        Treasure-map_ (source_), or for use on Twitter_.
        
        .. _Github: https://github.com/polypmer/freestuffs
        .. _Twitter: https://twitter.com/Freeebot
        .. _source: https://github.com/polypmer/treasure-map
        .. _Treasure-map: http://treasure.plyp.org
        
        Installation
        ------------
        
        ``freestuffs`` can be installed with pip:
        
        .. code-block:: bash
        
            pip install freestuffs
        
        The package has the following dependencies which are automatically
        installed by pip:
        
        * ``beautifulsoup4``
        * ``bs4``
        * ``folium``
        * ``geopy``
        * ``requests``
        * ``Unidecode``
        
        Additionally, these may be manually installed using pip with
        ``pip install -r requirements.txt``.
        
        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.
        
        
        Legend
        +++++++++++++++++
        
        - 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, ecran, 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 <http://github.com/polypmer/freestuff-bot/issues>`_.
        
Platform: UNKNOWN
