infuze python module user guide

WURFL InFuze for Python: User Guide

This is a Python module wrapping the WURFL C API and encapsulating it in an object oriented manner, to provide a fast, intuitive interface.

Installing libwurfl


IMPORTANT: Installing libwurfl

In order for the Module to work it is ESSENTIAL that the libwurfl library is installed on your system. libwurfl is provided in your Customer Vault/FileX.

If you have not already installed libwurfl, instructions can be found here. Release notes for each API can be found here.

Setup

WURFL InFuze for Python is built/installed using the Python virtualenv utility. The requirements.txt and setup.py files contain relevant setup code.

Requirements

The C libwurfl library must be installed and usable by C as #include <wurfl/wurfl.h>.

Python development headers and setuptools must also be installed. On Debian this is done by:

$ apt-get install python-dev python-setuptools

On CentOS this is done by:

$ yum install python-dev python-virtualenv

Installation

WURFL InFuze for Python is distributed as Python egg and can be installed using easy_install.

Once you have obtained the egg from your file manager and installed the InFuze WURFL library, you can run:

$ easy_install pywurfl-x.x-py2.7-linux-x86_64.egg

Usage

Once installed, WURFL InFuze for Python can immediately be used in Python using a simple import pywurfl. For pre-installation testing purposes, the bootstrapped bin/python interpreter can be used.

>>> import pywurfl

The pyWurfl functionality is encapsulated in an object representing a connection to a WURFL DB. It must be initialized with the path to a valid wurfl.xml file. Only two lines are need to import the library and load the file:

>>> from pywurfl.wurfl import Wurfl, CACHE_PROVIDERS
>>> wurfl = Wurfl("/usr/share/wurfl/wurfl-eval.xml")

The constructor can also be called with the keyword arguments patches and capabs, both of which are lists of strings specifying where to find WURFL patches, and which specific capabilities to load.

>>> patch_filename = pywurfl.temp_patch.name
>>> wurfl = Wurfl(
...   capabs = ["brand_name", "model_name", "is_tablet",
...   "pointing_method", "resolution_width", "device_os_version",
...   "device_os", "mobile_browser", "is_smartphone",
...   ],
...   patches = [patch_filename])

The argument high_accuracy (a True/False flag) can also be provided in order to switch WURFL from high performance mode (in which desktop browsers are not distinguished from each other) to high accuracy mode.

The last arguments that can be provided to the WURFL constructor are cache_provider and cache_extra_config. The value of cache_provider must be one of the values provided in the CACHE_PROVIDERS dictionary in the module, while cache_extra_config is expected to be a string containing configuration for the selected cache mechanism. Consult the Infuze for C++ API documentation for more details on possible cache configuration.

>>> wurfl = Wurfl(
...   capabs = ["brand_name", "model_name", "is_tablet",
...   "pointing_method", "resolution_width", "device_os_version",
...   "device_os", "mobile_browser", "is_smartphone",
...   ],
...   patches = [patch_filename],
...   high_accuracy = True,
...   cache_provider = CACHE_PROVIDERS["DOUBLE_LRU"], 
...   cache_extra_config="10000, 3000")

The most common and simple way to use this WURFL object is to parse browser user agents with it. To do so, let's first define some arbitrary UA's to use for testing.

>>> firefox = "Mozilla/5.0 (X11; Linux x86_64; rv:22.0) Gecko/20100101 Firefox/22.0"

>>> chrome = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/28.0.1500.71 Safari/537.36"

>>> android = "Mozilla/5.0 (Linux; U; Android 2.2; en-us; SCH-I800 Build/FROYO) AppleWebKit/533.1 (KHTML, like Gecko) Version/4.0\
... Mobile Safari/533.1"

>>> android_tab = "Mozilla/5.0 (Android; Tablet; rv:23.0) Gecko/23.0 Firefox/23.0" 

Next, let's parse a couple into WURFL devices.

>>> firefox_dev = wurfl.parse_useragent(firefox)
>>> chrome_dev = wurfl.parse_useragent(chrome)
>>> android_dev = wurfl.parse_useragent(android)

Note that the WURFL object does local caching of these devices. You can pass in a second argument of False (or the keyword argument cache=False) to disable this behavior.

>>> firefox_dev2 = wurfl.parse_useragent(firefox)
>>> firefox_dev is firefox_dev2 
False

>>> chrome_dev2 = wurfl.parse_useragent(chrome, cache=False)
>>> chrome_dev is chrome_dev2
False

These WURFL devices are used to query information about their particular user agents.

>>> print firefox_dev.id
generic_web_browser

>>> print android_dev.id
generic_android_ver2_2

Traversal up the device tree (to parent) is also possible.

>>> print android_dev.parent.parent.id
generic

They also have several different ways to retrieve their browser capabilities.

>>> print android_dev.get_capability("brand_name")
Generic

>>> print android_dev.get_capability("model_name")
Android 2.2

>>> caps = android_dev.get_capabilities(["brand_name",
...                                      "model_name"])
>>> caps == {'brand_name': 'Generic', 'model_name': 'Android 2.2'}
True

>>> caps_all = android_dev.get_all_capabilities()
>>> all(item in caps_all.items() for item in 
...     [('brand_name', 'Generic'), ('model_name', 'Android 2.2')])
True

When a particular capability is not found, the API should return None as a value.

>>> print android_dev.get_capability("not_a_capability")
None

Virtual capabilities are abstracted through this API, which means they can be accessed using the exact same method calls.

>>> print android_dev.get_capability("is_android")
true

Once a device is no longer needed, it should be released to avoid memory leaks.

>>> android_tab_dev = wurfl.parse_useragent(android)
>>> android_tab_dev.release()
>>> android_tab_dev.get_all_capabilities()
Traceback (most recent call last):
AssertionError: This handle was released!

Here is an example program to get started using InFuze for Python:

from pywurfl.wurfl import Wurfl
WURFL = Wurfl("/usr/share/wurfl/wurfl-eval.xml")

dev = WURFL.parse_useragent("Mozilla/5.0 (Linux; Android 4.4; Nexus 5 Build/KRT16M) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/30.0.0.0 Mobile Safari/537.36")

# Get deviceid
print(dev.id)

# Get one capability 
print(dev.get_capability("is_mobile"))

# Get many capabilities
print(dev.get_capabilities(["brand_name", "model_name"]))

# Get all capabilities
dev.get_all_capabilities()

# Release the device
dev.release()

License

2017 ScientiaMobile Incorporated All Rights Reserved.

NOTICE: All information contained herein is, and remains the property of ScientiaMobile Incorporated and its suppliers, if any. The intellectual and technical concepts contained herein are proprietary to ScientiaMobile Incorporated and its suppliers and may be covered by U.S. and Foreign Patents, patents in process, and are protected by trade secret or copyright law. Dissemination of this information or reproduction of this material is strictly forbidden unless prior written permission is obtained from ScientiaMobile Incorporated.include('layouts.partials.license-footer')