Metadata-Version: 1.1
Name: bcferries
Version: 0.0.10
Summary: BC Ferries Python Library
Home-page: http://yasyf.github.io/bcferries/
Author: Yasyf Mohamedali
Author-email: yasyfm@gmail.com
License: MIT
Download-URL: https://github.com/yasyf/bcferries/tarball/0.0.10
Description: BC Ferries Python Library
        =========================
        
        This is the Python client library for interacting with information
        published on the `BC Ferries mobile
        site <http://mobile.bcferries.com/>`__. It is essentially a wrapper
        around a BeautifulSoup-powered scraper. Better documentation and tests
        are still in the works; feel free to contribute! The source code for
        this library can be found at
        `yasyf/bcferries <https://github.com/yasyf/bcferries>`__ on GitHub.
        
        Installation
        ------------
        
        ``pip install bcferries``
        
        Setup
        -----
        
        Some functions require interaction with a geocoding service; the Google
        Maps API is used for this. In order to prevent severe rate limiting,
        you'll want to acquire an API key. To let ``bcferries`` know about this
        key, set it as the ``GOOGLE_MAPS_API_KEY`` environment variable.
        Alternatively, you can pass it as an optional keyword argument to the
        constructor.
        
        .. code:: python
        
            from bcferries import BCFerries
        
            bc = BCFerries(google_maps_api_key='xxx-xxx-xxx')
        
        Usage
        -----
        
        .. code:: python
        
            bc = BCFerries()
        
        Terminals
        ~~~~~~~~~
        
        .. code:: python
        
            bc.nearest_terminal('Qualicum Beach')
            # BCFerriesTerminal(Nanaimo (Duke Pt))
        
            terminals = bc.terminals()
            # {u'Horseshoe Bay': BCFerriesTerminal(Horseshoe Bay), u'Tsawwassen': BCFerriesTerminal(Tsawwassen)}
            t = terminals['Tsawwassen']
            # BCFerriesTerminal(Tsawwassen)
            t.updated_at()
            # datetime.datetime(2014, 12, 29, 0, 4)
            t.next_crossing()
            # BCFerriesCrossing(Tsawwassen to Duke Point at 5:15am)
            t.location().address
            # u'Ferry Causeway, Delta, BC V4M, Canada'
        
        Routes
        ~~~~~~
        
        .. code:: python
        
            routes = t.routes()
            # {u'Tsawwassen to Duke Point': BCFerriesRoute(Tsawwassen to Duke Point)}
            r = routes['Tsawwassen to Duke Point']
            # BCFerriesRoute(Tsawwassen to Duke Point)
        
            r.from_, r.to
            # (BCFerriesTerminal(Tsawwassen), BCFerriesTerminal(Nanaimo (Duke Pt)))
            r.distance()
            # Distance(61.9591068557)
            r.car_waits
            # 0
        
        Crossings
        ~~~~~~~~~
        
        .. code:: python
        
            crossing = r.crossings()['10:45pm']
            # BCFerriesCrossing(Tsawwassen to Duke Point at 5:45pm)
            crossing.capacity
            # BCFerriesCapacity(18% Full)
        
        Schedules
        ~~~~~~~~~
        
        .. code:: python
        
            schedule = r.scheduled('12:45 PM')
            # BCFerriesScheduledCrossing(Queen of Alberni at 12:45 PM)
            schedule.status
            # u'On Time'
            schedule.sailing_time
            # datetime.timedelta(0, 7200)
            schedule.is_late()
            # False
            schedule.is_departed()
            # True
        
        Fuzzy Results
        -------------
        
        All returned dictionaries have fuzzy string matching on they keys.
        
        .. code:: python
        
            routes['Tsawwassen to Duke Point'] == routes['Tsaw to DP']
            # True
        
        There is also fuzzy time matching on keys that represent a nearby time.
        
        .. code:: python
        
            r = routes['HBay to DBay']
            schedule = r.schedule()
            schedule['6:12 PM']
            # BCFerriesScheduledCrossing(Queen of Cowichan at 6:30 PM)
        
        ``datetime`` objects can also be used as keys.
        
        .. code:: python
        
            from datetime import datetime
        
            datetime.datetime.now()
            # datetime.datetime(2014, 12, 28, 10, 42, 35, 630996)
            schedule[datetime.datetime.now()]
            # BCFerriesScheduledCrossing(Coastal Renaissance at 10:40 AM)
        
        Caching
        -------
        
        ``bcferries`` caches the 16 most used API calls for up to five minutes
        by default. You can change this behavior as below. This must be done
        before creating a ``BCFerries`` object.
        
        .. code:: python
        
            import bcferries
            import datetime
        
            bcferries.set_cache_size(16)
            bcferries.set_cache_timeout(datetime.timedelta(minutes=5))
        
        You can also pass any function the ``ignore_cache`` keyword argument to
        bypass the cache, or call the ``flush_cache`` method on ``BCFerries`` to
        clear the entire cache.
        
        .. code:: python
        
            terminals = bc.terminals() # initial call takes multiple seconds
            terminals = bc.terminals() # repeated call returns almost instantly
            terminals = bc.terminals(ignore_cache=True) # takes multiple seconds to return
        
            bc.flush_cache() # wipes the cache
        
        Export
        ------
        
        You can export any subset of information with a call to ``to_dict`` on
        any object. You can also use ``to_fuzzy_dict`` and ``to_json`` as
        needed. To export all available information, call any of these methods
        on a ``BCFerries`` instance, and be prepared to wait a while.
        
        .. code:: python
        
            crossing.capacity
            # BCFerriesCapacity(18% Full)
            crossing.capacity.to_dict()
            # {'passenger_filled': 32, 'mixed_filled': 4, 'name': '18% Full', 'filled': 18}
        
Keywords: bc ferries,schedule
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
